sidekick-shared 0.13.2

package/dist/parsers/planExtractor.js

@@ -0,0 +1,330 @@
+"use strict";
+/**
+ * Shared plan extraction from session events.
+ *
+ * Handles all three providers:
+ * - Claude Code: EnterPlanMode/ExitPlanMode tool calls with accumulated markdown
+ * - OpenCode: <proposed_plan> XML blocks in assistant messages
+ * - Codex: UpdatePlan tool calls with structured approach arrays
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanExtractor = void 0;
+exports.parsePlanMarkdown = parsePlanMarkdown;
+exports.extractProposedPlan = extractProposedPlan;
+/** Checkbox pattern: `- [ ] text` or `- [x] text` */
+const CHECKBOX_PATTERN = /^[-*]\s+\[([ xX])\]\s+(.+)/;
+/** Numbered list pattern: `1. text` or `1) text` */
+const NUMBERED_PATTERN = /^\d+[.)]\s+(.+)/;
+/** Bullet point pattern: `- Step` or `* Step` (excluding checkboxes) */
+const BULLET_PATTERN = /^[-*]\s+(?!\[[ xX]\])(.+)/;
+/** Phase header pattern: `## Phase 1: Setup` */
+const PHASE_HEADER_PATTERN = /^#{2,4}\s+(?:Phase|Step|Stage)\s*\d*[:.]\s*(.+)/i;
+/** Generic H1/H2 header for title extraction */
+const TITLE_HEADER_PATTERN = /^#{1,2}\s+(.+)/;
+/** Complexity keywords */
+const EXPLICIT_COMPLEXITY_PATTERN = /\[(high|medium|low)\]|\((complex|simple)\)/i;
+const HIGH_COMPLEXITY_KEYWORDS = /\b(refactor|migrate|rewrite|redesign|overhaul|rearchitect)\b/i;
+const LOW_COMPLEXITY_KEYWORDS = /\b(update|fix|tweak|rename|adjust|bump|typo)\b/i;
+function inferComplexity(description) {
+    const explicitMatch = description.match(EXPLICIT_COMPLEXITY_PATTERN);
+    if (explicitMatch) {
+        const marker = (explicitMatch[1] || explicitMatch[2]).toLowerCase();
+        if (marker === 'high' || marker === 'complex')
+            return 'high';
+        if (marker === 'low' || marker === 'simple')
+            return 'low';
+        return 'medium';
+    }
+    if (HIGH_COMPLEXITY_KEYWORDS.test(description))
+        return 'high';
+    if (LOW_COMPLEXITY_KEYWORDS.test(description))
+        return 'low';
+    return undefined;
+}
+/**
+ * Parses plan markdown into structured plan steps.
+ */
+function parsePlanMarkdown(markdown) {
+    if (!markdown || !markdown.trim())
+        return { steps: [] };
+    const lines = markdown.split('\n');
+    const steps = [];
+    let title;
+    let currentPhase;
+    let stepIndex = 0;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (!title) {
+            const titleMatch = line.match(TITLE_HEADER_PATTERN);
+            if (titleMatch)
+                title = titleMatch[1].trim();
+        }
+        const phaseMatch = line.match(PHASE_HEADER_PATTERN);
+        if (phaseMatch) {
+            currentPhase = phaseMatch[1].trim();
+            continue;
+        }
+        const checkboxMatch = line.match(CHECKBOX_PATTERN);
+        if (checkboxMatch) {
+            const checked = checkboxMatch[1].toLowerCase() === 'x';
+            const description = checkboxMatch[2].trim();
+            steps.push({
+                id: `step-${stepIndex}`,
+                description,
+                status: checked ? 'completed' : 'pending',
+                phase: currentPhase,
+                complexity: inferComplexity(description),
+            });
+            stepIndex++;
+            continue;
+        }
+        const numberedMatch = line.match(NUMBERED_PATTERN);
+        if (numberedMatch) {
+            const description = numberedMatch[1].trim();
+            steps.push({
+                id: `step-${stepIndex}`,
+                description,
+                status: 'pending',
+                phase: currentPhase,
+                complexity: inferComplexity(description),
+            });
+            stepIndex++;
+            continue;
+        }
+        const bulletMatch = line.match(BULLET_PATTERN);
+        if (bulletMatch) {
+            const raw = bulletMatch[1].trim();
+            if (raw.length <= 3)
+                continue; // skip trivially short lines
+            // Normalize bold-colon patterns: **Setup**: desc → Setup: desc
+            const description = raw.replace(/\*\*(.+?)\*\*:\s*/, '$1: ');
+            steps.push({
+                id: `step-${stepIndex}`,
+                description,
+                status: 'pending',
+                phase: currentPhase,
+                complexity: inferComplexity(description),
+            });
+            stepIndex++;
+            continue;
+        }
+    }
+    return { title, steps };
+}
+/**
+ * Extracts <proposed_plan> content from text.
+ */
+function extractProposedPlan(text) {
+    const match = text.match(/<proposed_plan>([\s\S]*?)<\/proposed_plan>/);
+    return match ? match[1].trim() : null;
+}
+/**
+ * Extracts full untruncated text from event.raw message content blocks.
+ * Falls back to event.summary if raw is unavailable.
+ */
+function extractFullTextFromRaw(event) {
+    const raw = event.raw;
+    const message = raw?.message;
+    const content = message?.content;
+    if (Array.isArray(content)) {
+        const texts = [];
+        for (const block of content) {
+            const b = block;
+            if (b.type === 'text' && typeof b.text === 'string') {
+                texts.push(b.text);
+            }
+        }
+        if (texts.length > 0)
+            return texts.join('\n');
+    }
+    // Fall back to summary (may be truncated, but better than nothing)
+    return event.summary || null;
+}
+/**
+ * Stateful plan extractor for use with FollowEvent streams.
+ *
+ * Handles all three providers:
+ * - Claude Code: EnterPlanMode/ExitPlanMode tool calls
+ * - OpenCode: <proposed_plan> blocks in assistant text
+ * - Codex: UpdatePlan tool calls
+ */
+class PlanExtractor {
+    _plan = null;
+    _planModeActive = false;
+    _planTexts = [];
+    _planFileContent = null;
+    _planFilePath = null;
+    _readFile;
+    constructor(readFile) {
+        this._readFile = readFile ?? null;
+    }
+    get plan() {
+        return this._plan;
+    }
+    reset() {
+        this._plan = null;
+        this._planModeActive = false;
+        this._planTexts = [];
+        this._planFileContent = null;
+        this._planFilePath = null;
+    }
+    /**
+     * Process a FollowEvent and extract plan data if present.
+     * Returns true if the plan was updated.
+     */
+    processEvent(event) {
+        // Codex: UpdatePlan tool calls
+        if (event.type === 'tool_use' && event.toolName === 'UpdatePlan') {
+            return this.extractCodexPlan(event);
+        }
+        // Claude Code: EnterPlanMode
+        if (event.type === 'tool_use' && event.toolName === 'EnterPlanMode') {
+            this._planModeActive = true;
+            this._planTexts = [];
+            this._planFileContent = null;
+            this._planFilePath = null;
+            return false;
+        }
+        // Claude Code: ExitPlanMode
+        if (event.type === 'tool_use' && event.toolName === 'ExitPlanMode') {
+            return this.finalizePlanMode();
+        }
+        // Capture Write/Edit tool calls to plan files during plan mode
+        if (this._planModeActive && event.type === 'tool_use') {
+            const raw = event.raw;
+            const input = raw?.input;
+            const filePath = input?.file_path;
+            if (event.toolName === 'Write') {
+                const content = input?.content;
+                if (filePath && content && filePath.includes('.claude/plans/')) {
+                    this._planFileContent = content;
+                    this._planFilePath = filePath;
+                }
+            }
+            else if (event.toolName === 'Edit') {
+                // Edit contains a diff, not full content — capture path for disk-read fallback
+                if (filePath && filePath.includes('.claude/plans/')) {
+                    this._planFilePath = filePath;
+                }
+            }
+        }
+        // Accumulate text during plan mode (Claude Code)
+        // Extract full text from event.raw to avoid truncated summaries
+        if (this._planModeActive && event.type === 'assistant') {
+            const fullText = extractFullTextFromRaw(event);
+            if (fullText) {
+                this._planTexts.push(fullText);
+            }
+        }
+        // OpenCode / Codex: <proposed_plan> blocks
+        // Check raw message content first (untruncated), then fall back to summary
+        if (event.type === 'assistant') {
+            const raw = event.raw;
+            const message = raw?.message;
+            const content = message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block;
+                    if (b.type === 'text' && typeof b.text === 'string') {
+                        const planText = extractProposedPlan(b.text);
+                        if (planText) {
+                            return this.extractFromMarkdown(planText, this.getSource(event));
+                        }
+                    }
+                }
+            }
+            // Fall back to summary (may work for short plans)
+            if (event.summary) {
+                const proposed = extractProposedPlan(event.summary);
+                if (proposed) {
+                    return this.extractFromMarkdown(proposed, this.getSource(event));
+                }
+            }
+        }
+        return false;
+    }
+    getSource(event) {
+        if (event.providerId === 'opencode')
+            return 'opencode';
+        if (event.providerId === 'codex')
+            return 'codex';
+        return 'claude-code';
+    }
+    extractCodexPlan(event) {
+        const raw = event.raw;
+        if (!raw?.input)
+            return false;
+        const input = raw.input;
+        // Codex UpdatePlan can use either approach[] or plan[] format
+        const approach = (input.approach ?? input.plan);
+        if (!approach || !Array.isArray(approach))
+            return false;
+        const steps = [];
+        for (let i = 0; i < approach.length; i++) {
+            const entry = approach[i];
+            if (typeof entry === 'string') {
+                steps.push({
+                    id: `step-${i}`,
+                    description: entry,
+                    status: 'pending',
+                    complexity: inferComplexity(entry),
+                });
+            }
+            else if (typeof entry === 'object' && entry !== null) {
+                const obj = entry;
+                const desc = String(obj.step || obj.description || '').trim();
+                if (!desc)
+                    continue;
+                const rawStatus = String(obj.status || 'pending').toLowerCase();
+                let status;
+                if (rawStatus === 'completed')
+                    status = 'completed';
+                else if (rawStatus === 'in_progress' || rawStatus === 'in-progress')
+                    status = 'in_progress';
+                else
+                    status = 'pending';
+                steps.push({
+                    id: `step-${i}`,
+                    description: desc,
+                    status,
+                    complexity: inferComplexity(desc),
+                });
+            }
+        }
+        if (steps.length > 0) {
+            this._plan = {
+                title: input.title || 'Plan',
+                steps,
+                source: 'codex',
+            };
+            return true;
+        }
+        return false;
+    }
+    finalizePlanMode() {
+        this._planModeActive = false;
+        // Prefer plan file content (from Write tool) → accumulated assistant text → disk read fallback
+        const markdown = this._planFileContent
+            || (this._planTexts.length > 0 ? this._planTexts.join('\n') : null)
+            || (this._planFilePath && this._readFile ? this._readFile(this._planFilePath) : null);
+        this._planFileContent = null;
+        this._planFilePath = null;
+        this._planTexts = [];
+        if (!markdown)
+            return false;
+        return this.extractFromMarkdown(markdown, 'claude-code');
+    }
+    extractFromMarkdown(markdown, source) {
+        const parsed = parsePlanMarkdown(markdown);
+        this._plan = {
+            title: parsed.title || 'Plan',
+            steps: parsed.steps,
+            source,
+            rawMarkdown: markdown,
+        };
+        return true;
+    }
+}
+exports.PlanExtractor = PlanExtractor;

