verbalcoding 0.2.10 → 0.2.12

package/docs/superpowers/plans/2026-05-13-phase1-streaming-pipeline.md

@@ -0,0 +1,122 @@
+# Phase 1 — Streaming End-to-End Pipeline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Stream the agent's stdout into the TTS pipeline so the first sentence plays seconds before the agent finishes the full reply.
+
+**Architecture:** Today `agent_adapters.mjs::run` waits for the agent process to exit, then `tts_prefetch.mjs::playChunkedTTSWithPrefetch` consumes the final answer. New path: add `app-node/stream_sentencer.mjs` (a stateful sentence-boundary detector over a stdout stream), plumb it into the existing spawn-with-progress branch in `agent_adapters.mjs`, and feed sentences into a new `streaming_tts_queue.mjs` that synthesises and plays in order with abort support.
+
+**Tech Stack:** Node 20 ESM, async stdout chunks, existing `splitForTTS`/`playChunkedTTSWithPrefetch`.
+
+---
+
+## Spec
+
+### Stream sentencer
+
+API:
+```javascript
+const sentencer = createSentencer({ minChars: 40, maxLatencyMs: 800 });
+sentencer.on('sentence', s => ...);
+sentencer.push(chunkText);
+sentencer.flush();
+```
+
+Boundary rules:
+- Terminal punctuation (`.!?。！？…`) followed by whitespace or EOS.
+- Soft boundary on whitespace if buffer ≥ `minChars` and ≥ `maxLatencyMs` since last emit.
+- Strip ANSI and Hermes box glyphs (`╭ ╰ │ ┊`) before emit.
+- Drop `VERBALCODING_PROGRESS:` lines (those belong to the progress channel).
+
+### Adapter changes
+
+- `createAgentAdapter(settings, deps)` accepts `onSentence` callback in deps.
+- Existing spawn-streaming branch (the one that already streams stdout for verbose mode) feeds the sentencer; final `flush()` runs on close.
+
+### Bridge changes
+
+- `main.mjs` builds a `StreamingTTSQueue` per turn when `STREAMING_TTS=1`.
+- Queue: synth-on-arrival, play-in-order, drops further work when the existing barge-in signal aborts.
+- When flag is off, behavior is unchanged.
+
+---
+
+## File Structure
+
+- Create: `app-node/stream_sentencer.mjs`, `app-node/stream_sentencer.test.mjs`.
+- Create: `app-node/streaming_tts_queue.mjs`, `app-node/streaming_tts_queue.test.mjs`.
+- Modify: `app-node/agent_adapters.mjs` — plumb `onSentence` into the spawn-streaming branch.
+- Modify: `app-node/main.mjs` — wire queue.
+- Modify: `.env.example` — `STREAMING_TTS`.
+
+---
+
+## Tasks
+
+### Task 1: Sentencer TDD
+
+- [ ] Write `app-node/stream_sentencer.test.mjs` with five cases:
+  1. Emits on terminal punctuation.
+  2. Holds partial sentences until terminator.
+  3. Strips ANSI before emitting.
+  4. Filters `VERBALCODING_PROGRESS:` lines.
+  5. `flush()` emits residual on close.
+
+- [ ] Verify FAIL: `node --test app-node/stream_sentencer.test.mjs` → module missing.
+
+### Task 2: Implement sentencer
+
+- [ ] Create `app-node/stream_sentencer.mjs`:
+  - `EventEmitter`-backed.
+  - Internal `buffer` string.
+  - On `push`: clean (regex strip ANSI + box chars + drop progress lines), append, scan for terminal punctuation, emit & advance index. If buffer ≥ minChars and elapsed ≥ maxLatencyMs, emit at last whitespace.
+  - On `flush`: emit trimmed residual.
+
+- [ ] Run tests: PASS.
+- [ ] Commit: `feat(streaming): stream sentencer with ANSI/progress filtering`.
+
+### Task 3: Streaming TTS queue TDD
+
+- [ ] Write `app-node/streaming_tts_queue.test.mjs`:
+  1. Synth + play happen in enqueue order.
+  2. Abort signal stops further playback after current.
+
+- [ ] Run, expect FAIL.
+
+### Task 4: Implement queue
+
+- [ ] Create `app-node/streaming_tts_queue.mjs`:
+  - `createStreamingTTSQueue({ synth, play, signal, cleanup })`.
+  - Internal FIFO; single async pump promise; honours `signal.aborted` between awaits; runs cleanup when aborted between synth and play.
+- [ ] Run tests: PASS.
+- [ ] Commit: `feat(streaming): TTS queue with abort support`.
+
+### Task 5: Wire adapter
+
+- [ ] In `agent_adapters.mjs`, accept `onSentence` from deps; build sentencer once per `run()`; feed both stdout and stderr; call `flush()` on close. Wrap existing `emitVerboseProgress` call site — sentences go to a different callback.
+- [ ] Add adapter test using a fake spawn that emits stdout in three chunks; assert sentences arrive in order before the close handler fires.
+- [ ] Commit.
+
+### Task 6: Wire bridge
+
+- [ ] In `main.mjs`, when `STREAMING_TTS=1`:
+  - Build queue with the existing synth/play helpers.
+  - Pass `onSentence: text => queue.enqueue(text)` to adapter.
+  - After adapter returns, await `queue.drain()`; skip the post-run chunked playback path for already-streamed content.
+- [ ] When flag is off, no change.
+- [ ] Commit.
+
+### Task 7: Document
+
+- [ ] Add `STREAMING_TTS=1` to `.env.example` with a short comment.
+- [ ] Add a "Streaming pipeline" subsection to `docs/CONFIGURATION.md`.
+- [ ] Commit.
+
+---
+
+## Self-Review
+
+- Spec covered.
+- No placeholders.
+- Names consistent: `createSentencer`, `createStreamingTTSQueue`, `onSentence`, `STREAMING_TTS`.
+- Risk: TTS providers vary in latency; queue must not block enqueue on slow synth (single pump avoids this).

