lattice-orchestrator 0.7.0

package/dist/services/walkthrough-service.js

@@ -0,0 +1,1112 @@
+/**
+ * WalkthroughService - Generates AI-narrated walkthroughs from session data
+ *
+ * Extracts Edit/Write tool calls from a session and uses Claude to create
+ * a narrative explanation of the changes with Code Hike syntax highlighting.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { highlight } from 'codehike/code';
+import * as Diff from 'diff';
+import { SessionInfoService } from './sessions/session-info-service.js';
+import { ConfigService } from './infrastructure/config-service.js';
+import { createLogger } from './infrastructure/logger.js';
+const logger = createLogger('WalkthroughService');
+/**
+ * Validate a generated walkthrough for quality and completeness.
+ * Returns errors (must fix) and warnings (should consider).
+ */
+export function validateWalkthrough(walkthrough) {
+    const errors = [];
+    const warnings = [];
+    // Type guard
+    if (!walkthrough || typeof walkthrough !== 'object') {
+        return { passed: false, errors: ['Walkthrough is not a valid object'], warnings: [] };
+    }
+    const wt = walkthrough;
+    // Required top-level fields
+    if (!wt.title || typeof wt.title !== 'string') {
+        errors.push('Missing or invalid title');
+    }
+    if (!wt.summary || typeof wt.summary !== 'string') {
+        errors.push('Missing or invalid summary');
+    }
+    if (!wt.phases || !Array.isArray(wt.phases)) {
+        errors.push('Missing or invalid phases array');
+        return { passed: false, errors, warnings };
+    }
+    // Count code blocks and collect files with code
+    const filesWithCode = new Set();
+    let totalCodeBlocks = 0;
+    let codeBlocksMissingLinkedPhrases = 0;
+    let codeBlocksMissingContext = 0;
+    for (const phase of wt.phases) {
+        if (!phase.name || typeof phase.name !== 'string') {
+            errors.push('Phase missing name');
+            continue;
+        }
+        if (!phase.keyMoments || !Array.isArray(phase.keyMoments)) {
+            warnings.push(`Phase "${phase.name}" has no keyMoments`);
+            continue;
+        }
+        for (const moment of phase.keyMoments) {
+            if (!moment.code || !Array.isArray(moment.code))
+                continue;
+            for (const code of moment.code) {
+                totalCodeBlocks++;
+                const file = code.file;
+                if (file)
+                    filesWithCode.add(file);
+                // Check required fields
+                if (!code.linkedPhrases || !Array.isArray(code.linkedPhrases) || code.linkedPhrases.length === 0) {
+                    codeBlocksMissingLinkedPhrases++;
+                }
+                if (!code.contextBefore && !code.contextAfter) {
+                    codeBlocksMissingContext++;
+                }
+            }
+        }
+    }
+    // Minimum code block requirement
+    if (totalCodeBlocks < 5) {
+        errors.push(`Only ${totalCodeBlocks} code blocks - need at least 5 to show meaningful changes`);
+    }
+    // Check linkedPhrases coverage
+    if (codeBlocksMissingLinkedPhrases > 0) {
+        const pct = Math.round((codeBlocksMissingLinkedPhrases / totalCodeBlocks) * 100);
+        if (pct > 50) {
+            errors.push(`${codeBlocksMissingLinkedPhrases}/${totalCodeBlocks} code blocks (${pct}%) missing linkedPhrases`);
+        }
+        else if (pct > 20) {
+            warnings.push(`${codeBlocksMissingLinkedPhrases}/${totalCodeBlocks} code blocks missing linkedPhrases`);
+        }
+    }
+    // Check context coverage
+    if (codeBlocksMissingContext > 0) {
+        const pct = Math.round((codeBlocksMissingContext / totalCodeBlocks) * 100);
+        if (pct > 50) {
+            warnings.push(`${codeBlocksMissingContext}/${totalCodeBlocks} code blocks missing context`);
+        }
+    }
+    // Check outcome section
+    const outcome = wt.outcome;
+    if (!outcome) {
+        errors.push('Missing outcome section');
+    }
+    else {
+        const filesChanged = outcome.filesChanged;
+        if (!filesChanged || !Array.isArray(filesChanged) || filesChanged.length === 0) {
+            errors.push('outcome.filesChanged is empty or missing');
+        }
+        else {
+            // Check that files in filesChanged have code blocks
+            const missingCodeFiles = [];
+            for (const file of filesChanged) {
+                // Check both full path and just filename
+                const hasCode = filesWithCode.has(file) ||
+                    Array.from(filesWithCode).some(f => f.endsWith(file) || file.endsWith(f.split('/').pop() || ''));
+                if (!hasCode) {
+                    missingCodeFiles.push(file);
+                }
+            }
+            if (missingCodeFiles.length > 0) {
+                const pct = Math.round((missingCodeFiles.length / filesChanged.length) * 100);
+                if (pct > 30) {
+                    warnings.push(`${missingCodeFiles.length}/${filesChanged.length} files in filesChanged have no code blocks: ${missingCodeFiles.slice(0, 3).join(', ')}${missingCodeFiles.length > 3 ? '...' : ''}`);
+                }
+            }
+        }
+        // Check that linesAdded/linesRemoved are reasonable (not obviously fake)
+        const linesAdded = outcome.linesAdded;
+        const linesRemoved = outcome.linesRemoved;
+        if (linesAdded !== undefined && linesRemoved !== undefined) {
+            // If claimed stats are very round numbers, flag as potentially fake
+            if (linesAdded % 100 === 0 && linesRemoved % 100 === 0 && linesAdded > 500) {
+                warnings.push(`Line stats (${linesAdded}/${linesRemoved}) are suspiciously round - verify accuracy`);
+            }
+        }
+    }
+    return {
+        passed: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Fix linkedPhrase line numbers by finding where phrases actually appear in code.
+ * LLMs often produce off-by-one errors when counting lines.
+ * This function scans the code and corrects the line numbers.
+ */
+export function fixLinkedPhraseLines(walkthrough) {
+    if (!walkthrough || typeof walkthrough !== 'object')
+        return walkthrough;
+    const wt = walkthrough;
+    if (!wt.phases || !Array.isArray(wt.phases))
+        return walkthrough;
+    for (const phase of wt.phases) {
+        if (!phase.keyMoments || !Array.isArray(phase.keyMoments))
+            continue;
+        for (const moment of phase.keyMoments) {
+            if (!moment.code || !Array.isArray(moment.code))
+                continue;
+            for (const code of moment.code) {
+                const linkedPhrases = code.linkedPhrases;
+                if (!linkedPhrases || !Array.isArray(linkedPhrases))
+                    continue;
+                // Get the code content - prefer 'after', fall back to content from Write
+                const codeContent = (code.after || code.content || '');
+                if (!codeContent)
+                    continue;
+                const codeLines = codeContent.split('\n');
+                for (const lp of linkedPhrases) {
+                    const phrase = lp.phrase;
+                    if (!phrase)
+                        continue;
+                    // Find which line(s) actually contain this phrase
+                    const matchingLines = [];
+                    for (let i = 0; i < codeLines.length; i++) {
+                        if (codeLines[i].includes(phrase)) {
+                            matchingLines.push(i + 1); // 1-indexed
+                        }
+                    }
+                    if (matchingLines.length > 0) {
+                        // Update the lines spec
+                        if (matchingLines.length === 1) {
+                            lp.lines = String(matchingLines[0]);
+                        }
+                        else {
+                            // If phrase spans multiple lines or appears multiple times, use range
+                            const min = Math.min(...matchingLines);
+                            const max = Math.max(...matchingLines);
+                            lp.lines = min === max ? String(min) : `${min}:${max}`;
+                        }
+                    }
+                    // If phrase not found, leave original lines (might be in contextBefore/After)
+                }
+            }
+        }
+    }
+    return walkthrough;
+}
+// ============================================================================
+// SCHEMA & PROMPTS
+// ============================================================================
+const WALKTHROUGH_SCHEMA = `
+{
+  "title": "string - A concise title for this set of changes",
+  "summary": "string - 1-2 sentence overview of what was accomplished",
+
+  "context": {
+    "problem": "string - What was the user trying to achieve? What was broken, missing, or needed improvement?",
+    "priorState": "string - How did things work before? Describe the user experience, code flow, or system behavior.",
+    "approach": "string - High-level summary of the solution approach before diving into details"
+  },
+
+  "orientation": {
+    "narrative": "string - A brief tour of the relevant parts of the codebase BEFORE any changes. Help the reader understand where we're working.",
+    "keyFiles": [
+      {
+        "file": "string - relative file path",
+        "role": "string - what this file does in the system"
+      }
+    ]
+  },
+
+  "sections": [
+    {
+      "heading": "string - Conceptual heading (not a filename)",
+      "narrative": "string - Explanation of this part of the changes. Write in first person as Claude. Use phrases that reference specific code elements.",
+      "linkedPhrases": [
+        {
+          "phrase": "string - exact text from narrative to make interactive (underlined, hoverable)",
+          "focusLines": "string - lines in the 'after' code to highlight on hover, e.g. '3:5' or '7'",
+          "explanation": "string (optional) - tooltip to show on hover"
+        }
+      ],
+      "file": "string - relative file path",
+      "language": "string - programming language (tsx, typescript, python, etc.)",
+      "before": {
+        "description": "string - Brief description of what the code looked like before",
+        "code": "string - The code BEFORE the change (use // !focus and // !mark annotations)"
+      },
+      "after": {
+        "description": "string - Brief description of what changed",
+        "code": "string - The code AFTER the change (use // !focus and // !mark annotations)"
+      }
+    }
+  ],
+
+  "systemFlow": {
+    "description": "string - How the pieces work together after the changes",
+    "components": ["string - list of key components/files involved and their roles"]
+  }
+}
+`;
+// Language mapping for Code Hike
+const LANG_MAP = {
+    tsx: 'tsx',
+    typescript: 'typescript',
+    ts: 'typescript',
+    javascript: 'javascript',
+    js: 'javascript',
+    jsx: 'jsx',
+    python: 'python',
+    py: 'python',
+    bash: 'bash',
+    sh: 'bash',
+    shell: 'bash',
+    json: 'json',
+    css: 'css',
+    html: 'html',
+    markdown: 'markdown',
+    md: 'markdown',
+    sql: 'sql',
+    yaml: 'yaml',
+    yml: 'yaml',
+};
+// ============================================================================
+// SERVICE
+// ============================================================================
+export class WalkthroughService {
+    historyReader;
+    client = null;
+    constructor(historyReader) {
+        this.historyReader = historyReader;
+    }
+    /**
+     * Pre-compute all file change data for a session.
+     * This data is passed to the skill prompt so the model doesn't need to query the DB.
+     * @param sessionId - The session to precompute data for
+     * @param scope - Optional scope with editIndices and writeIndices to filter changes
+     */
+    async precomputeWalkthroughData(sessionId, scope) {
+        logger.info('Pre-computing walkthrough data', { sessionId, hasScope: !!scope });
+        const sessionInfo = SessionInfoService.getInstance();
+        // Get file changes from database (returns camelCase props)
+        let fileChanges = sessionInfo.getFileChanges(sessionId);
+        // If scope provided, filter to only the specified indices
+        if (scope?.editIndices || scope?.writeIndices) {
+            const editIndices = new Set(scope.editIndices || []);
+            const writeIndices = new Set(scope.writeIndices || []);
+            // File changes are ordered by ID, which corresponds to the indices
+            // We need to track edit and write indices separately
+            let editIdx = 0;
+            let writeIdx = 0;
+            fileChanges = fileChanges.filter(change => {
+                if (change.toolName === 'Edit') {
+                    const include = editIndices.has(editIdx);
+                    editIdx++;
+                    return include;
+                }
+                else {
+                    const include = writeIndices.has(writeIdx);
+                    writeIdx++;
+                    return include;
+                }
+            });
+            logger.info('Filtered file changes by scope', {
+                originalCount: sessionInfo.getFileChanges(sessionId).length,
+                filteredCount: fileChanges.length,
+                editIndicesCount: editIndices.size,
+                writeIndicesCount: writeIndices.size,
+            });
+        }
+        // Get turn summaries from database (returns snake_case props)
+        const turns = await sessionInfo.getTurns(sessionId);
+        // Get session insights
+        const insights = await sessionInfo.getInsights(sessionId);
+        // Group changes by file
+        const fileMap = new Map();
+        let totalLinesAdded = 0;
+        let totalLinesRemoved = 0;
+        for (const change of fileChanges) {
+            const relativePath = change.filePath
+                .replace(/^\/home\/jason\/(claudia|cui-custom)\//, '')
+                .replace(/^\/home\/jason\//, '~/');
+            if (!fileMap.has(change.filePath)) {
+                fileMap.set(change.filePath, {
+                    path: change.filePath,
+                    relativePath,
+                    turnNumbers: [],
+                    totalEdits: 0,
+                    totalWrites: 0,
+                    changes: [],
+                });
+            }
+            const fileData = fileMap.get(change.filePath);
+            // Track turn numbers
+            if (!fileData.turnNumbers.includes(change.turnNumber)) {
+                fileData.turnNumbers.push(change.turnNumber);
+            }
+            // Count by tool type
+            if (change.toolName === 'Edit') {
+                fileData.totalEdits++;
+            }
+            else {
+                fileData.totalWrites++;
+            }
+            // Add change data
+            fileData.changes.push({
+                turn: change.turnNumber,
+                toolName: change.toolName,
+                oldString: change.oldString,
+                newString: change.newString,
+            });
+            // Compute line stats from actual changes
+            const newLines = (change.newString.match(/\n/g) || []).length + 1;
+            const oldLines = change.oldString ? (change.oldString.match(/\n/g) || []).length + 1 : 0;
+            if (change.toolName === 'Write') {
+                // New file - all lines are added
+                totalLinesAdded += newLines;
+            }
+            else {
+                // Edit - compute diff
+                totalLinesAdded += Math.max(0, newLines - oldLines);
+                totalLinesRemoved += Math.max(0, oldLines - newLines);
+            }
+        }
+        // Convert map to array and sort by first turn number
+        const files = Array.from(fileMap.values()).sort((a, b) => {
+            const aFirst = Math.min(...a.turnNumbers);
+            const bFirst = Math.min(...b.turnNumbers);
+            return aFirst - bFirst;
+        });
+        // Format turn summaries (TurnRecord uses snake_case)
+        const turnSummaries = turns.map((t) => ({
+            number: t.turn_number,
+            headline: t.headline,
+            tag: t.tag || 'implement',
+            toolCount: t.tool_count || 0,
+        }));
+        // Compute total turns (max turn number from changes or turns)
+        const maxTurnFromChanges = fileChanges.length > 0
+            ? Math.max(...fileChanges.map(c => c.turnNumber))
+            : 0;
+        const maxTurnFromTurns = turns.length > 0
+            ? Math.max(...turns.map((t) => t.turn_number))
+            : 0;
+        const totalTurns = Math.max(maxTurnFromChanges, maxTurnFromTurns);
+        logger.info('Pre-computed walkthrough data', {
+            sessionId,
+            totalFiles: files.length,
+            totalChanges: fileChanges.length,
+            totalTurns,
+            linesAdded: totalLinesAdded,
+            linesRemoved: totalLinesRemoved,
+        });
+        return {
+            sessionId,
+            totalTurns,
+            totalFiles: files.length,
+            linesAdded: totalLinesAdded,
+            linesRemoved: totalLinesRemoved,
+            files,
+            turns: turnSummaries,
+            purpose: insights?.purpose || undefined,
+            description: insights?.description || undefined,
+        };
+    }
+    getClient() {
+        if (!this.client) {
+            const config = ConfigService.getInstance().getConfig();
+            const apiKey = config.anthropic?.apiKey || process.env.ANTHROPIC_API_KEY;
+            if (!apiKey) {
+                throw new Error('No Anthropic API key configured');
+            }
+            this.client = new Anthropic({ apiKey });
+        }
+        return this.client;
+    }
+    /**
+     * Generate a walkthrough for a session, optionally filtered to specific indices
+     * @param sessionId - The session to generate walkthrough for
+     * @param scope - Optional scope with editIndices and writeIndices to filter changes
+     */
+    async generateWalkthrough(sessionId, scope) {
+        logger.info('Generating walkthrough', { sessionId, hasScope: !!scope });
+        // Extract session data
+        let data = await this.extractWalkthroughData(sessionId);
+        if (data.edits.length === 0 && data.writes.length === 0) {
+            throw new Error('No code changes found in session');
+        }
+        // If scope indices provided, filter the data
+        if (scope?.editIndices || scope?.writeIndices) {
+            const editIndices = scope.editIndices || [];
+            const writeIndices = scope.writeIndices || [];
+            logger.info('Filtering to scope', {
+                editCount: editIndices.length,
+                writeCount: writeIndices.length,
+                totalEdits: data.edits.length,
+                totalWrites: data.writes.length,
+            });
+            // Filter edits and writes to only those in this scope
+            data = {
+                ...data,
+                edits: editIndices.map(i => data.edits[i]).filter(Boolean),
+                writes: writeIndices.map(i => data.writes[i]).filter(Boolean),
+            };
+        }
+        logger.info('Extracted session data', {
+            sessionId,
+            edits: data.edits.length,
+            writes: data.writes.length,
+        });
+        // Generate walkthrough with Claude
+        const walkthrough = await this.callClaude(data);
+        // Add syntax highlighting
+        const highlighted = await this.addHighlighting(walkthrough);
+        logger.info('Walkthrough generated', { sessionId, sections: highlighted.sections.length });
+        return highlighted;
+    }
+    /**
+     * Analyze session changes and suggest conceptual groupings for walkthroughs.
+     * Uses Haiku for fast analysis of what distinct features/tasks were worked on.
+     * @param sessionId - The session to analyze
+     * @param previousGroupings - Optional previous groupings to maintain stability
+     */
+    async analyzeScope(sessionId, previousGroupings) {
+        logger.info('Analyzing walkthrough scope', { sessionId, hasPreviousGroupings: !!previousGroupings });
+        const data = await this.extractWalkthroughData(sessionId);
+        if (data.edits.length === 0 && data.writes.length === 0) {
+            throw new Error('No code changes found in session');
+        }
+        // Build a summary of changes for Haiku to analyze
+        const changesSummary = this.buildChangesSummaryForScoping(data);
+        // Build stability context if we have previous groupings
+        let stabilityContext = '';
+        if (previousGroupings && previousGroupings.length > 0) {
+            stabilityContext = `
+IMPORTANT: This session was previously analyzed with these groupings:
+${JSON.stringify(previousGroupings, null, 2)}
+
+STABILITY RULES:
+- Keep existing group IDs and titles when the same work is still present
+- Only rename a group if its scope has fundamentally changed
+- New changes (higher indices) should either extend existing groups OR form new groups
+- Prefer extending existing groups over creating new ones when work is related
+- If a previous group's changes are still present, keep that group
+
+`;
+        }
+        const client = this.getClient();
+        const response = await client.messages.create({
+            model: 'claude-haiku-4-5-20251001',
+            max_tokens: 2048,
+            messages: [{
+                    role: 'user',
+                    content: `Analyze these code changes from a coding session and identify distinct conceptual groupings.
+
+The user's original request was:
+"${data.userRequest.slice(0, 500)}"
+
+Here are the changes made, with reasoning before each:
+
+${changesSummary}
+
+---
+${stabilityContext}
+Identify 1-4 conceptual groupings based on WHAT was being accomplished (not just which files were touched).
+Consider the reasoning text - it explains intent.
+
+For each grouping, specify which edit/write indices belong to it (0-indexed).
+
+Output JSON:
+{
+  "groupings": [
+    {
+      "id": "unique-slug",
+      "title": "Short title (3-6 words)",
+      "description": "One sentence explaining what this group of changes accomplishes",
+      "editIndices": [0, 1, 5],
+      "writeIndices": [0]
+    }
+  ]
+}
+
+If all changes are part of one cohesive feature, return just one grouping with all indices.
+Output only valid JSON.`
+                }],
+        });
+        const content = response.content[0];
+        if (content.type !== 'text') {
+            throw new Error('Unexpected response type from scope analysis');
+        }
+        // Parse response
+        let jsonText = content.text.trim();
+        const jsonMatch = jsonText.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+        if (jsonMatch) {
+            jsonText = jsonMatch[1];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonText);
+        }
+        catch {
+            logger.error('Failed to parse scope analysis', { response: content.text.slice(0, 500) });
+            // Fallback: single group with everything
+            parsed = {
+                groupings: [{
+                        id: 'all-changes',
+                        title: 'All Changes',
+                        description: 'All changes in this session',
+                        editIndices: data.edits.map((_, i) => i),
+                        writeIndices: data.writes.map((_, i) => i),
+                    }]
+            };
+        }
+        // Build scope options with file counts and turn ranges
+        const options = parsed.groupings.map(g => {
+            const files = new Set();
+            const turnNumbers = [];
+            g.editIndices.forEach(i => {
+                if (data.edits[i]) {
+                    files.add(data.edits[i].file_path);
+                    turnNumbers.push(data.edits[i].turnNumber);
+                }
+            });
+            g.writeIndices.forEach(i => {
+                if (data.writes[i]) {
+                    files.add(data.writes[i].file_path);
+                    turnNumbers.push(data.writes[i].turnNumber);
+                }
+            });
+            // Compute turn range (min/max turn numbers in this group)
+            const minTurn = turnNumbers.length > 0 ? Math.min(...turnNumbers) : 1;
+            const maxTurn = turnNumbers.length > 0 ? Math.max(...turnNumbers) : 1;
+            return {
+                id: g.id,
+                title: g.title,
+                description: g.description,
+                editIndices: g.editIndices,
+                writeIndices: g.writeIndices,
+                fileCount: files.size,
+                changeCount: g.editIndices.length + g.writeIndices.length,
+                turnRange: [minTurn, maxTurn],
+            };
+        });
+        // Compute total turn count from all edits/writes
+        const allTurnNumbers = [
+            ...data.edits.map(e => e.turnNumber),
+            ...data.writes.map(w => w.turnNumber),
+        ];
+        const totalTurns = allTurnNumbers.length > 0 ? Math.max(...allTurnNumbers) : 0;
+        // Compute all unique files for full session scope
+        const allFiles = new Set();
+        data.edits.forEach(e => allFiles.add(e.file_path));
+        data.writes.forEach(w => allFiles.add(w.file_path));
+        // Prepend "Complete Session" option if there are multiple groupings
+        // (If Haiku already returned a single "all changes" group, don't duplicate)
+        const hasMultipleGroupings = options.length > 1;
+        const fullSessionOption = {
+            id: 'complete-session',
+            title: 'Complete Session',
+            description: 'Walk through everything done in this session from start to finish',
+            editIndices: data.edits.map((_, i) => i),
+            writeIndices: data.writes.map((_, i) => i),
+            fileCount: allFiles.size,
+            changeCount: data.edits.length + data.writes.length,
+            turnRange: [1, totalTurns],
+        };
+        const finalOptions = hasMultipleGroupings ? [fullSessionOption, ...options] : options;
+        logger.info('Scope analysis complete', {
+            sessionId,
+            optionCount: finalOptions.length,
+            totalTurns,
+            hasFullSessionOption: hasMultipleGroupings,
+            options: finalOptions.map(o => ({ title: o.title, turnRange: o.turnRange }))
+        });
+        return {
+            sessionId,
+            totalEdits: data.edits.length,
+            totalWrites: data.writes.length,
+            totalTurns,
+            userRequest: data.userRequest.slice(0, 200),
+            options: finalOptions,
+        };
+    }
+    /**
+     * Build a concise summary of changes for scope analysis
+     */
+    buildChangesSummaryForScoping(data) {
+        const lines = [];
+        data.edits.forEach((edit, i) => {
+            const shortPath = edit.file_path.replace(/^\/home\/jason\/(claudia|cui-custom)\//, '');
+            const reasoningSnippet = edit.reasoning.slice(0, 150).replace(/\n/g, ' ');
+            lines.push(`Edit ${i}: ${shortPath}`);
+            lines.push(`  Reasoning: ${reasoningSnippet}...`);
+            lines.push(`  Changed: ${edit.old_string.slice(0, 50).replace(/\n/g, '\\n')}... → ${edit.new_string.slice(0, 50).replace(/\n/g, '\\n')}...`);
+            lines.push('');
+        });
+        data.writes.forEach((write, i) => {
+            const shortPath = write.file_path.replace(/^\/home\/jason\/(claudia|cui-custom)\//, '');
+            const reasoningSnippet = write.reasoning.slice(0, 150).replace(/\n/g, ' ');
+            lines.push(`Write ${i}: ${shortPath} (new file)`);
+            lines.push(`  Reasoning: ${reasoningSnippet}...`);
+            lines.push('');
+        });
+        return lines.join('\n');
+    }
+    /**
+     * Check if a user message contains actual human text (not just tool_result).
+     */
+    hasHumanText(content) {
+        if (typeof content === 'string' && content.trim()) {
+            return true;
+        }
+        if (Array.isArray(content)) {
+            return content.some(block => typeof block === 'object' && block !== null && block.type === 'text' && 'text' in block);
+        }
+        return false;
+    }
+    /**
+     * Extract Edit/Write calls from session messages, including turn numbers.
+     */
+    async extractWalkthroughData(sessionId) {
+        const details = await this.historyReader.fetchConversationDirect(sessionId);
+        if (!details || !details.messages) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const messages = details.messages;
+        // Extract user request (first user message with human text)
+        let userRequest = '';
+        for (const msg of messages) {
+            if (msg.type === 'user' && this.hasHumanText(msg.message.content)) {
+                const content = msg.message.content;
+                if (typeof content === 'string') {
+                    userRequest = content;
+                    break;
+                }
+                else if (Array.isArray(content)) {
+                    const textBlock = content.find((b) => b.type === 'text');
+                    if (textBlock?.text) {
+                        userRequest = textBlock.text;
+                        break;
+                    }
+                }
+            }
+        }
+        // Extract Edit/Write calls with reasoning and turn numbers
+        // A turn starts when we see a user message with actual human text
+        const edits = [];
+        const writes = [];
+        let currentReasoning = '';
+        let currentTurn = 0;
+        for (const msg of messages) {
+            // Detect turn boundaries - user message with human text starts a new turn
+            if (msg.type === 'user' && this.hasHumanText(msg.message.content)) {
+                currentTurn++;
+            }
+            if (msg.type === 'assistant') {
+                const content = msg.message.content;
+                if (Array.isArray(content)) {
+                    // Capture reasoning from text blocks
+                    const textBlocks = content.filter((b) => b.type === 'text');
+                    if (textBlocks.length > 0) {
+                        currentReasoning = textBlocks.map((b) => b.text || '').join('\n');
+                    }
+                    // Extract tool calls
+                    for (const block of content) {
+                        if (block.type === 'tool_use') {
+                            if (block.name === 'Edit' && block.input) {
+                                edits.push({
+                                    file_path: block.input.file_path,
+                                    old_string: block.input.old_string,
+                                    new_string: block.input.new_string,
+                                    reasoning: currentReasoning,
+                                    turnNumber: currentTurn,
+                                });
+                            }
+                            else if (block.name === 'Write' && block.input) {
+                                writes.push({
+                                    file_path: block.input.file_path,
+                                    content: block.input.content,
+                                    reasoning: currentReasoning,
+                                    turnNumber: currentTurn,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return { sessionId, userRequest, edits, writes };
+    }
+    /**
+     * Build prompt and call Claude to generate walkthrough
+     * Uses structured outputs beta for guaranteed JSON schema compliance
+     */
+    async callClaude(data) {
+        const prompt = this.buildPrompt(data);
+        const client = this.getClient();
+        // Use structured outputs beta for guaranteed JSON schema compliance
+        const response = await client.beta.messages.create({
+            model: 'claude-sonnet-4-5-20250929',
+            max_tokens: 16384,
+            betas: ['structured-outputs-2025-11-13'],
+            messages: [{ role: 'user', content: prompt }],
+            output_format: {
+                type: 'json_schema',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        summary: { type: 'string' },
+                        context: {
+                            type: 'object',
+                            properties: {
+                                problem: { type: 'string' },
+                                priorState: { type: 'string' },
+                                approach: { type: 'string' },
+                            },
+                            required: ['problem', 'priorState', 'approach'],
+                            additionalProperties: false,
+                        },
+                        orientation: {
+                            type: 'object',
+                            properties: {
+                                narrative: { type: 'string' },
+                                keyFiles: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            file: { type: 'string' },
+                                            role: { type: 'string' },
+                                        },
+                                        required: ['file', 'role'],
+                                        additionalProperties: false,
+                                    },
+                                },
+                            },
+                            required: ['narrative'],
+                            additionalProperties: false,
+                        },
+                        sections: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    heading: { type: 'string' },
+                                    narrative: { type: 'string' },
+                                    linkedPhrases: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                phrase: { type: 'string' },
+                                                focusLines: { type: 'string' },
+                                                explanation: { type: 'string' },
+                                            },
+                                            required: ['phrase'],
+                                            additionalProperties: false,
+                                        },
+                                    },
+                                    file: { type: 'string' },
+                                    language: { type: 'string' },
+                                    before: {
+                                        type: 'object',
+                                        properties: {
+                                            description: { type: 'string' },
+                                            code: { type: 'string' },
+                                        },
+                                        required: ['description', 'code'],
+                                        additionalProperties: false,
+                                    },
+                                    after: {
+                                        type: 'object',
+                                        properties: {
+                                            description: { type: 'string' },
+                                            code: { type: 'string' },
+                                        },
+                                        required: ['description', 'code'],
+                                        additionalProperties: false,
+                                    },
+                                },
+                                required: ['heading', 'narrative'],
+                                additionalProperties: false,
+                            },
+                        },
+                        systemFlow: {
+                            type: 'object',
+                            properties: {
+                                description: { type: 'string' },
+                                components: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                },
+                            },
+                            required: ['description', 'components'],
+                            additionalProperties: false,
+                        },
+                    },
+                    required: ['title', 'summary', 'context', 'sections'],
+                    additionalProperties: false,
+                },
+            },
+        });
+        const content = response.content[0];
+        if (content.type !== 'text') {
+            throw new Error('Unexpected response type');
+        }
+        // With structured outputs, the response is guaranteed valid JSON
+        return JSON.parse(content.text);
+    }
+    buildPrompt(data) {
+        // Group edits by file
+        const editsByFile = new Map();
+        for (const edit of data.edits) {
+            const existing = editsByFile.get(edit.file_path) || [];
+            existing.push(edit);
+            editsByFile.set(edit.file_path, existing);
+        }
+        let changesDescription = '';
+        for (const [filePath, fileEdits] of editsByFile) {
+            const shortPath = filePath.replace(/^\/home\/jason\/(claudia|cui-custom)\//, '');
+            changesDescription += `\n## ${shortPath}\n\n`;
+            for (let i = 0; i < fileEdits.length; i++) {
+                const edit = fileEdits[i];
+                changesDescription += `### Edit ${i + 1}\n`;
+                changesDescription += `**My reasoning at the time:**\n${edit.reasoning.slice(0, 500)}\n\n`;
+                changesDescription += `**Changed from:**\n\`\`\`\n${edit.old_string.slice(0, 400)}\n\`\`\`\n\n`;
+                changesDescription += `**Changed to:**\n\`\`\`\n${edit.new_string.slice(0, 400)}\n\`\`\`\n\n`;
+            }
+        }
+        for (const write of data.writes) {
+            const shortPath = write.file_path.replace(/^\/home\/jason\/(claudia|cui-custom)\//, '');
+            changesDescription += `\n## ${shortPath} (new file)\n\n`;
+            changesDescription += `**My reasoning:**\n${write.reasoning.slice(0, 500)}\n\n`;
+            changesDescription += `**Content:**\n\`\`\`\n${write.content.slice(0, 600)}\n\`\`\`\n\n`;
+        }
+        return `You are creating an interactive walkthrough of code changes from a coding session. The walkthrough will show a narrative explanation with before/after code comparisons and diffs.
+
+The user's original request was:
+"${data.userRequest.slice(0, 1000)}"
+
+Here are all the changes you made, with your reasoning at the time:
+
+${changesDescription}
+
+---
+
+Create a narrative-driven walkthrough with BEFORE/AFTER code comparisons:
+
+1. **Context** - Problem, prior state, approach (1-2 sentences each, set the scene)
+
+2. **Orientation** - Brief tour of relevant files (just file paths and roles, no code snippets)
+
+3. **Sections** - Each section explains ONE conceptual change with:
+   - A heading (conceptual, not just a filename)
+   - A narrative explaining what changed and WHY (first person, past tense)
+   - linkedPhrases: 2-4 phrases from the narrative that become interactive (underlined, hoverable)
+   - before: the code BEFORE the change
+   - after: the code AFTER the change (viewer will compute diff automatically)
+
+INTERACTIVE LINKED PHRASES:
+Pick key terms from your narrative that reference specific code. When the user hovers these underlined phrases, the corresponding lines in the "after" code will be highlighted. Include a brief tooltip explanation.
+
+EXAMPLE for narrative "I wrapped the component in a SelectionProvider and made each step use Selectable":
+linkedPhrases: [
+  { "phrase": "SelectionProvider", "focusLines": "3:4", "explanation": "Creates shared selection context for all children" },
+  { "phrase": "Selectable", "focusLines": "8:12", "explanation": "Makes this element respond to hover and scroll selection" }
+]
+
+CODE HIKE ANNOTATIONS (use in before/after code):
+- // !focus(1:3) - dims other lines, highlights these (great for drawing attention!)
+- // !mark[/text/] - highlights specific tokens inline
+- // !tooltip[/text/] Explanation - shows tooltip on hover over text in code
+
+Output JSON matching this schema:
+${WALKTHROUGH_SCHEMA}
+
+CRITICAL Guidelines:
+- Each section needs BOTH before AND after code - show the transformation
+- linkedPhrases must use EXACT text from the narrative (case-sensitive match)
+- focusLines reference the AFTER code using 1-indexed line numbers
+- Write in PAST TENSE - this is retrospective ("I added...", "This enabled...")
+- Keep sections focused - 3-6 sections is ideal
+- Code should be 10-40 lines, enough context to understand the change
+- Don't include unrelated code in before/after - focus on what changed
+
+IMPORTANT: Output ONLY the JSON object. No markdown, no prose, no explanation. Start with { end with }.`;
+    }
+    /**
+     * Add Code Hike syntax highlighting to all code blocks
+     */
+    async addHighlighting(walkthrough) {
+        const theme = 'github-dark';
+        const highlightCode = async (code, lang) => {
+            const normalizedLang = LANG_MAP[lang.toLowerCase()] || lang || 'text';
+            try {
+                return await highlight({ value: code, lang: normalizedLang, meta: '' }, theme);
+            }
+            catch (err) {
+                logger.warn('Failed to highlight code', { lang: normalizedLang, error: err });
+                return null;
+            }
+        };
+        const inferLang = (file) => {
+            if (!file)
+                return 'typescript';
+            const ext = file.split('.').pop()?.toLowerCase() || '';
+            return LANG_MAP[ext] || ext || 'typescript';
+        };
+        // Highlight orientation keyFiles
+        if (walkthrough.orientation?.keyFiles) {
+            for (const keyFile of walkthrough.orientation.keyFiles) {
+                if (keyFile.relevantCode) {
+                    const lang = inferLang(keyFile.file);
+                    const highlighted = await highlightCode(keyFile.relevantCode, lang);
+                    if (highlighted) {
+                        keyFile.highlighted = highlighted;
+                    }
+                }
+            }
+        }
+        // Highlight sections and compute diffs
+        for (const section of walkthrough.sections) {
+            const sectionLang = section.language || section.codeBlocks?.[0]?.language || 'typescript';
+            // New scrollycoding format: highlight section.code
+            if (section.code) {
+                const lang = section.language || inferLang(section.file);
+                const highlighted = await highlightCode(section.code, lang);
+                if (highlighted) {
+                    section.codeHighlighted = highlighted;
+                }
+            }
+            // Legacy format: before/after
+            if (section.before?.code) {
+                const highlighted = await highlightCode(section.before.code, sectionLang);
+                if (highlighted) {
+                    section.before.highlighted = highlighted;
+                }
+            }
+            if (section.after?.code) {
+                const highlighted = await highlightCode(section.after.code, sectionLang);
+                if (highlighted) {
+                    section.after.highlighted = highlighted;
+                }
+            }
+            // Compute diff if we have before and after code
+            if (section.before?.code && section.after?.code) {
+                const filename = section.codeBlocks?.[0]?.file;
+                section.diff = this.computeDiff(section.before.code, section.after.code, filename);
+            }
+            if (section.codeBlocks) {
+                for (const block of section.codeBlocks) {
+                    if (block.snippet) {
+                        const highlighted = await highlightCode(block.snippet, block.language || 'typescript');
+                        if (highlighted) {
+                            block.highlighted = highlighted;
+                        }
+                    }
+                }
+            }
+        }
+        return walkthrough;
+    }
+    /**
+     * Compute unified diff from old and new strings
+     */
+    computeDiff(oldStr, newStr, filename) {
+        const changes = Diff.diffLines(oldStr, newStr);
+        const lines = [];
+        let oldLineNum = 1;
+        let newLineNum = 1;
+        let added = 0;
+        let removed = 0;
+        for (const change of changes) {
+            const changeLines = change.value.replace(/\n$/, '').split('\n');
+            for (const line of changeLines) {
+                if (change.added) {
+                    lines.push({
+                        type: 'added',
+                        content: line,
+                        lineNumber: { new: newLineNum },
+                    });
+                    newLineNum++;
+                    added++;
+                }
+                else if (change.removed) {
+                    lines.push({
+                        type: 'removed',
+                        content: line,
+                        lineNumber: { old: oldLineNum },
+                    });
+                    oldLineNum++;
+                    removed++;
+                }
+                else {
+                    lines.push({
+                        type: 'context',
+                        content: line,
+                        lineNumber: { old: oldLineNum, new: newLineNum },
+                    });
+                    oldLineNum++;
+                    newLineNum++;
+                }
+            }
+        }
+        // Simplify to show only hunks with changes (context around changes)
+        const contextLines = 3;
+        const hunks = [];
+        let currentHunk = null;
+        let lastChangeIndex = -100;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const isChange = line.type !== 'context';
+            if (isChange) {
+                // Start new hunk if needed
+                if (!currentHunk || i - lastChangeIndex > contextLines * 2) {
+                    // Add trailing context to previous hunk
+                    if (currentHunk) {
+                        const trailingStart = lastChangeIndex + 1;
+                        const trailingEnd = Math.min(trailingStart + contextLines, i);
+                        for (let j = trailingStart; j < trailingEnd; j++) {
+                            if (lines[j].type === 'context') {
+                                currentHunk.lines.push(lines[j]);
+                            }
+                        }
+                        hunks.push(currentHunk);
+                    }
+                    // Start new hunk with leading context
+                    currentHunk = {
+                        header: `@@ changes @@`,
+                        lines: [],
+                    };
+                    const leadingStart = Math.max(0, i - contextLines);
+                    for (let j = leadingStart; j < i; j++) {
+                        if (lines[j].type === 'context') {
+                            currentHunk.lines.push(lines[j]);
+                        }
+                    }
+                }
+                currentHunk.lines.push(line);
+                lastChangeIndex = i;
+            }
+        }
+        // Finish last hunk
+        if (currentHunk && currentHunk.lines.length > 0) {
+            const trailingStart = lastChangeIndex + 1;
+            const trailingEnd = Math.min(trailingStart + contextLines, lines.length);
+            for (let j = trailingStart; j < trailingEnd; j++) {
+                if (lines[j].type === 'context') {
+                    currentHunk.lines.push(lines[j]);
+                }
+            }
+            hunks.push(currentHunk);
+        }
+        // If no hunks (no changes), return empty
+        if (hunks.length === 0) {
+            return {
+                hunks: [],
+                stats: { added: 0, removed: 0 },
+            };
+        }
+        return {
+            oldFile: filename,
+            newFile: filename,
+            hunks,
+            stats: { added, removed },
+        };
+    }
+}
+//# sourceMappingURL=walkthrough-service.js.map