package/dist/parsers/sessionActivityDetector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Content-based session activity detection.
+ *
+ * Uses heuristics on the tail of a JSONL file to determine if a session
+ * is genuinely ongoing (AI thinking/calling tools), ended (final output
+ * delivered), or stale (no updates for >5 minutes).
+ *
+ * Inspired by tail-claude's ending-event classification and grace periods.
+ *
+ * @module parsers/sessionActivityDetector
+ */
+export type SessionActivityState = 'ongoing' | 'ended' | 'stale';
+export interface SessionActivityResult {
+    state: SessionActivityState;
+    /** Timestamp of the last meaningful event */
+    lastActivityTime: Date | null;
+    /** Reason for the classification */
+    reason: string;
+}
+/**
+ * Determines whether a session is ongoing, ended, or stale.
+ *
+ * Uses a multi-signal approach:
+ * 1. File mtime staleness check (>5min → stale)
+ * 2. Content-based: reads last ~32KB and classifies the ending pattern
+ * 3. Grace period: prevents flicker by requiring 5s of inactivity before "ended"
+ *
+ * @param sessionPath - Path to the JSONL session file
+ * @returns Activity state with classification reason
+ */
+export declare function detectSessionActivity(sessionPath: string): SessionActivityResult;

package/dist/parsers/sessionActivityDetector.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * Content-based session activity detection.
+ *
+ * Uses heuristics on the tail of a JSONL file to determine if a session
+ * is genuinely ongoing (AI thinking/calling tools), ended (final output
+ * delivered), or stale (no updates for >5 minutes).
+ *
+ * Inspired by tail-claude's ending-event classification and grace periods.
+ *
+ * @module parsers/sessionActivityDetector
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSessionActivity = detectSessionActivity;
+const fs = __importStar(require("fs"));
+// ── Constants ──
+/** How many bytes to read from the end of the file for analysis */
+const TAIL_BYTES = 32 * 1024;
+/** Grace period to prevent spinner flicker (ms) */
+const GRACE_PERIOD_MS = 5_000;
+/** If mtime is older than this, session is stale regardless of content */
+const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
+// ── Event Classification Patterns ──
+/** Patterns indicating the AI is actively working */
+const AI_ACTIVITY_PATTERNS = [
+    '"type":"assistant"',
+    '"type":"tool_use"',
+    '"type":"tool_result"',
+    '"stop_reason":"tool_use"',
+];
+/** Patterns indicating the session has ended (final output delivered) */
+const ENDING_PATTERNS = [
+    '"stop_reason":"end_turn"',
+    '"type":"result"',
+    '"type":"user"', // User typing means AI is done with its turn
+];
+/** Patterns that definitely mean the session is done */
+const TERMINAL_PATTERNS = [
+    '"type":"result"',
+];
+// ── Public API ──
+/**
+ * Determines whether a session is ongoing, ended, or stale.
+ *
+ * Uses a multi-signal approach:
+ * 1. File mtime staleness check (>5min → stale)
+ * 2. Content-based: reads last ~32KB and classifies the ending pattern
+ * 3. Grace period: prevents flicker by requiring 5s of inactivity before "ended"
+ *
+ * @param sessionPath - Path to the JSONL session file
+ * @returns Activity state with classification reason
+ */
+function detectSessionActivity(sessionPath) {
+    let stat;
+    try {
+        stat = fs.statSync(sessionPath);
+    }
+    catch {
+        return { state: 'ended', lastActivityTime: null, reason: 'file-not-found' };
+    }
+    const now = Date.now();
+    const mtimeAge = now - stat.mtimeMs;
+    // Staleness check: if file hasn't been touched in >5 minutes, it's stale
+    if (mtimeAge > STALENESS_THRESHOLD_MS) {
+        return { state: 'stale', lastActivityTime: new Date(stat.mtimeMs), reason: 'mtime-stale' };
+    }
+    // Read the tail of the file for content analysis
+    const tail = readTail(sessionPath, stat.size);
+    if (!tail) {
+        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'empty-file' };
+    }
+    // Parse the last few JSONL lines
+    const lines = tail.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length === 0) {
+        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'no-events' };
+    }
+    // Find the last line that matches each category
+    let lastAiActivityIndex = -1;
+    let lastEndingIndex = -1;
+    let hasTerminal = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of AI_ACTIVITY_PATTERNS) {
+            if (line.includes(pattern)) {
+                lastAiActivityIndex = i;
+                break;
+            }
+        }
+        for (const pattern of TERMINAL_PATTERNS) {
+            if (line.includes(pattern)) {
+                hasTerminal = true;
+                lastEndingIndex = i;
+                break;
+            }
+        }
+        if (!hasTerminal) {
+            for (const pattern of ENDING_PATTERNS) {
+                if (line.includes(pattern)) {
+                    lastEndingIndex = i;
+                    break;
+                }
+            }
+        }
+    }
+    // Terminal patterns mean the session is definitely done
+    if (hasTerminal) {
+        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'terminal-event' };
+    }
+    // AI activity after the last ending event → ongoing
+    if (lastAiActivityIndex > lastEndingIndex) {
+        return { state: 'ongoing', lastActivityTime: new Date(stat.mtimeMs), reason: 'ai-activity-after-ending' };
+    }
+    // Ending event with no subsequent AI activity
+    if (lastEndingIndex >= 0) {
+        // Apply grace period to prevent flicker
+        if (mtimeAge < GRACE_PERIOD_MS) {
+            return { state: 'ongoing', lastActivityTime: new Date(stat.mtimeMs), reason: 'grace-period' };
+        }
+        return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'ending-event' };
+    }
+    // No clear signal — if recently modified, assume ongoing
+    if (mtimeAge < GRACE_PERIOD_MS) {
+        return { state: 'ongoing', lastActivityTime: new Date(stat.mtimeMs), reason: 'recent-mtime' };
+    }
+    return { state: 'ended', lastActivityTime: new Date(stat.mtimeMs), reason: 'no-activity-signal' };
+}
+// ── Helpers ──
+function readTail(filePath, fileSize) {
+    const bytesToRead = Math.min(TAIL_BYTES, fileSize);
+    if (bytesToRead <= 0)
+        return null;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buffer = Buffer.alloc(bytesToRead);
+        const offset = Math.max(0, fileSize - bytesToRead);
+        const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, offset);
+        fs.closeSync(fd);
+        fd = null;
+        return buffer.toString('utf-8', 0, bytesRead);
+    }
+    catch {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+        return null;
+    }
+}