osborn 0.9.147 → 0.9.149

package/dist/claude-llm.js

@@ -332,9 +332,13 @@ export const NAMED_AGENTS = {
             'Flag any change that could break existing callers, even if no test currently covers it.',
             '',
             '## How to work',
+            '0. **Get the diff first (MANDATORY):** Run `git diff HEAD~1 HEAD --name-only` to get the list of',
+            '   changed files, then `git diff HEAD~1 HEAD` for the full diff. Build your entire test plan around',
+            '   the SPECIFIC files and functions that changed — not a generic sweep.',
             '1. Identify the correct test / build command from package.json, Makefile, or the task brief.',
             '2. Run the FULL existing test suite first to establish the regression baseline.',
-            '3. Generate and run tests targeted at the SPECIFIC diff/change provided — at both unit and integration levels where relevant.',
+            '3. Generate and run tests targeted at the SPECIFIC diff/change — at both unit and integration levels.',
+            '   Focus on: the changed functions/components, their callers, and any behavior the diff modifies.',
             '4. Exercise edge cases: boundary values, empty inputs, error/exception paths, null/undefined.',
             '5. Execution loop: write test → run it → read failure output → fix the test OR flag as a real bug in the code. Do NOT silently paper over a real defect.',
             '6. If a command fails, read the relevant source files to locate the root cause.',
@@ -440,7 +444,19 @@ export const NAMED_AGENTS = {
             'You must NEVER write code, config, or source files (.ts, .js, .json, .env, etc.) — the write gate',
             'enforces this at the system level and will deny any such attempt.',
             '',
+            '## Backward-compatibility mandate',
+            'For every change, explicitly verify:',
+            '- No existing exported function signature changed (parameter count/order/type, return type)',
+            '- No existing data-channel message schema changed (field names, types, required fields)',
+            '- No existing API endpoint behavior changed silently',
+            '- No existing UI prop interface changed in a breaking way',
+            '- Existing callers and consumers of the changed code still work',
+            'Tag any violation BLOCKER — silent compat breaks are the hardest bugs to catch after the fact.',
+            '',
             '## How to work',
+            '0. **Get the diff first (MANDATORY):** Run `git diff HEAD~1 HEAD --stat` then `git diff HEAD~1 HEAD`.',
+            '   Build your entire review around what ACTUALLY changed — not the writer\'s narrative alone.',
+            '   If the task provides a diff, still verify it matches git history.',
             '1. Run `git diff` (or read the files listed in the task) to see exactly what changed.',
             '2. Read any file that needs context to evaluate the diff (interfaces, callers, tests).',
             '3. Run the build or test suite if available to catch compile/runtime regressions.',
@@ -552,6 +568,10 @@ export class ClaudeLLM extends llm.LLM {
     // No JSONL replay after the first cold start.
     #persistentQuery = null;
     #messageChannel = null;
+    // Read-along tracking — per-turn message ID and chunk counter for TTS highlighting
+    #currentTurnMessageId = null;
+    #currentTurnChunkIndex = 0;
+    #currentTurnChunks = [];
     #backgroundConsumerRunning = false;
     // Active queries — multiple can be running (SDK queues them internally).
     // We keep ALL references so interrupt() can stop whatever is currently executing.
@@ -1106,22 +1126,41 @@ export class ClaudeLLM extends llm.LLM {
                 }
                 // Stream assistant text → tts_say events
                 if (msg.type === 'assistant' && msg.message?.content) {
+                    // Assign a stable messageId for this turn (first block sets it, rest reuse)
+                    if (!this.#currentTurnMessageId) {
+                        this.#currentTurnMessageId = crypto.randomUUID();
+                        this.#currentTurnChunkIndex = 0;
+                        this.#currentTurnChunks = [];
+                    }
+                    const turnMessageId = this.#currentTurnMessageId;
                     for (const block of msg.message.content) {
                         if (block.type === 'text' && block.text) {
-                            callbacks.eventEmitter.emit('assistant_text', { text: block.text });
+                            const chunkIndex = this.#currentTurnChunkIndex;
+                            callbacks.eventEmitter.emit('assistant_text', { text: block.text, messageId: turnMessageId, chunkIndex });
                             const ttsChunk = stripMarkdownForTTS(block.text);
                             if (ttsChunk.trim()) {
+                                this.#currentTurnChunks.push(ttsChunk);
+                                this.#currentTurnChunkIndex++;
                                 console.log(`🔊 TTS say (${ttsChunk.length} chars): "${ttsChunk}"`);
-                                callbacks.eventEmitter.emit('tts_say', { text: ttsChunk });
+                                callbacks.eventEmitter.emit('tts_say', { text: ttsChunk, messageId: turnMessageId, chunkIndex });
                             }
                         }
                     }
                 }
                 // Result — marks end of a turn (but we keep consuming for next turn)
                 if (msg.type === 'result') {
+                    const turnMessageId = this.#currentTurnMessageId;
+                    const turnChunks = [...this.#currentTurnChunks];
                     if (msg.result) {
-                        callbacks.eventEmitter.emit('assistant_result', { text: msg.result });
+                        callbacks.eventEmitter.emit('assistant_result', { text: msg.result, messageId: turnMessageId });
                     }
+                    if (turnMessageId && turnChunks.length > 0) {
+                        callbacks.eventEmitter.emit('tts_chunks', { messageId: turnMessageId, chunks: turnChunks });
+                    }
+                    // Reset per-turn state for next turn
+                    this.#currentTurnMessageId = null;
+                    this.#currentTurnChunkIndex = 0;
+                    this.#currentTurnChunks = [];
                     console.log('✅ Claude turn complete (persistent session stays alive)');
                 }
             }
@@ -1158,13 +1197,26 @@ export class ClaudeLLM extends llm.LLM {
             const idxPathReviewer = (this.#sessionId && this.#opts.workingDirectory)
                 ? getIndexPath(this.#sessionId, this.#opts.workingDirectory)
                 : null;
+            // Get the actual diff to give reviewer concrete evidence instead of just the narrative
+            let gitDiff = '';
+            try {
+                const { execSync } = await import('child_process');
+                const diffStat = execSync('git diff HEAD~1 HEAD --stat 2>/dev/null', { cwd: this.#opts.workingDirectory, timeout: 5000 }).toString().trim();
+                const diff = execSync('git diff HEAD~1 HEAD 2>/dev/null', { cwd: this.#opts.workingDirectory, timeout: 5000 }).toString().trim();
+                gitDiff = diffStat ? `\n\n<git_diff_stat>\n${diffStat}\n</git_diff_stat>\n\n<git_diff>\n${diff.slice(0, 6000)}\n</git_diff>` : '';
+            }
+            catch {
+                // non-fatal: if git fails, proceed without diff
+            }
             const prompt = [
                 'Use the reviewer sub-agent to review this writer output for correctness/spec-adherence/obvious bugs.',
+                'The git diff is provided below — use it as the authoritative source of what changed.',
                 'End your reply with exactly `VERDICT: ACCEPT` or `VERDICT: REJECT`.',
                 ...(idxPathReviewer ? [`The session index is at ${idxPathReviewer} — you MUST read it before reviewing.`] : []),
+                gitDiff,
                 '',
                 '<writer_output>',
-                writerOutput.slice(0, 8000),
+                writerOutput.slice(0, 6000),
                 '</writer_output>',
             ].join('\n');
             // Do NOT pass agents here — the reviewer must be review-only and must not
@@ -1854,6 +1906,10 @@ class ClaudeLLMStream extends llm.LLMStream {
             // Run Claude Agent SDK query() and stream results
             let hasOutput = false;
             let fullResponse = ''; // Collect full response for frontend
+            // Per-turn read-along tracking (non-skipTTSQueue path)
+            let streamTurnMessageId = null;
+            let streamTurnChunkIndex = 0;
+            let streamTurnChunks = [];
             // DIRECT MODE OPTIMIZATION: When skipTTSQueue is true, we run the Claude query
             // in the background and return from run() immediately. This is critical because:
             //
@@ -1940,20 +1996,29 @@ class ClaudeLLMStream extends llm.LLMStream {
                     if (sdkRequestId) {
                         this.#eventEmitter.emit('query_request_id', { requestId: sdkRequestId });
                     }
+                    // Assign a stable messageId for this turn (first block sets it, rest reuse)
+                    if (!streamTurnMessageId) {
+                        streamTurnMessageId = crypto.randomUUID();
+                        streamTurnChunkIndex = 0;
+                        streamTurnChunks = [];
+                    }
                     for (const block of message.message.content) {
                         if (block.type === 'text' && block.text) {
                             hasOutput = true;
                             const rawText = block.text;
+                            const chunkIndex = streamTurnChunkIndex;
                             // Emit RAW text to frontend (for chat bubbles with full formatting)
-                            this.#eventEmitter.emit('assistant_text', { text: rawText });
+                            this.#eventEmitter.emit('assistant_text', { text: rawText, messageId: streamTurnMessageId, chunkIndex });
                             // Strip markdown for clean speech
                             const ttsChunk = stripMarkdownForTTS(rawText);
                             if (ttsChunk.trim()) {
+                                streamTurnChunks.push(ttsChunk);
+                                streamTurnChunkIndex++;
                                 if (this.#opts.skipTTSQueue) {
                                     // Direct mode: emit event for session.say() — bypasses LiveKit's
                                     // BufferedTokenStream which causes stuck/delayed/out-of-order audio
                                     console.log(`🔊 TTS say (${ttsChunk.length} chars): "${ttsChunk}"`);
-                                    this.#eventEmitter.emit('tts_say', { text: ttsChunk });
+                                    this.#eventEmitter.emit('tts_say', { text: ttsChunk, messageId: streamTurnMessageId, chunkIndex });
                                 }
                                 else {
                                     // Realtime mode: use LLM stream queue (framework handles TTS)
@@ -1971,7 +2036,15 @@ class ClaudeLLMStream extends llm.LLMStream {
                 if (message.type === 'result' && message.result) {
                     const rawResult = message.result;
                     // Emit RAW result to frontend
-                    this.#eventEmitter.emit('assistant_result', { text: rawResult });
+                    this.#eventEmitter.emit('assistant_result', { text: rawResult, messageId: streamTurnMessageId });
+                    // Emit ordered chunk list for frontend read-along
+                    if (streamTurnMessageId && streamTurnChunks.length > 0) {
+                        this.#eventEmitter.emit('tts_chunks', { messageId: streamTurnMessageId, chunks: streamTurnChunks });
+                    }
+                    // Reset per-turn state
+                    streamTurnMessageId = null;
+                    streamTurnChunkIndex = 0;
+                    streamTurnChunks = [];
                     if (!hasOutput) {
                         hasOutput = true;
                         const ttsText = stripMarkdownForTTS(rawResult);

package/dist/index.js

@@ -2814,6 +2814,8 @@ async function main() {
                 text: data.text,
                 isStreaming: true,
                 agentRole: 'direct',
+                messageId: data.messageId,
+                chunkIndex: data.chunkIndex,
             });
         });
         // Wire up Claude final result - RAW result goes to frontend
@@ -2825,6 +2827,15 @@ async function main() {
                 isStreaming: false,
                 isFinal: true,
                 agentRole: 'direct',
+                messageId: data.messageId,
+            });
+        });
+        // Wire up ordered TTS chunk list — emitted once per turn for read-along
+        directLLM.events.on('tts_chunks', (data) => {
+            sendToFrontend({
+                type: 'tts_chunks',
+                messageId: data.messageId,
+                chunks: data.chunks,
             });
         });
         // Wire up permission requests - sends to frontend for user approval
@@ -3001,6 +3012,15 @@ async function main() {
                             playbackStartedAt = Date.now();
                             console.log(`🔊 [${sayId}] audio first frame out (playbackStarted)`);
                             audioOutputRef.off('playbackStarted', onPlaybackStarted);
+                            // Notify frontend that this TTS chunk is now audibly playing
+                            if (data.messageId != null && data.chunkIndex != null) {
+                                sendToFrontend({
+                                    type: 'tts_chunk_playing',
+                                    messageId: data.messageId,
+                                    chunkIndex: data.chunkIndex,
+                                    text: data.text,
+                                });
+                            }
                         };
                         audioOutputRef.on('playbackStarted', onPlaybackStarted);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osborn",
-  "version": "0.9.147",
+  "version": "0.9.149",
   "description": "Voice AI coding assistant - local agent that connects to Osborn frontend",
   "type": "module",
   "bin": {