package/docs/superpowers/plans/2026-05-13-phase10-push-notifications.md

@@ -0,0 +1,152 @@
+# Phase 10 — Push Notification Handoff Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** When a long-running agent task completes while no human is in the voice channel (or after a configurable idle threshold), send a mobile push notification with a 1-line voice summary; tap the notification to rejoin the VC and hear the full reply.
+
+**Architecture:** New `app-node/notify.mjs` with a provider interface (`send(title, body, deepLink)`). Default provider: ntfy.sh (zero-setup, works with iOS/Android apps, supports a `Click` action that opens a URL). Optional providers: Pushover, Discord DM. Trigger heuristic: task elapsed > `NOTIFY_MIN_TASK_MS` (default 60s) AND VC has 0 non-bot listeners OR user enabled `!notify on` for the session.
+
+**Tech Stack:** Node 20 ESM, `fetch`, optional Discord DM via existing `discord.js` client.
+
+---
+
+## Spec
+
+### Provider API
+
+```javascript
+const notifier = createNotifier({ provider: 'ntfy', topic: env.NTFY_TOPIC });
+await notifier.send({
+  title: 'Hermes finished',
+  body: 'Refactor done, 3 files changed, all tests green.',
+  deepLink: 'discord://discord.com/channels/<guild>/<channel>',
+});
+```
+
+### Trigger logic
+
+- Wrap each `agent.run()`; if elapsed > threshold AND `shouldNotify()` returns true, send.
+- `shouldNotify()`:
+  - User toggle `!notify on` → always send.
+  - Or: `getVoiceChannelHumanCount() === 0` → send.
+
+### Body composition
+
+- Use last sentence of sanitized agent answer (short).
+- Truncate to 200 chars.
+- Strip PII (token/api key patterns) via existing `compactProgressText` helper.
+
+### Discord deep link
+
+- Built from guild+channel IDs.
+
+### Privacy
+
+- Notification body never contains code, diffs, or session_id.
+
+---
+
+## File Structure
+
+- Create: `app-node/notify.mjs`, `app-node/notify.test.mjs`.
+- Modify: `app-node/main.mjs` — wrap agent run completion.
+- Modify: `.env.example` — `NOTIFY_PROVIDER`, `NTFY_TOPIC`, `PUSHOVER_USER`, `PUSHOVER_TOKEN`, `NOTIFY_MIN_TASK_MS`.
+
+---
+
+## Tasks
+
+### Task 1: TDD — ntfy provider sends correct payload
+
+- [ ] Step 1: Failing test:
+
+```javascript
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotifier } from './notify.mjs';
+
+test('ntfy provider posts to topic URL with title and body', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push({ url, opts }); return { ok: true, status: 200 }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'verbalcoding-test', fetchImpl });
+  await n.send({ title: 'Done', body: 'All green.', deepLink: 'discord://x' });
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].url, /ntfy\.sh\/verbalcoding-test/);
+  assert.equal(calls[0].opts.headers.Title, 'Done');
+  assert.equal(calls[0].opts.headers.Click, 'discord://x');
+  assert.equal(calls[0].opts.body, 'All green.');
+});
+
+test('shouldNotify true when zero human listeners', async () => {
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl: async () => ({ ok: true }) });
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 10_000, minTaskMs: 1000 }), true);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 100, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000, userOptIn: true }), true);
+});
+
+test('redacts api keys from body', async () => {
+  const calls = [];
+  const fetchImpl = async (u, o) => { calls.push(o); return { ok: true }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl });
+  await n.send({ title: 't', body: 'token=sk-abc123 finished', deepLink: '' });
+  assert.match(calls[0].body, /\[REDACTED\]/);
+  assert.doesNotMatch(calls[0].body, /sk-abc123/);
+});
+```
+
+- [ ] Step 2: Run, expect FAIL.
+
+### Task 2: Implement `notify.mjs`
+
+- [ ] Step 1: Create module:
+
+```javascript
+const SECRET_RE = /\b(?:token|api[_-]?key|password|secret|authorization|bearer|sk-[a-zA-Z0-9_-]+)\b[^\s]*/gi;
+
+function redact(text) {
+  return String(text || '').replace(SECRET_RE, '[REDACTED]');
+}
+
+export function createNotifier({ provider = 'ntfy', topic = '', fetchImpl = globalThis.fetch, ntfyBase = 'https://ntfy.sh' } = {}) {
+  async function send({ title = 'VerbalCoding', body = '', deepLink = '' } = {}) {
+    const safeBody = redact(body).slice(0, 200);
+    if (provider === 'ntfy') {
+      if (!topic) return { skipped: true, reason: 'no topic' };
+      const headers = { Title: title };
+      if (deepLink) headers.Click = deepLink;
+      const res = await fetchImpl(`${ntfyBase}/${encodeURIComponent(topic)}`, {
+        method: 'POST',
+        headers,
+        body: safeBody,
+      });
+      return { ok: !!res?.ok, status: res?.status };
+    }
+    if (provider === 'noop') return { ok: true };
+    throw new Error(`unknown notify provider ${provider}`);
+  }
+
+  function shouldNotify({ humanCount = 0, taskMs = 0, minTaskMs = 60_000, userOptIn = false } = {}) {
+    if (taskMs < minTaskMs) return false;
+    if (userOptIn) return true;
+    return humanCount === 0;
+  }
+
+  return { send, shouldNotify };
+}
+```
+
+- [ ] Step 2: Run tests, expect PASS.
+- [ ] Step 3: Commit.
+
+### Task 3: Wire into `main.mjs`
+
+- [ ] Step 1: After each agent run, check `shouldNotify`, build deep link, call `send`.
+- [ ] Step 2: Helper `getVoiceChannelHumanCount(channel)` reads voice state.
+- [ ] Step 3: Add `!notify on|off` per-channel toggle.
+- [ ] Step 4: Commit.
+
+### Task 4: Document
+
+- [ ] Step 1: `.env.example` + `docs/USAGE.md` notification section.
+- [ ] Step 2: Commit.

