lattice-orchestrator 0.7.0

package/dist/services/insights/insight-queue.js

@@ -0,0 +1,277 @@
+/**
+ * InsightQueue - Serializes insight operations per session to eliminate race conditions.
+ *
+ * The Problem This Solves:
+ * Previously, background regenerations could race with patches:
+ *   T+0s: Patch starts (Haiku)
+ *   T+1s: Background regen starts (Opus)
+ *   T+5s: Patch completes, writes to cache
+ *   T+8s: Regen completes, merge decision uses stale snapshot, overwrites patch
+ *
+ * The Solution:
+ * All insight operations go through this queue. Operations for the same session
+ * are serialized - a REFRESH can't start until the PATCH completes.
+ *
+ * Key Design Decisions:
+ * - One queue per session (different sessions can run in parallel)
+ * - Operations coalesce (if PATCH is queued and another PATCH comes in, skip the new one)
+ * - Priority ordering: PATCH > GENERATE > REFRESH
+ * - In-memory only (operations are idempotent, no need for persistence)
+ */
+import { EventEmitter } from 'events';
+import { createLogger } from '../infrastructure/logger.js';
+// Priority ordering: lower number = higher priority
+const PRIORITY_ORDER = {
+    high: 0,
+    normal: 1,
+    low: 2,
+};
+// Type ordering within same priority: PATCH > GENERATE > REFRESH
+const TYPE_ORDER = {
+    PATCH: 0,
+    GENERATE: 1,
+    REFRESH: 2,
+};
+/**
+ * Compare two operations for queue ordering.
+ * Returns negative if a should come before b.
+ */
+function compareOperations(a, b) {
+    // First by priority
+    const priorityDiff = PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority];
+    if (priorityDiff !== 0)
+        return priorityDiff;
+    // Then by type
+    const typeDiff = TYPE_ORDER[a.type] - TYPE_ORDER[b.type];
+    if (typeDiff !== 0)
+        return typeDiff;
+    // Finally by enqueue time (FIFO within same priority+type)
+    return a.enqueuedAt - b.enqueuedAt;
+}
+export class InsightQueue extends EventEmitter {
+    logger;
+    queues = new Map();
+    processing = new Set();
+    // Track what operation type is currently being processed per session
+    processingType = new Map();
+    stats = {
+        totalEnqueued: 0,
+        totalProcessed: 0,
+        totalSkipped: 0,
+        byType: { GENERATE: 0, PATCH: 0, REFRESH: 0 },
+        byTrigger: {},
+    };
+    // Executor function - injected to avoid circular dependencies
+    executor = null;
+    constructor() {
+        super();
+        this.logger = createLogger('InsightQueue');
+    }
+    /**
+     * Set the executor function that processes operations.
+     * This is injected to break the circular dependency between queue and handler.
+     */
+    setExecutor(executor) {
+        this.executor = executor;
+        this.logger.info('Executor set');
+    }
+    /**
+     * Enqueue an insight operation.
+     * Operations are coalesced (duplicate type+session skipped) and prioritized.
+     */
+    enqueue(op) {
+        const operation = {
+            ...op,
+            enqueuedAt: Date.now(),
+        };
+        const queue = this.queues.get(op.sessionId) || [];
+        // Coalesce: skip if same operation type is already queued OR currently processing
+        const isQueued = queue.some(q => q.type === op.type);
+        const isProcessing = this.processingType.get(op.sessionId) === op.type;
+        if (isQueued || isProcessing) {
+            this.stats.totalSkipped++;
+            this.logger.debug('Operation coalesced', {
+                sessionId: op.sessionId.slice(0, 8),
+                type: op.type,
+                trigger: op.trigger,
+                reason: isProcessing ? 'already_processing' : 'already_queued',
+                queueLength: queue.length,
+            });
+            return false;
+        }
+        // Add to queue and sort by priority
+        queue.push(operation);
+        queue.sort(compareOperations);
+        this.queues.set(op.sessionId, queue);
+        // Update stats
+        this.stats.totalEnqueued++;
+        this.stats.byType[op.type]++;
+        this.stats.byTrigger[op.trigger] = (this.stats.byTrigger[op.trigger] || 0) + 1;
+        this.logger.debug('Operation enqueued', {
+            sessionId: op.sessionId.slice(0, 8),
+            type: op.type,
+            priority: op.priority,
+            trigger: op.trigger,
+            queueLength: queue.length,
+            traceId: op.traceId,
+        });
+        // Emit event for monitoring
+        this.emit('enqueued', operation);
+        // Start processing if not already running
+        this.processNext(op.sessionId);
+        return true;
+    }
+    /**
+     * Process the next operation in a session's queue.
+     * This is the serialization point - only one operation per session at a time.
+     */
+    async processNext(sessionId) {
+        // Already processing this session - wait for current operation to complete
+        if (this.processing.has(sessionId)) {
+            return;
+        }
+        const queue = this.queues.get(sessionId);
+        if (!queue || queue.length === 0) {
+            return;
+        }
+        if (!this.executor) {
+            this.logger.error('No executor set - cannot process operations');
+            return;
+        }
+        // Mark as processing
+        this.processing.add(sessionId);
+        const op = queue.shift();
+        this.processingType.set(sessionId, op.type);
+        const startTime = Date.now();
+        this.logger.debug('Processing operation', {
+            sessionId: sessionId.slice(0, 8),
+            type: op.type,
+            trigger: op.trigger,
+            waitTimeMs: startTime - op.enqueuedAt,
+            traceId: op.traceId,
+        });
+        // Emit event for monitoring
+        this.emit('processing', op);
+        try {
+            await this.executor(op);
+            const durationMs = Date.now() - startTime;
+            this.stats.totalProcessed++;
+            this.logger.debug('Operation completed', {
+                sessionId: sessionId.slice(0, 8),
+                type: op.type,
+                trigger: op.trigger,
+                durationMs,
+                traceId: op.traceId,
+            });
+            // Emit event for monitoring
+            this.emit('completed', { ...op, durationMs });
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            this.logger.error('Operation failed', {
+                sessionId: sessionId.slice(0, 8),
+                type: op.type,
+                trigger: op.trigger,
+                durationMs,
+                error: error instanceof Error ? error.message : String(error),
+                traceId: op.traceId,
+            });
+            // Emit event for monitoring
+            this.emit('failed', { ...op, durationMs, error });
+        }
+        finally {
+            // Mark as no longer processing
+            this.processing.delete(sessionId);
+            this.processingType.delete(sessionId);
+            // Process next in queue (if any)
+            this.processNext(sessionId);
+        }
+    }
+    /**
+     * Get the current queue for a session (for debugging/UI).
+     */
+    getQueue(sessionId) {
+        return [...(this.queues.get(sessionId) || [])];
+    }
+    /**
+     * Check if a session is currently being processed.
+     */
+    isProcessing(sessionId) {
+        return this.processing.has(sessionId);
+    }
+    /**
+     * Get the operation type currently being processed for a session.
+     */
+    getProcessingType(sessionId) {
+        return this.processingType.get(sessionId);
+    }
+    /**
+     * Get the number of pending operations for a session.
+     */
+    getPendingCount(sessionId) {
+        return this.queues.get(sessionId)?.length || 0;
+    }
+    /**
+     * Get all sessions with pending operations.
+     */
+    getActiveSessionIds() {
+        return Array.from(this.queues.keys()).filter(sessionId => (this.queues.get(sessionId)?.length || 0) > 0 || this.processing.has(sessionId));
+    }
+    /**
+     * Get queue statistics.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Clear the queue for a session (e.g., when session is archived).
+     */
+    clearSession(sessionId) {
+        const queue = this.queues.get(sessionId);
+        if (queue && queue.length > 0) {
+            this.logger.info('Clearing session queue', {
+                sessionId: sessionId.slice(0, 8),
+                droppedOperations: queue.length,
+            });
+        }
+        this.queues.delete(sessionId);
+    }
+    /**
+     * Shutdown the queue (for graceful server shutdown).
+     * Waits for in-flight operations to complete but doesn't process new ones.
+     */
+    async shutdown(timeoutMs = 30000) {
+        this.logger.info('Shutting down insight queue', {
+            processingCount: this.processing.size,
+            pendingCount: Array.from(this.queues.values()).reduce((sum, q) => sum + q.length, 0),
+        });
+        // Clear all pending queues
+        this.queues.clear();
+        // Wait for in-flight operations to complete
+        const startTime = Date.now();
+        while (this.processing.size > 0 && Date.now() - startTime < timeoutMs) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        if (this.processing.size > 0) {
+            this.logger.warn('Shutdown timed out with operations still processing', {
+                remainingCount: this.processing.size,
+            });
+        }
+        else {
+            this.logger.info('Insight queue shutdown complete');
+        }
+    }
+}
+// Singleton instance
+let instance = null;
+export function getInsightQueue() {
+    if (!instance) {
+        instance = new InsightQueue();
+    }
+    return instance;
+}
+// For testing - allows resetting the singleton
+export function resetInsightQueue() {
+    instance = null;
+}
+//# sourceMappingURL=insight-queue.js.map

