@ekkos/cli 0.2.7 → 0.2.8

package/dist/capture/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Stream capture types for mid-turn context preservation
+ */
+export type TurnStatus = 'in_progress' | 'complete';
+/**
+ * How a turn was sealed (closed)
+ */
+export type SealReason = 'user_boundary' | 'explicit' | 'process_exit' | 'context_wall';
+export interface ToolEvent {
+    kind: 'tool_use' | 'tool_result';
+    id: string;
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    is_error?: boolean;
+    ts: string;
+    transcript_line_uuid?: string;
+}
+export interface StreamTurn {
+    session_id: string;
+    session_name?: string;
+    turn_id: number;
+    started_at: string;
+    updated_at: string;
+    user_query?: string;
+    assistant_stream: string;
+    assistant_response?: string;
+    status: TurnStatus;
+    stream_offset: number;
+    tools: ToolEvent[];
+    files_referenced?: string[];
+    files_modified?: string[];
+    last_text_delta_ts?: string;
+    last_tool_event_ts?: string;
+    sealed_at?: string;
+    sealed_by?: SealReason;
+}
+export type StreamEvent = {
+    kind: 'session_start';
+    event_id: string;
+    session_id: string;
+    session_name?: string;
+    ts: string;
+} | {
+    kind: 'user_query';
+    event_id: string;
+    turn_id: number;
+    query: string;
+    ts: string;
+    transcript_line_uuid?: string;
+} | {
+    kind: 'assistant_text_delta';
+    event_id: string;
+    turn_id: number;
+    delta: string;
+    offset: number;
+    ts: string;
+    transcript_line_uuid?: string;
+} | {
+    kind: 'tool_use';
+    event_id: string;
+    turn_id: number;
+    id: string;
+    name: string;
+    input?: unknown;
+    ts: string;
+    transcript_line_uuid?: string;
+} | {
+    kind: 'tool_result';
+    event_id: string;
+    turn_id: number;
+    id: string;
+    output?: unknown;
+    is_error?: boolean;
+    ts: string;
+    transcript_line_uuid?: string;
+} | {
+    kind: 'seal_turn';
+    event_id: string;
+    turn_id: number;
+    reason: SealReason;
+    ts: string;
+};
+export interface TranscriptLine {
+    type: 'user' | 'assistant' | string;
+    uuid: string;
+    parentUuid?: string | null;
+    timestamp: string;
+    sessionId: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    isMeta?: boolean;
+    message: {
+        role: 'user' | 'assistant';
+        model?: string;
+        content: string | ContentBlock[];
+    };
+}
+export interface ContentBlock {
+    type: 'text' | 'thinking' | 'tool_use' | 'tool_result';
+    text?: string;
+    thinking?: string;
+    signature?: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+export interface TailerState {
+    transcriptPath: string;
+    sessionId: string;
+    sessionName?: string;
+    readOffset: number;
+    pendingBuffer: string;
+    currentTurnId: number;
+    currentTurnStatus: TurnStatus;
+    lastActivityTs: number;
+}
+/**
+ * Stream state - where are we in the conversation flow?
+ */
+export type StreamState = 'idle' | 'assistant_streaming' | 'tool_running' | 'interrupted' | 'wall_hit';
+/**
+ * Stream state machine - deterministic resume anchor
+ */
+export interface StreamStateMachine {
+    session_id: string;
+    session_name?: string;
+    state: StreamState;
+    state_entered_at: string;
+    last_complete_turn_id: number;
+    current_turn_id: number;
+    in_progress_text_head: string;
+    in_progress_text_tail: string;
+    in_progress_total_chars: number;
+    open_loops: Array<{
+        type: 'tool' | 'plan_step';
+        id: string;
+        name: string;
+        started_at: string;
+    }>;
+    last_event_ts: string;
+    last_checkpoint_ts: string;
+    stream_bytes_captured: number;
+    events_captured: number;
+}
+/**
+ * In-progress checkpoint - saved every N seconds for crash recovery
+ */
+export interface StreamCheckpoint {
+    session_id: string;
+    turn_id: number;
+    checkpoint_ts: string;
+    text_head: string;
+    text_tail: string;
+    state: StreamState;
+    open_loops: Array<{
+        type: string;
+        id: string;
+        name: string;
+        started_at: string;
+    }>;
+    total_chars: number;
+    events_since_last_checkpoint: number;
+}
+/**
+ * Open loop - work started but not completed
+ */
+export interface OpenLoop {
+    type: 'tool' | 'plan_step' | 'user_request';
+    name: string;
+    status: 'in_progress' | 'blocked' | 'waiting';
+    started_at: string;
+    context?: string;
+}
+/**
+ * Work phase derived from activity patterns
+ */
+export type WorkPhase = 'Plan' | 'Implement' | 'Verify' | 'Fix' | 'Deploy';
+/**
+ * WorkState Capsule - deterministic resume anchor for Time Machine
+ *
+ * This is the machine-derived state that guarantees perfect continuation.
+ * It's built from streaming capture data and injected by /continue.
+ */
+export interface WorkStateCapsule {
+    goal: string;
+    phase: WorkPhase;
+    next_step: string;
+    open_loops: OpenLoop[];
+    files_in_play: string[];
+    decisions_made: string[];
+    blockers?: string[];
+    last_good_output_tail: string;
+    continuation_instruction: string;
+    generated_at: string;
+    turn_id: number;
+    session_id: string;
+}
+/**
+ * Timeline event for Time Machine display
+ */
+export interface TimelineEvent {
+    turn_id: number;
+    timestamp: string;
+    phase: WorkPhase;
+    summary: string;
+    impact?: string;
+    tools_used: string[];
+    files_touched: string[];
+}
+/**
+ * Evidence entry for audit trail
+ */
+export interface EvidenceEntry {
+    turn_id: number;
+    timestamp: string;
+    tool_events: ToolEvent[];
+    files_touched: string[];
+    diff_summary?: string;
+    transcript_line_uuid: string;
+    transcript_path: string;
+    raw_transcript_offset?: number;
+}

package/dist/capture/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Stream capture types for mid-turn context preservation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/run.js

@@ -44,6 +44,7 @@ const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const state_1 = require("../utils/state");
 const doctor_1 = require("./doctor");
+const stream_tailer_1 = require("../capture/stream-tailer");
 // Try to load node-pty (may fail on Node 24+)
 let pty = null;
 try {
@@ -510,9 +511,55 @@ async function run(options) {
     (0, state_1.clearAutoClearFlag)();
     // Track state
     let currentSession = options.session || (0, state_1.getCurrentSessionName)();
+    // ════════════════════════════════════════════════════════════════════════════
+    // MULTI-SESSION SUPPORT: Register this process as an active session
+    // This prevents state collision when multiple Claude Code instances run
+    // ════════════════════════════════════════════════════════════════════════════
+    (0, state_1.registerActiveSession)('pending', // Session ID not yet known
+    currentSession || 'initializing', process.cwd());
+    dlog(`Registered active session (PID ${process.pid})`);
+    // Show active sessions count if verbose
+    if (verbose) {
+        const activeSessions = (0, state_1.getActiveSessions)();
+        if (activeSessions.length > 1) {
+            console.log(chalk_1.default.cyan(`  📊 Active ekkOS sessions: ${activeSessions.length}`));
+        }
+    }
     let isAutoClearInProgress = false;
     let transcriptPath = null;
     let currentSessionId = null;
+    // Stream tailer for mid-turn context capture
+    let streamTailer = null;
+    const streamCacheDir = path.join(os.homedir(), '.ekkos', 'cache', 'sessions');
+    // Helper to start stream tailer when we have transcript path
+    function startStreamTailer(tPath, sId, sName) {
+        if (streamTailer)
+            return; // Already running
+        try {
+            streamTailer = new stream_tailer_1.StreamTailer({
+                transcriptPath: tPath,
+                sessionId: sId,
+                sessionName: sName,
+                cacheDir: streamCacheDir,
+                onEvent: (event) => {
+                    dlog(`Stream event: ${event.kind} (turn ${event.turn_id || 'n/a'})`);
+                }
+            });
+            streamTailer.start();
+            dlog(`Stream tailer started for ${sName || sId}`);
+        }
+        catch (err) {
+            dlog(`Failed to start stream tailer: ${err.message}`);
+        }
+    }
+    // Helper to stop stream tailer
+    function stopStreamTailer() {
+        if (streamTailer) {
+            streamTailer.stop();
+            streamTailer = null;
+            dlog('Stream tailer stopped');
+        }
+    }
     // ══════════════════════════════════════════════════════════════════════════
     // SESSION NAME TRACKING (from live TUI output)
     // Claude prints: "· Turn N · groovy-koala-saves · 📅"
@@ -701,16 +748,26 @@ async function run(options) {
             }
         }
         // PRIORITY 4: Persisted state (last resort)
+        // CRITICAL: Always validate sessionName - persisted state may have invalid names
+        // like "claude-plugins-official" from directory names or false positives
         if (!sessionToRestore) {
             const state = (0, state_1.getState)();
-            sessionToRestore = state?.sessionName || null;
+            const persistedName = state?.sessionName || null;
             const sessionId = state?.sessionId || null;
-            // If still no session name but we have an ID, generate it
-            if (!sessionToRestore && sessionId) {
-                sessionToRestore = (0, state_1.uuidToWords)(sessionId);
+            // Validate persisted name - only use if it passes word list validation
+            if (persistedName && isValidSessionName(persistedName)) {
+                sessionToRestore = persistedName;
+                dlog(`Using validated persisted state: ${sessionToRestore}`);
             }
-            if (sessionToRestore) {
-                dlog(`Using persisted state (last resort): ${sessionToRestore}`);
+            else if (sessionId) {
+                // Derive from UUID if persisted name is invalid or missing
+                sessionToRestore = (0, state_1.uuidToWords)(sessionId);
+                if (persistedName) {
+                    dlog(`Persisted name "${persistedName}" invalid, derived from UUID: ${sessionToRestore}`);
+                }
+                else {
+                    dlog(`No persisted name, derived from UUID: ${sessionToRestore}`);
+                }
             }
         }
         const sessionDisplay = sessionToRestore || 'unknown-session';
@@ -796,18 +853,35 @@ async function run(options) {
             outputBuffer = outputBuffer.slice(-2000);
         }
         // Try to extract transcript path from output (Claude shows it on startup)
-        const transcriptMatch = data.match(/transcript[_\s]?(?:path)?[:\s]+([^\s\n]+\.json)/i);
+        const transcriptMatch = data.match(/transcript[_\s]?(?:path)?[:\s]+([^\s\n]+\.jsonl?)/i);
         if (transcriptMatch) {
             transcriptPath = transcriptMatch[1];
             dlog(`Detected transcript: ${transcriptPath}`);
+            // Start tailer if we have session ID
+            if (currentSessionId && transcriptPath) {
+                startStreamTailer(transcriptPath, currentSessionId, currentSession || undefined);
+            }
         }
         // Try to extract session ID from output (fallback - Claude rarely prints this)
         const sessionMatch = data.match(/session[_\s]?(?:id)?[:\s]+([a-f0-9-]{36})/i);
         if (sessionMatch) {
             currentSessionId = sessionMatch[1];
             currentSession = (0, state_1.uuidToWords)(currentSessionId);
+            // Update THIS process's session entry (not global state.json)
+            (0, state_1.updateCurrentProcessSession)(currentSessionId, currentSession);
+            // Also update global state for backwards compatibility
             (0, state_1.updateState)({ sessionId: currentSessionId, sessionName: currentSession });
             dlog(`Session detected from UUID: ${currentSession}`);
+            // Try to find/construct transcript path from session ID
+            if (!transcriptPath) {
+                const encodedCwd = process.cwd().replace(/\//g, '-').replace(/^-/, '');
+                const possibleTranscript = path.join(os.homedir(), '.claude', 'projects', encodedCwd, `${currentSessionId}.jsonl`);
+                if (fs.existsSync(possibleTranscript)) {
+                    transcriptPath = possibleTranscript;
+                    dlog(`Found transcript from session ID: ${transcriptPath}`);
+                    startStreamTailer(transcriptPath, currentSessionId, currentSession || undefined);
+                }
+            }
         }
         // ════════════════════════════════════════════════════════════════════════
         // SESSION NAME DETECTION (PRIMARY METHOD)
@@ -829,8 +903,37 @@ async function run(options) {
                 lastSeenSessionAt = Date.now();
                 currentSession = lastSeenSessionName;
                 observedSessionThisRun = true; // Mark that we've seen a session in THIS process
+                // Update THIS process's session entry (not global state.json)
+                (0, state_1.updateCurrentProcessSession)(currentSessionId || 'unknown', currentSession);
+                // Also update global state for backwards compatibility
                 (0, state_1.updateState)({ sessionName: currentSession });
                 dlog(`Session detected from status line: ${currentSession} (observedSessionThisRun=true)`);
+                // Try to start stream tailer - scan for matching transcript file
+                if (!streamTailer) {
+                    const encodedCwd = process.cwd().replace(/\//g, '-').replace(/^-/, '');
+                    const projectDir = path.join(os.homedir(), '.claude', 'projects', encodedCwd);
+                    try {
+                        const files = fs.readdirSync(projectDir);
+                        // Find most recent .jsonl file (likely current session)
+                        const jsonlFiles = files
+                            .filter(f => f.endsWith('.jsonl'))
+                            .map(f => ({
+                            name: f,
+                            path: path.join(projectDir, f),
+                            mtime: fs.statSync(path.join(projectDir, f)).mtimeMs
+                        }))
+                            .sort((a, b) => b.mtime - a.mtime);
+                        if (jsonlFiles.length > 0) {
+                            transcriptPath = jsonlFiles[0].path;
+                            currentSessionId = jsonlFiles[0].name.replace('.jsonl', '');
+                            dlog(`Found transcript from project scan: ${transcriptPath}`);
+                            startStreamTailer(transcriptPath, currentSessionId, currentSession);
+                        }
+                    }
+                    catch {
+                        // Project dir might not exist yet
+                    }
+                }
             }
             else {
                 // Same session, just update timestamp
@@ -851,6 +954,9 @@ async function run(options) {
                     lastSeenSessionAt = Date.now();
                     currentSession = lastSeenSessionName;
                     observedSessionThisRun = true; // Mark that we've seen a session in THIS process
+                    // Update THIS process's session entry (not global state.json)
+                    (0, state_1.updateCurrentProcessSession)(currentSessionId || 'unknown', currentSession);
+                    // Also update global state for backwards compatibility
                     (0, state_1.updateState)({ sessionName: currentSession });
                     dlog(`Session detected from generic match: ${currentSession} (observedSessionThisRun=true)`);
                 }
@@ -874,6 +980,8 @@ async function run(options) {
     // Handle PTY exit
     shell.onExit(({ exitCode }) => {
         (0, state_1.clearAutoClearFlag)();
+        stopStreamTailer(); // Stop stream capture
+        (0, state_1.unregisterActiveSession)(); // Remove from active sessions registry
         // Restore terminal
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(false);
@@ -886,6 +994,8 @@ async function run(options) {
     // Cleanup on exit signals
     const cleanup = () => {
         (0, state_1.clearAutoClearFlag)();
+        stopStreamTailer(); // Stop stream capture
+        (0, state_1.unregisterActiveSession)(); // Remove from active sessions registry
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(false);
         }

package/dist/commands/stream.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ekkos stream - Stream capture status and management
+ *
+ * Shows live status of stream capture for debugging and support.
+ */
+interface StreamStatusOptions {
+    session?: string;
+    watch?: boolean;
+    json?: boolean;
+}
+/**
+ * Display stream status
+ */
+export declare function streamStatus(options: StreamStatusOptions): Promise<void>;
+/**
+ * List all sessions with stream data
+ */
+export declare function streamList(): void;
+export {};