sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/parsers/planExtractor.js

@@ -0,0 +1,335 @@
+/**
+ * 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
+ */
+/** 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.
+ */
+export 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.
+ */
+export 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
+ */
+export 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 = extractToolInput(raw);
+            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;
+        const input = extractToolInput(raw);
+        if (!input)
+            return false;
+        // 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 captured Write content, then the final file after Edit, then prose fallback.
+        // Edit only contains a diff, so reading the file must happen before accumulated text.
+        const markdown = this._planFileContent ||
+            (this._planFilePath && this._readFile ? this._readFile(this._planFilePath) : null) ||
+            (this._planTexts.length > 0 ? this._planTexts.join('\n') : 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;
+    }
+}
+function extractToolInput(raw) {
+    if (!raw)
+        return null;
+    if (raw.input && typeof raw.input === 'object')
+        return raw.input;
+    const tool = raw.tool;
+    if (tool?.input && typeof tool.input === 'object')
+        return tool.input;
+    return null;
+}

package/dist/esm/parsers/sessionActivityDetector.js

@@ -0,0 +1,246 @@
+/**
+ * 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
+ */
+import * as fs from '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) */
+export const SESSION_ACTIVITY_GRACE_PERIOD_MS = 5_000;
+const GRACE_PERIOD_MS = SESSION_ACTIVITY_GRACE_PERIOD_MS;
+/** If mtime is older than this, session is stale regardless of content */
+export const SESSION_ACTIVITY_STALENESS_MS = 5 * 60 * 1000;
+const STALENESS_THRESHOLD_MS = SESSION_ACTIVITY_STALENESS_MS;
+/** How many trailing events the in-memory classifier inspects (about a 32 KiB tail). */
+const TAIL_EVENTS = 200;
+// ── 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
+ */
+export 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' };
+    }
+    return classifyFromSignals(signalsFromLines(lines), stat.mtimeMs, mtimeAge);
+}
+function signalsFromLines(lines) {
+    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 (pattern === '"type":"user"' && line.includes('"type":"tool_result"'))
+                    continue;
+                if (line.includes(pattern)) {
+                    lastEndingIndex = i;
+                    break;
+                }
+            }
+        }
+    }
+    return { lastAiActivityIndex, lastEndingIndex, hasTerminal };
+}
+function hasToolResultBlock(event) {
+    const content = event.message?.content;
+    return (Array.isArray(content) &&
+        content.some((block) => typeof block === 'object' &&
+            block !== null &&
+            block.type === 'tool_result'));
+}
+/**
+ * The same signals the tail scanner derives from raw JSONL lines, read from
+ * canonical events instead: assistant, tool-use, and tool-result events (and
+ * user events carrying tool results) are AI activity; an assistant turn that
+ * stopped with `end_turn` or a user prompt is an ending event.
+ */
+function signalsFromEvents(events) {
+    let lastAiActivityIndex = -1;
+    let lastEndingIndex = -1;
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        const carriesToolResult = event.type === 'user' && hasToolResultBlock(event);
+        if (event.type === 'assistant' ||
+            event.type === 'tool_use' ||
+            event.type === 'tool_result' ||
+            carriesToolResult) {
+            lastAiActivityIndex = i;
+        }
+        if ((event.type === 'assistant' && event.message?.stop_reason === 'end_turn') ||
+            (event.type === 'user' && !carriesToolResult)) {
+            lastEndingIndex = i;
+        }
+    }
+    return { lastAiActivityIndex, lastEndingIndex, hasTerminal: false };
+}
+function classifyFromSignals(signals, mtimeMs, mtimeAge) {
+    const lastActivityTime = new Date(mtimeMs);
+    const { lastAiActivityIndex, lastEndingIndex, hasTerminal } = signals;
+    // Terminal patterns mean the session is definitely done
+    if (hasTerminal) {
+        return { state: 'ended', lastActivityTime, reason: 'terminal-event' };
+    }
+    // AI activity after the last ending event -> ongoing
+    if (lastAiActivityIndex > lastEndingIndex) {
+        return { state: 'ongoing', lastActivityTime, 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, reason: 'grace-period' };
+        }
+        return { state: 'ended', lastActivityTime, reason: 'ending-event' };
+    }
+    // No clear signal: if recently modified, assume ongoing
+    if (mtimeAge < GRACE_PERIOD_MS) {
+        return { state: 'ongoing', lastActivityTime, reason: 'recent-mtime' };
+    }
+    return { state: 'ended', lastActivityTime, reason: 'no-activity-signal' };
+}
+/**
+ * Classify a session from events already in memory, with the same states,
+ * reasons, grace period, and staleness rule as {@link detectSessionActivity},
+ * but without opening the file again. Works for every provider (the raw
+ * tail patterns only ever matched Claude Code JSONL) and for database-backed
+ * sessions that have no file to tail.
+ */
+export function classifySessionActivity(options) {
+    const now = options.now ?? Date.now();
+    const events = options.events;
+    const lastEventMs = events.length > 0 ? Date.parse(events[events.length - 1].timestamp) : NaN;
+    const mtimeMs = typeof options.mtimeMs === 'number' && Number.isFinite(options.mtimeMs)
+        ? options.mtimeMs
+        : Number.isFinite(lastEventMs)
+            ? lastEventMs
+            : null;
+    if (mtimeMs === null) {
+        return { state: 'ended', lastActivityTime: null, reason: 'no-events' };
+    }
+    const mtimeAge = now - mtimeMs;
+    if (mtimeAge > STALENESS_THRESHOLD_MS) {
+        return { state: 'stale', lastActivityTime: new Date(mtimeMs), reason: 'mtime-stale' };
+    }
+    if (events.length === 0) {
+        return { state: 'ended', lastActivityTime: new Date(mtimeMs), reason: 'no-events' };
+    }
+    const tail = events.length > TAIL_EVENTS ? events.slice(-TAIL_EVENTS) : events;
+    return classifyFromSignals(signalsFromEvents(tail), mtimeMs, mtimeAge);
+}
+/**
+ * Refresh a cached classification from its unchanged fingerprint without
+ * re-reading the transcript. An active file remains active until it crosses
+ * the same five-minute staleness boundary used by detectSessionActivity,
+ * unless it was active only by grace period (`previousReason`).
+ */
+export function refreshSessionActivityState(previous, mtimeMs, nowMs = Date.now(), previousReason) {
+    if (!Number.isFinite(mtimeMs))
+        return previous;
+    if (nowMs - mtimeMs > STALENESS_THRESHOLD_MS)
+        return 'idle';
+    if (previous === 'ended')
+        return 'ended';
+    if (previous === 'idle')
+        return 'idle';
+    // A session that was only active thanks to the grace period ends once the
+    // grace period lapses, exactly as a fresh classification would say.
+    if (previous === 'active' &&
+        (previousReason === 'grace-period' || previousReason === 'recent-mtime') &&
+        nowMs - mtimeMs >= GRACE_PERIOD_MS) {
+        return 'ended';
+    }
+    return previous === 'unknown' ? 'unknown' : 'active';
+}
+// ── 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;
+    }
+}