package/dist/services/insights/insight-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight-queue.js","sourceRoot":"","sources":["../../../src/services/insights/insight-queue.ts"],"names":[],"mappings":"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"}

package/dist/services/insights/insights-computer.d.ts

@@ -0,0 +1,132 @@
+import { ClaudeHistoryReader } from '../sessions/claude-history-reader.js';
+import { SessionInfoService } from '../sessions/session-info-service.js';
+import type { ConversationMessage, SessionContext, SessionEvent, SessionInsights, SessionMilestone, SessionProgress, SessionTags, TodoItem } from '../../types/index.js';
+export type { SessionInsights, SessionMilestone, SessionProgress, TodoItem } from '../../types/index.js';
+/**
+ * InsightsComputer - The computational engine for generating insights.
+ *
+ * This service handles the actual LLM calls and prompt construction for insights.
+ * It does NOT coordinate when to generate insights - that's InsightsCoordinator's job.
+ *
+ * Responsibilities:
+ * - Building prompts for insight generation
+ * - Calling Anthropic/Gemini APIs
+ * - Caching computed insights
+ * - Generating identity images
+ *
+ * Related services:
+ * - InsightsCoordinator (insights-coordinator.ts) - orchestrates when to compute
+ * - AnthropicService (anthropic-service.ts) - actual API calls
+ */
+export declare class InsightsComputer {
+    private logger;
+    private historyReader;
+    private sessionInfoService;
+    constructor(historyReader: ClaudeHistoryReader, sessionInfoService?: SessionInfoService);
+    /**
+     * Check if a session is automated (e.g., Claudia sessions).
+     * Automated sessions should skip expensive AI insight generation.
+     */
+    isAutomatedSession(sessionId: string): Promise<boolean>;
+    /**
+     * Extract the final todo state from conversation messages
+     */
+    extractTodoState(messages: ConversationMessage[]): TodoItem[] | null;
+    /**
+     * Compute progress from todo state
+     */
+    computeProgress(todos: TodoItem[]): SessionProgress;
+    /**
+     * Extract the last N actions from recent messages (tool uses, user messages, assistant text)
+     * Returns an array of {tool, timestamp} for mini action log display
+     */
+    extractRecentActions(messages: ConversationMessage[], limit?: number): Array<{
+        tool: string;
+        timestamp: number;
+    }>;
+    /**
+     * Extract user prompts from conversation
+     */
+    extractUserPrompts(messages: ConversationMessage[]): string[];
+    /**
+     * Extract recent assistant text responses (last N messages)
+     * Used to capture outcomes and progress for insight generation
+     */
+    extractRecentAssistantText(messages: ConversationMessage[], limit?: number): string[];
+    /**
+     * Format a tool call into a human-readable action description
+     */
+    private formatToolAction;
+    /**
+     * Extract filename from a path for display
+     */
+    private extractFilename;
+    /**
+     * Generate rich structured session insights using Opus 4.5
+     */
+    generateStructuredInsights(messages: ConversationMessage[], sessionId?: string): Promise<{
+        context: SessionContext | null;
+        milestones: SessionMilestone[];
+        notable: SessionEvent[];
+        recentActions: string[];
+        theme: string | null;
+        tags: SessionTags | null;
+    }>;
+    /**
+     * Get full insights for a session (checks cache first)
+     * For automated sessions, returns quick insights without AI generation.
+     *
+     * NON-BLOCKING BEHAVIOR:
+     * - If cache is fresh → return it immediately
+     * - If cache is stale → return stale data immediately, trigger background regeneration
+     * - If no cache → generate synchronously (first time only)
+     */
+    getInsights(sessionId: string): Promise<SessionInsights>;
+    /**
+     * Regenerate insights in the background (for stale cache refresh).
+     * This runs async and updates the cache when done.
+     */
+    private regenerateInsightsInBackground;
+    /**
+     * Compute insights from conversation (bypasses cache)
+     */
+    computeInsights(sessionId: string): Promise<SessionInsights & {
+        messageCount: number;
+    }>;
+    /**
+     * Cache insights to database
+     */
+    cacheInsights(sessionId: string, insights: SessionInsights & {
+        messageCount?: number;
+    }): Promise<void>;
+    /**
+     * Generate identity image for a session if it doesn't already have one.
+     * This is called after insights are cached/patched, and runs in the background.
+     * Public so InsightsCoordinator can call it after patching too.
+     */
+    maybeGenerateIdentityImage(sessionId: string, insights: SessionInsights): Promise<void>;
+    /**
+     * Convert cached insights to SessionInsights format
+     */
+    private cachedToSessionInsights;
+    /**
+     * Get cached insights for multiple sessions (for list view)
+     */
+    getCachedInsightsForSessions(sessionIds: string[]): Promise<Map<string, SessionInsights>>;
+    /**
+     * Compute and cache insights for sessions that don't have cached insights
+     */
+    computeMissingInsights(sessionIds: string[], maxConcurrent?: number): Promise<number>;
+    /**
+     * Recompute insights for stale sessions (force refresh)
+     * Preserves accumulated milestones/notable from existing cache if new result is empty
+     */
+    recomputeStaleInsights(sessionIds: string[], maxConcurrent?: number): Promise<number>;
+    /**
+     * Get insights without AI generation (faster, for list views)
+     */
+    getInsightsQuick(sessionId: string): Promise<SessionInsights>;
+}
+/** @deprecated Use InsightsComputer instead */
+export declare const SessionInsightsService: typeof InsightsComputer;
+//# sourceMappingURL=insights-computer.d.ts.map