package/docs/superpowers/plans/2026-05-13-phase2-agent-adapters.md

@@ -0,0 +1,242 @@
+# Phase 2 — Agent-Agnostic Adapter Completion Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Round out `agent_adapters.mjs` so VerbalCoding works first-class with Aider and Cursor CLI, and auto-detects whichever agent is installed on the host.
+
+**Architecture:** Extend the existing `buildAgentSettings()` defaults table in `app-node/agent_adapters.mjs`. Add a new `detectInstalledAgents()` helper in `app-node/agent_detect.mjs` that uses `which`/`command -v` to probe binaries, and wire it into `vc setup` + `vc doctor` + `vc status`. Add adapter quirks for Aider (`--no-pretty`, stdin prompt) and Cursor CLI (`cursor-agent`).
+
+**Tech Stack:** Node 20 ESM, `node:child_process`, `node --test` (existing test runner).
+
+---
+
+## Spec
+
+### Adapter additions
+
+- **Aider** — `aider --no-pretty --yes-always --message <prompt>`; no built-in session resume via flag, but supports `.aider.chat.history.md` for history. Skip session resume in adapter (treat each turn as fresh w/ project context). Sanitize Aider's "Tokens:" footer.
+- **Cursor CLI** — `cursor-agent --prompt <prompt> --print` (Cursor's CLI flags vary by version; default to `cursor-agent` binary).
+
+### Auto-detection
+
+- `detectInstalledAgents(env, { which })` returns ordered list of `{ backend, label, command, present: boolean, version?: string }`.
+- Probe order: `hermes`, `claude`, `codex`, `gemini`, `opencode`, `openclaw`, `aider`, `cursor-agent`.
+- Called by `vc setup` to auto-pick a default when `AGENT_BACKEND` is unset.
+- Called by `vc doctor` to display which agents are reachable.
+
+### CLI surface
+
+- `vc setup` — show detected agents and ask user to pick (default = first present).
+- `vc doctor` — section "Agent backends" lists present/missing.
+- `vc status` — show current `AGENT_BACKEND` + whether the binary resolves.
+
+---
+
+## File Structure
+
+- Create: `app-node/agent_detect.mjs` — `detectInstalledAgents`, `probeAgentBinary`.
+- Create: `app-node/agent_detect.test.mjs` — unit tests with injected `which`.
+- Modify: `app-node/agent_adapters.mjs` (lines ~208–276) — add `aider` and `cursor` entries to `defaults` in `buildAgentSettings`.
+- Modify: `app-node/agent_contract.mjs` — extend capability flags (`supportsStdinPrompt`, `supportsResume`).
+- Modify: `scripts/install.mjs` (or wherever `vc setup` lives — find via grep) — call `detectInstalledAgents` when prompting for backend.
+- Modify: `scripts/doctor.mjs` — render detection report.
+- Modify: `.env.example` — document `AIDER_COMMAND`, `CURSOR_COMMAND`.
+- Modify: `README.md` — agent list (after Phase 2 lands, full README reframe is its own task).
+
+---
+
+## Tasks
+
+### Task 1: Failing test for `detectInstalledAgents`
+
+**Files:** Create `app-node/agent_detect.test.mjs`.
+
+- [ ] Step 1: Write failing test
+
+```javascript
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { detectInstalledAgents } from './agent_detect.mjs';
+
+test('detectInstalledAgents marks present when which resolves', async () => {
+  const fakeWhich = async (bin) => bin === 'hermes' ? '/usr/local/bin/hermes' : null;
+  const result = await detectInstalledAgents({}, { which: fakeWhich });
+  const hermes = result.find(r => r.backend === 'hermes');
+  assert.equal(hermes.present, true);
+  assert.equal(hermes.command.includes('hermes'), true);
+  const claude = result.find(r => r.backend === 'claude');
+  assert.equal(claude.present, false);
+});
+
+test('detectInstalledAgents includes aider and cursor', async () => {
+  const fakeWhich = async () => null;
+  const result = await detectInstalledAgents({}, { which: fakeWhich });
+  const backends = result.map(r => r.backend);
+  assert.ok(backends.includes('aider'));
+  assert.ok(backends.includes('cursor'));
+});
+
+test('detectInstalledAgents honors env overrides for command', async () => {
+  const fakeWhich = async (bin) => bin === 'aider' ? '/opt/aider' : null;
+  const result = await detectInstalledAgents({ AIDER_COMMAND: 'aider --foo' }, { which: fakeWhich });
+  const aider = result.find(r => r.backend === 'aider');
+  assert.equal(aider.command, 'aider --foo');
+});
+```
+
+- [ ] Step 2: Run test, expect failure
+
+```bash
+node --test app-node/agent_detect.test.mjs
+```
+Expected: FAIL — `Cannot find module './agent_detect.mjs'`.
+
+### Task 2: Implement `agent_detect.mjs`
+
+**Files:** Create `app-node/agent_detect.mjs`.
+
+- [ ] Step 1: Implement minimal module
+
+```javascript
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileP = promisify(execFile);
+
+const PROBES = [
+  { backend: 'hermes', bin: 'hermes', defaultCommand: 'hermes chat -Q -q', envCommand: 'HERMES_COMMAND' },
+  { backend: 'claude', bin: 'claude', defaultCommand: 'claude -p', envCommand: 'CLAUDE_COMMAND' },
+  { backend: 'codex', bin: 'codex', defaultCommand: 'codex exec', envCommand: 'CODEX_COMMAND' },
+  { backend: 'gemini', bin: 'gemini', defaultCommand: 'gemini -p', envCommand: 'GEMINI_COMMAND' },
+  { backend: 'opencode', bin: 'opencode', defaultCommand: 'opencode run', envCommand: 'OPENCODE_COMMAND' },
+  { backend: 'openclaw', bin: 'openclaw', defaultCommand: 'openclaw run', envCommand: 'OPENCLAW_COMMAND' },
+  { backend: 'aider', bin: 'aider', defaultCommand: 'aider --no-pretty --yes-always --message', envCommand: 'AIDER_COMMAND' },
+  { backend: 'cursor', bin: 'cursor-agent', defaultCommand: 'cursor-agent --print --prompt', envCommand: 'CURSOR_COMMAND' },
+];
+
+async function defaultWhich(bin) {
+  try {
+    const { stdout } = await execFileP('which', [bin]);
+    const p = stdout.trim();
+    return p || null;
+  } catch { return null; }
+}
+
+export async function detectInstalledAgents(env = process.env, { which = defaultWhich } = {}) {
+  const results = await Promise.all(PROBES.map(async (p) => {
+    const path = await which(p.bin);
+    return {
+      backend: p.backend,
+      label: backendLabel(p.backend),
+      command: env[p.envCommand] || p.defaultCommand,
+      bin: p.bin,
+      path: path || null,
+      present: Boolean(path),
+    };
+  }));
+  return results;
+}
+
+function backendLabel(backend) {
+  return { hermes: 'Hermes Agent', claude: 'Claude Code', codex: 'Codex', gemini: 'Gemini', opencode: 'OpenCode', openclaw: 'OpenClaw', aider: 'Aider', cursor: 'Cursor CLI' }[backend] || backend;
+}
+```
+
+- [ ] Step 2: Run tests
+
+```bash
+node --test app-node/agent_detect.test.mjs
+```
+Expected: PASS.
+
+- [ ] Step 3: Commit
+
+```bash
+git add app-node/agent_detect.mjs app-node/agent_detect.test.mjs
+git commit -m "feat(adapters): add agent_detect for auto-detection across 8 backends"
+```
+
+### Task 3: Add Aider + Cursor defaults to `buildAgentSettings`
+
+**Files:** Modify `app-node/agent_adapters.mjs` defaults table (~lines 211–260).
+
+- [ ] Step 1: Add entries
+
+Inside the `defaults` object, insert:
+
+```javascript
+    aider: {
+      label: 'Aider',
+      command: env.AIDER_COMMAND || 'aider --no-pretty --yes-always --message',
+      sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'aider'),
+      supportsHermesSession: false,
+    },
+    cursor: {
+      label: 'Cursor CLI',
+      command: env.CURSOR_COMMAND || 'cursor-agent --print --prompt',
+      sessionFile: env.AGENT_SESSION_FILE || path.join(root, '.agent-sessions', 'cursor'),
+      supportsHermesSession: false,
+    },
+```
+
+- [ ] Step 2: Add a corresponding test to `app-node/agent_adapters.test.mjs`
+
+```javascript
+test('buildAgentSettings supports AGENT_BACKEND=aider', () => {
+  const s = buildAgentSettings({ ROOT: '/tmp/r', env: { AGENT_BACKEND: 'aider' } });
+  assert.equal(s.backend, 'aider');
+  assert.equal(s.label, 'Aider');
+  assert.match(s.command, /aider/);
+});
+
+test('buildAgentSettings supports AGENT_BACKEND=cursor', () => {
+  const s = buildAgentSettings({ ROOT: '/tmp/r', env: { AGENT_BACKEND: 'cursor' } });
+  assert.equal(s.backend, 'cursor');
+  assert.match(s.command, /cursor-agent/);
+});
+```
+
+- [ ] Step 3: Run
+
+```bash
+node --test app-node/agent_adapters.test.mjs
+```
+Expected: PASS.
+
+- [ ] Step 4: Commit
+
+```bash
+git add app-node/agent_adapters.mjs app-node/agent_adapters.test.mjs
+git commit -m "feat(adapters): first-class Aider and Cursor CLI backends"
+```
+
+### Task 4: Wire detection into `vc setup`
+
+**Files:** Find via `grep -nR "AGENT_BACKEND" scripts/install.mjs scripts/cli.mjs` first, then modify the relevant prompt logic.
+
+- [ ] Step 1: Use `detectInstalledAgents` to default the picker, and label entries as `present`/`missing`.
+- [ ] Step 2: Add a test for the picker function (extracted as pure function for testability).
+- [ ] Step 3: Commit:
+
+```bash
+git commit -m "feat(setup): auto-detect installed agents and default the picker"
+```
+
+### Task 5: Wire detection into `vc doctor`
+
+- [ ] Step 1: Render a new "Agent backends" section in doctor output.
+- [ ] Step 2: Commit.
+
+### Task 6: Document in `.env.example` and `docs/USAGE.md`
+
+- [ ] Step 1: Add `AIDER_COMMAND` and `CURSOR_COMMAND` to `.env.example` with comments.
+- [ ] Step 2: Update `docs/USAGE.md` agent table.
+- [ ] Step 3: Commit.
+
+---
+
+## Self-Review
+
+- Spec coverage: detection ✓, Aider ✓, Cursor ✓, setup wiring ✓, doctor wiring ✓, docs ✓.
+- No placeholders.
+- Types consistent (`backend` strings match across `agent_adapters.mjs` and `agent_detect.mjs`).

package/docs/superpowers/plans/2026-05-13-phase6-smart-progress.md

@@ -0,0 +1,172 @@
+# Phase 6 — Smart Progress Summarization Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Replace pattern-matched progress narration ("editing files routes.ts, server.ts") with semantic summaries ("wiring the new endpoint into the router").
+
+**Architecture:** Add a `SmartProgressSummarizer` that buffers raw progress events for `summaryWindowMs` (default 4000ms) and asks a small LLM (Groq llama-3.1-8b or local ollama) to compress them into one human sentence. Fall back to the existing regex labels on summarizer failure/timeout/no-API-key.
+
+**Tech Stack:** Node 20 ESM, `fetch` (Groq OpenAI-compatible API by default).
+
+---
+
+## Spec
+
+### API
+
+```javascript
+const summarizer = createSmartProgressSummarizer({
+  apiKey: env.SMART_PROGRESS_API_KEY || env.GROQ_API_KEY,
+  baseUrl: env.SMART_PROGRESS_BASE_URL || 'https://api.groq.com/openai/v1',
+  model: env.SMART_PROGRESS_MODEL || 'llama-3.1-8b-instant',
+  windowMs: 4000,
+  language: 'en' | 'ko',
+  fallback: rawEvent => rawEvent,
+});
+summarizer.ingest(rawEvent);
+summarizer.on('summary', text => ...);
+```
+
+### Behavior
+
+- Buffer events for `windowMs`; when window expires OR buffer hits 8 events, request a summary.
+- Prompt: "Summarize what the coding agent is doing into one short sentence ({language}). Events: ..."
+- 1.5s timeout — fall through to fallback if exceeded.
+- Cache identical event windows for 60s (dedupe back-to-back identical narration).
+- Disabled when no API key — pure fallback to current regex events.
+
+### Integration
+
+- `progress_speech.mjs` already handles narration cadence; add `summarizer` upstream.
+- Voice toggleable: `!smart-progress on|off`.
+
+---
+
+## File Structure
+
+- Create: `app-node/smart_progress.mjs`, `app-node/smart_progress.test.mjs`.
+- Modify: `app-node/progress_speech.mjs` — inject summarizer.
+- Modify: `app-node/main.mjs` — wire toggle.
+- Modify: `.env.example` — new env keys.
+
+---
+
+## Tasks
+
+### Task 1: TDD — fallback when no API key
+
+- [ ] Step 1: Write failing test:
+
+```javascript
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createSmartProgressSummarizer } from './smart_progress.mjs';
+
+test('falls back to raw events when no apiKey', async () => {
+  const out = [];
+  const s = createSmartProgressSummarizer({ windowMs: 10 });
+  s.on('summary', t => out.push(t));
+  s.ingest('reading files routes.ts');
+  s.ingest('editing files routes.ts');
+  await new Promise(r => setTimeout(r, 30));
+  assert.ok(out.includes('reading files routes.ts'));
+  assert.ok(out.includes('editing files routes.ts'));
+});
+```
+
+- [ ] Step 2: Run, expect FAIL.
+
+### Task 2: Implement minimal summarizer (fallback path only)
+
+- [ ] Step 1: Create `app-node/smart_progress.mjs`:
+
+```javascript
+import { EventEmitter } from 'node:events';
+
+export function createSmartProgressSummarizer({
+  apiKey = '',
+  baseUrl = 'https://api.groq.com/openai/v1',
+  model = 'llama-3.1-8b-instant',
+  windowMs = 4000,
+  language = 'en',
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 1500,
+  cacheMs = 60_000,
+} = {}) {
+  const ee = new EventEmitter();
+  let buffer = [];
+  let timer = null;
+  const cache = new Map();
+
+  function flush() {
+    timer = null;
+    const events = buffer; buffer = [];
+    if (!events.length) return;
+    if (!apiKey) { for (const e of events) ee.emit('summary', e); return; }
+    summarize(events).then(text => ee.emit('summary', text || events[events.length - 1])).catch(() => { for (const e of events) ee.emit('summary', e); });
+  }
+
+  async function summarize(events) {
+    const key = events.join('|');
+    const cached = cache.get(key);
+    if (cached && Date.now() - cached.t < cacheMs) return cached.text;
+    const ctl = new AbortController();
+    const to = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const r = await fetchImpl(`${baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+        signal: ctl.signal,
+        body: JSON.stringify({
+          model,
+          temperature: 0.2,
+          max_tokens: 40,
+          messages: [
+            { role: 'system', content: `Summarize a coding agent's recent actions in one short ${language === 'ko' ? 'Korean' : 'English'} sentence. No file paths unless essential. No quotes.` },
+            { role: 'user', content: events.join('\n') },
+          ],
+        }),
+      });
+      const data = await r.json();
+      const text = (data?.choices?.[0]?.message?.content || '').trim();
+      cache.set(key, { text, t: Date.now() });
+      return text;
+    } finally { clearTimeout(to); }
+  }
+
+  return {
+    on: (e, fn) => ee.on(e, fn),
+    ingest(event) {
+      if (!event) return;
+      buffer.push(String(event));
+      if (buffer.length >= 8) { clearTimeout(timer); flush(); return; }
+      if (!timer) timer = setTimeout(flush, windowMs);
+    },
+  };
+}
+```
+
+- [ ] Step 2: Run, expect PASS.
+- [ ] Step 3: Commit.
+
+### Task 3: TDD — calls fetch with apiKey
+
+- [ ] Step 1: Write test that injects fake fetch and asserts the request body.
+- [ ] Step 2: Run, expect PASS (implementation already supports this).
+- [ ] Step 3: Commit.
+
+### Task 4: TDD — timeout falls back to last raw event
+
+- [ ] Step 1: Inject a fetch that never resolves; assert fallback after `timeoutMs`.
+- [ ] Step 2: Commit.
+
+### Task 5: Wire into `progress_speech.mjs`
+
+- [ ] Step 1: Read existing module to find narration entry; pipe summaries through summarizer when enabled.
+- [ ] Step 2: Add `!smart-progress` toggle parsed in `discord_text.mjs`.
+- [ ] Step 3: Commit.
+
+### Task 6: Document
+
+- [ ] Step 1: `.env.example` — `SMART_PROGRESS_API_KEY`, `SMART_PROGRESS_MODEL`.
+- [ ] Step 2: Commit.