package/dist/services/insights/insights-computer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-computer.d.ts","sourceRoot":"","sources":["../../../src/services/insights/insights-computer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,OAAO,EAAE,kBAAkB,EAAkB,MAAM,qCAAqC,CAAC;AAmDzF,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAErG;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,kBAAkB,CAAqB;gBAEnC,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,CAAC,EAAE,kBAAkB;IAMvF;;;OAGG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU7D;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI;IA6BpE;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,eAAe;IAUnD;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,EAAE,KAAK,GAAE,MAAW,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA8FrH;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE;IA4B7D;;;OAGG;IACH,0BAA0B,CAAC,QAAQ,EAAE,mBAAmB,EAAE,EAAE,KAAK,GAAE,MAAU,GAAG,MAAM,EAAE;IA8BxF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqCxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACG,0BAA0B,CAAC,QAAQ,EAAE,mBAAmB,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAC7F,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;QAC/B,UAAU,EAAE,gBAAgB,EAAE,CAAC;QAC/B,OAAO,EAAE,YAAY,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;KAC1B,CAAC;IAgDF;;;;;;;;OAQG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAuH9D;;;OAGG;YACW,8BAA8B;IAuD5C;;OAEG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAsE7F;;OAEG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoF5G;;;;OAIG;IACG,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD7F;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAsC/B;;OAEG;IACG,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAc/F;;OAEG;IACG,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,aAAa,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BtF;;;OAGG;IACG,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,aAAa,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAiGtF;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAmDpE;AAGD,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,yBAAmB,CAAC"}