@guidemode/session-processing 0.1.43

package/dist/esm/processors/canonical/index.js

@@ -0,0 +1,42 @@
+/**
+ * Unified Canonical Session Processor
+ *
+ * Single processor that works for all providers using the canonical format.
+ * Consolidates 5+ provider-specific processors into one.
+ */
+import { CanonicalParser } from '../../parsers/index.js';
+import { BaseProviderProcessor } from '../base/index.js';
+import { CanonicalContextProcessor } from './metrics/context.js';
+import { CanonicalEngagementProcessor } from './metrics/engagement.js';
+import { CanonicalErrorProcessor } from './metrics/error.js';
+import { CanonicalPerformanceProcessor } from './metrics/performance.js';
+import { CanonicalQualityProcessor } from './metrics/quality.js';
+import { CanonicalUsageProcessor } from './metrics/usage.js';
+export class CanonicalSessionProcessor extends BaseProviderProcessor {
+    providerName = 'canonical';
+    description = 'Unified session processor for all providers using canonical format';
+    parser = new CanonicalParser();
+    metricProcessors;
+    constructor() {
+        super();
+        // Initialize all unified metric processors
+        this.metricProcessors = [
+            new CanonicalPerformanceProcessor(),
+            new CanonicalEngagementProcessor(),
+            new CanonicalQualityProcessor(),
+            new CanonicalUsageProcessor(),
+            new CanonicalErrorProcessor(),
+            new CanonicalContextProcessor(),
+        ];
+    }
+    parseSession(jsonlContent, _provider) {
+        this.validateJsonlContent(jsonlContent);
+        return this.parser.parseSession(jsonlContent);
+    }
+    getMetricProcessors() {
+        return this.metricProcessors;
+    }
+}
+// Export metric processors for testing
+export { CanonicalEngagementProcessor, CanonicalUsageProcessor, CanonicalQualityProcessor, CanonicalPerformanceProcessor, CanonicalErrorProcessor, CanonicalContextProcessor, };
+//# sourceMappingURL=index.js.map

package/dist/esm/processors/canonical/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/processors/canonical/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAA4B,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAA;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAA;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,MAAM,OAAO,yBAA0B,SAAQ,qBAAqB;IACzD,YAAY,GAAG,WAAW,CAAA;IAC1B,WAAW,GAAG,oEAAoE,CAAA;IAEnF,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IAC9B,gBAAgB,CAAuB;IAE/C;QACE,KAAK,EAAE,CAAA;QAEP,2CAA2C;QAC3C,IAAI,CAAC,gBAAgB,GAAG;YACtB,IAAI,6BAA6B,EAAE;YACnC,IAAI,4BAA4B,EAAE;YAClC,IAAI,yBAAyB,EAAE;YAC/B,IAAI,uBAAuB,EAAE;YAC7B,IAAI,uBAAuB,EAAE;YAC7B,IAAI,yBAAyB,EAAE;SAChC,CAAA;IACH,CAAC;IAED,YAAY,CAAC,YAAoB,EAAE,SAAiB;QAClD,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAA;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAA;IAC/C,CAAC;IAED,mBAAmB;QACjB,OAAO,IAAI,CAAC,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,uCAAuC;AACvC,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACvB,yBAAyB,GAC1B,CAAA"}

package/dist/esm/processors/canonical/metrics/context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Unified Context Metrics Processor
+ *
+ * Works for providers with token data (Claude Code, Codex).
+ * Tracks token usage, cache efficiency, and context compaction events.
+ * Returns null for providers without token data.
+ */
+import type { ContextManagementMetrics } from '@guidemode/types';
+import type { ParsedSession } from '../../../parsers/base/types.js';
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export declare class CanonicalContextProcessor extends BaseMetricProcessor {
+    readonly name = "canonical-context";
+    readonly metricType: "context-management";
+    readonly description = "Tracks token usage, cache efficiency, and context management (unified for all providers)";
+    private readonly CONTEXT_WINDOW_SIZE;
+    /**
+     * Check if session has token data (required for context metrics)
+     */
+    canProcess(session: ParsedSession): boolean;
+    process(session: ParsedSession): Promise<ContextManagementMetrics>;
+    /**
+     * Calculate token totals from the session
+     */
+    private calculateTotals;
+    /**
+     * Detect compact events in the session
+     */
+    private detectCompactEvents;
+    /**
+     * Calculate average input tokens per message
+     */
+    private calculateAvgTokensPerMessage;
+    /**
+     * Generate improvement tips
+     */
+    private generateImprovementTips;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/esm/processors/canonical/metrics/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../../src/processors/canonical/metrics/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEpE,qBAAa,yBAA0B,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,IAAI,uBAAsB;IACnC,QAAQ,CAAC,UAAU,EAAG,oBAAoB,CAAS;IACnD,QAAQ,CAAC,WAAW,8FACwE;IAG5F,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO;IAIrC,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAgCxE;;OAEG;IACH,OAAO,CAAC,eAAe;IA6DvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAqBpC;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAuChC"}

package/dist/esm/processors/canonical/metrics/context.js

@@ -0,0 +1,153 @@
+/**
+ * Unified Context Metrics Processor
+ *
+ * Works for providers with token data (Claude Code, Codex).
+ * Tracks token usage, cache efficiency, and context compaction events.
+ * Returns null for providers without token data.
+ */
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export class CanonicalContextProcessor extends BaseMetricProcessor {
+    name = 'canonical-context';
+    metricType = 'context-management';
+    description = 'Tracks token usage, cache efficiency, and context management (unified for all providers)';
+    // Claude Sonnet 4.5 context window (providers may vary)
+    CONTEXT_WINDOW_SIZE = 200000;
+    /**
+     * Check if session has token data (required for context metrics)
+     */
+    canProcess(session) {
+        return session.messages.some(m => m.metadata?.usage);
+    }
+    async process(session) {
+        // Calculate totals
+        const totals = this.calculateTotals(session);
+        // Detect compact events
+        const compactEvents = this.detectCompactEvents(session);
+        // Calculate average tokens per message
+        const avgTokensPerMessage = this.calculateAvgTokensPerMessage(session);
+        // Calculate context utilization
+        const contextUtilization = (totals.contextLength / this.CONTEXT_WINDOW_SIZE) * 100;
+        // Generate improvement tips
+        const improvementTips = this.generateImprovementTips(compactEvents, totals, contextUtilization);
+        return {
+            total_input_tokens: totals.totalInputTokens,
+            total_output_tokens: totals.totalOutputTokens,
+            total_cache_created: totals.totalCacheCreated,
+            total_cache_read: totals.totalCacheRead,
+            context_length: totals.contextLength,
+            context_window_size: this.CONTEXT_WINDOW_SIZE,
+            context_utilization_percent: contextUtilization,
+            compact_event_count: compactEvents.count,
+            compact_event_steps: JSON.stringify(compactEvents.steps),
+            avg_tokens_per_message: avgTokensPerMessage,
+            messages_until_first_compact: compactEvents.firstCompactStep,
+            context_improvement_tips: JSON.stringify(improvementTips),
+        };
+    }
+    /**
+     * Calculate token totals from the session
+     */
+    calculateTotals(session) {
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCacheCreated = 0;
+        let totalCacheRead = 0;
+        let contextLength = 0;
+        let mostRecentTimestamp = null;
+        let mostRecentUsage = null;
+        for (const message of session.messages) {
+            const usage = message.metadata?.usage;
+            if (usage) {
+                // Sum all tokens
+                totalInputTokens += usage.input_tokens || 0;
+                totalOutputTokens += usage.output_tokens || 0;
+                totalCacheCreated += usage.cache_creation_input_tokens || 0;
+                totalCacheRead += usage.cache_read_input_tokens || 0;
+                // Track most recent main chain message for context_length
+                const isSidechain = message.metadata?.isSidechain === true;
+                if (!isSidechain &&
+                    message.timestamp &&
+                    (!mostRecentTimestamp || message.timestamp > mostRecentTimestamp)) {
+                    mostRecentTimestamp = message.timestamp;
+                    mostRecentUsage = usage;
+                }
+            }
+        }
+        // Calculate context_length from most recent main chain message
+        if (mostRecentUsage) {
+            contextLength =
+                (mostRecentUsage.input_tokens || 0) +
+                    (mostRecentUsage.cache_read_input_tokens || 0) +
+                    (mostRecentUsage.cache_creation_input_tokens || 0);
+        }
+        return {
+            totalInputTokens,
+            totalOutputTokens,
+            totalCacheCreated,
+            totalCacheRead,
+            contextLength,
+        };
+    }
+    /**
+     * Detect compact events in the session
+     */
+    detectCompactEvents(session) {
+        const compactSteps = [];
+        session.messages.forEach((message, index) => {
+            if (message.type === 'compact') {
+                compactSteps.push(index + 1); // 1-based indexing
+            }
+        });
+        return {
+            count: compactSteps.length,
+            steps: compactSteps,
+            firstCompactStep: compactSteps.length > 0 ? compactSteps[0] : null,
+        };
+    }
+    /**
+     * Calculate average input tokens per message
+     */
+    calculateAvgTokensPerMessage(session) {
+        let totalInputTokens = 0;
+        let messageCount = 0;
+        for (const message of session.messages) {
+            const usage = message.metadata?.usage;
+            const inputTokens = usage?.input_tokens || 0;
+            if (inputTokens > 0) {
+                totalInputTokens += inputTokens;
+                messageCount++;
+            }
+        }
+        return messageCount > 0 ? Math.round(totalInputTokens / messageCount) : 0;
+    }
+    /**
+     * Generate improvement tips
+     */
+    generateImprovementTips(compactEvents, totals, contextUtilization) {
+        const tips = [];
+        // Context utilization tips
+        if (contextUtilization > 80) {
+            tips.push('High context utilization - consider compacting context or breaking into smaller sessions');
+        }
+        if (contextUtilization > 90) {
+            tips.push('Very high context utilization - approaching limit, compact soon to avoid issues');
+        }
+        // Cache efficiency tips
+        const cacheHitRate = totals.totalCacheCreated > 0 ? totals.totalCacheRead / totals.totalCacheCreated : 0;
+        if (cacheHitRate > 0.5) {
+            tips.push('Good cache efficiency - prompt caching is working well');
+        }
+        else if (cacheHitRate > 0 && cacheHitRate <= 0.5) {
+            tips.push('Moderate cache efficiency - consider more consistent context patterns');
+        }
+        // Compact event tips
+        if (compactEvents.count === 0 && contextUtilization > 60) {
+            tips.push('Consider using /compact command to manage context size proactively');
+        }
+        if (compactEvents.count > 3) {
+            tips.push('Frequent compaction - consider breaking this into multiple shorter sessions');
+        }
+        return tips;
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/esm/processors/canonical/metrics/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../src/processors/canonical/metrics/context.ts"],"names":[],"mappings":"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"}

package/dist/esm/processors/canonical/metrics/engagement.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unified Engagement Metrics Processor
+ *
+ * Works for all providers using the canonical format.
+ * Measures interruption rate and session length.
+ */
+import type { EngagementMetrics } from '@guidemode/types';
+import type { ParsedSession } from '../../../parsers/base/types.js';
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export declare class CanonicalEngagementProcessor extends BaseMetricProcessor {
+    readonly name = "canonical-engagement";
+    readonly metricType: "engagement";
+    readonly description = "Measures interruption rate and session length (unified for all providers)";
+    process(session: ParsedSession): Promise<EngagementMetrics>;
+    /**
+     * Find interruption messages
+     * An interruption is when:
+     * 1. Message has canonical type 'interruption'
+     * 2. User sends consecutive messages (without assistant response in between)
+     * 3. User message contains interruption keywords (stop, wait, actually, no)
+     */
+    private findInterruptions;
+    /**
+     * Extract text content from message (handles both string and structured content)
+     */
+    private extractTextContent;
+    /**
+     * Generate improvement tips based on metrics
+     */
+    private generateImprovementTips;
+}
+//# sourceMappingURL=engagement.d.ts.map

package/dist/esm/processors/canonical/metrics/engagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../../../../../src/processors/canonical/metrics/engagement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEpE,qBAAa,4BAA6B,SAAQ,mBAAmB;IACnE,QAAQ,CAAC,IAAI,0BAAyB;IACtC,QAAQ,CAAC,UAAU,EAAG,YAAY,CAAS;IAC3C,QAAQ,CAAC,WAAW,+EAA8E;IAE5F,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA8BjE;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IA+CzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAmBhC"}

package/dist/esm/processors/canonical/metrics/engagement.js

@@ -0,0 +1,114 @@
+/**
+ * Unified Engagement Metrics Processor
+ *
+ * Works for all providers using the canonical format.
+ * Measures interruption rate and session length.
+ */
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export class CanonicalEngagementProcessor extends BaseMetricProcessor {
+    name = 'canonical-engagement';
+    metricType = 'engagement';
+    description = 'Measures interruption rate and session length (unified for all providers)';
+    async process(session) {
+        const userMessages = session.messages.filter(m => m.type === 'user');
+        const assistantMessages = session.messages.filter(m => m.type === 'assistant');
+        if (userMessages.length === 0 || assistantMessages.length === 0) {
+            return {
+                interruption_rate: 0,
+                total_interruptions: 0,
+                session_length_minutes: 0,
+            };
+        }
+        // Calculate interruption rate
+        const interruptions = this.findInterruptions(session.messages);
+        const interruptionRate = Math.round((interruptions.length / assistantMessages.length) * 100);
+        // Calculate session length in minutes
+        const sessionLengthMinutes = Math.round(session.duration / (1000 * 60));
+        return {
+            interruption_rate: interruptionRate,
+            total_interruptions: interruptions.length,
+            session_length_minutes: sessionLengthMinutes,
+            metadata: {
+                total_responses: assistantMessages.length,
+                improvement_tips: this.generateImprovementTips(interruptionRate, sessionLengthMinutes),
+            },
+        };
+    }
+    /**
+     * Find interruption messages
+     * An interruption is when:
+     * 1. Message has canonical type 'interruption'
+     * 2. User sends consecutive messages (without assistant response in between)
+     * 3. User message contains interruption keywords (stop, wait, actually, no)
+     */
+    findInterruptions(messages) {
+        const interruptions = [];
+        const interruptionIds = new Set(); // Prevent duplicates
+        for (let i = 1; i < messages.length; i++) {
+            const current = messages[i];
+            const previous = messages[i - 1];
+            // Skip if already marked as interruption
+            if (interruptionIds.has(current.id)) {
+                continue;
+            }
+            // Type 1: Canonical interruption message type
+            if (current.type === 'interruption') {
+                interruptions.push(current);
+                interruptionIds.add(current.id);
+                continue;
+            }
+            // Type 2: Consecutive user messages
+            if (current.type === 'user' && previous.type === 'user') {
+                interruptions.push(current);
+                interruptionIds.add(current.id);
+                continue;
+            }
+            // Type 3: User message with interruption keywords
+            if (current.type === 'user') {
+                const content = this.extractTextContent(current).toLowerCase();
+                const hasInterruptionKeyword = content.includes('wait') ||
+                    content.includes('stop') ||
+                    content.includes('actually') ||
+                    content.startsWith('no, ') ||
+                    content.includes('cancel');
+                if (hasInterruptionKeyword) {
+                    interruptions.push(current);
+                    interruptionIds.add(current.id);
+                }
+            }
+        }
+        return interruptions;
+    }
+    /**
+     * Extract text content from message (handles both string and structured content)
+     */
+    extractTextContent(message) {
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        // Structured content
+        if (message.content.text) {
+            return message.content.text;
+        }
+        return '';
+    }
+    /**
+     * Generate improvement tips based on metrics
+     */
+    generateImprovementTips(interruptionRate, sessionLength) {
+        const tips = [];
+        if (interruptionRate > 50) {
+            tips.push('High interruption rate - consider providing more context upfront');
+            tips.push('Note: Some interruptions are effective when steering AI back on track');
+        }
+        if (sessionLength > 60) {
+            tips.push("Long session - ensure you're making steady progress on your task");
+            tips.push('Consider whether initial requirements were comprehensive enough');
+        }
+        if (interruptionRate < 10 && sessionLength < 30) {
+            tips.push('Excellent collaboration! Efficient session with minimal course corrections');
+        }
+        return tips;
+    }
+}
+//# sourceMappingURL=engagement.js.map

package/dist/esm/processors/canonical/metrics/engagement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engagement.js","sourceRoot":"","sources":["../../../../../src/processors/canonical/metrics/engagement.ts"],"names":[],"mappings":"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"}

package/dist/esm/processors/canonical/metrics/error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified Error Metrics Processor
+ *
+ * Works for all providers using the canonical format.
+ * Tracks errors, failures, and recovery patterns.
+ */
+import type { ErrorMetrics } from '@guidemode/types';
+import type { ParsedSession } from '../../../parsers/base/types.js';
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export declare class CanonicalErrorProcessor extends BaseMetricProcessor {
+    readonly name = "canonical-error";
+    readonly metricType: "error";
+    readonly description = "Tracks errors, failures, and recovery patterns (unified for all providers)";
+    process(session: ParsedSession): Promise<ErrorMetrics>;
+    /**
+     * Extract tool results from session
+     */
+    private extractToolResults;
+    /**
+     * Extract errors from tool results
+     */
+    private extractErrors;
+    /**
+     * Check if content has error indicators
+     */
+    private hasErrorIndicators;
+    /**
+     * Determine error severity
+     */
+    private determineSeverity;
+    /**
+     * Categorize errors by type
+     */
+    private categorizeErrors;
+    /**
+     * Count recovery attempts (retries after errors)
+     */
+    private countRecoveryAttempts;
+    /**
+     * Extract text content from message
+     */
+    private extractTextContent;
+    /**
+     * Generate improvement tips
+     */
+    private generateImprovementTips;
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/esm/processors/canonical/metrics/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../../src/processors/canonical/metrics/error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,kBAAkB,CAAA;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEpE,qBAAa,uBAAwB,SAAQ,mBAAmB;IAC9D,QAAQ,CAAC,IAAI,qBAAoB;IACjC,QAAQ,CAAC,UAAU,EAAG,OAAO,CAAS;IACtC,QAAQ,CAAC,WAAW,gFAC0D;IAExE,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IA+B5D;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,aAAa;IA6BrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsCxB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAahC"}

package/dist/esm/processors/canonical/metrics/error.js

@@ -0,0 +1,199 @@
+/**
+ * Unified Error Metrics Processor
+ *
+ * Works for all providers using the canonical format.
+ * Tracks errors, failures, and recovery patterns.
+ */
+import { isStructuredMessageContent } from '@guidemode/types';
+import { BaseMetricProcessor } from '../../base/metric-processor.js';
+export class CanonicalErrorProcessor extends BaseMetricProcessor {
+    name = 'canonical-error';
+    metricType = 'error';
+    description = 'Tracks errors, failures, and recovery patterns (unified for all providers)';
+    async process(session) {
+        const toolResults = this.extractToolResults(session);
+        if (toolResults.length === 0) {
+            return {
+                error_count: 0,
+                error_types: [],
+                last_error_message: '',
+                recovery_attempts: 0,
+                fatal_errors: 0,
+            };
+        }
+        // Extract errors from tool results
+        const errors = this.extractErrors(toolResults);
+        const errorTypes = this.categorizeErrors(errors);
+        const recoveryAttempts = this.countRecoveryAttempts(session);
+        const fatalErrors = errors.filter(e => e.severity === 'fatal').length;
+        return {
+            error_count: errors.length,
+            error_types: Array.from(new Set(errorTypes)),
+            last_error_message: '', // Kept for backwards compatibility, not displayed
+            recovery_attempts: recoveryAttempts,
+            fatal_errors: fatalErrors,
+            metadata: {
+                improvement_tips: this.generateImprovementTips(errors.length, fatalErrors),
+            },
+        };
+    }
+    /**
+     * Extract tool results from session
+     */
+    extractToolResults(session) {
+        const toolResults = [];
+        for (const message of session.messages) {
+            if (isStructuredMessageContent(message.content) && message.content.toolResult) {
+                toolResults.push(message.content.toolResult);
+            }
+        }
+        return toolResults;
+    }
+    /**
+     * Extract errors from tool results
+     */
+    extractErrors(toolResults) {
+        const errors = [];
+        for (const result of toolResults) {
+            // Check explicit error flag
+            if (result.is_error) {
+                const message = typeof result.content === 'string' ? result.content : JSON.stringify(result.content);
+                const severity = this.determineSeverity(message);
+                errors.push({ message, severity });
+                continue;
+            }
+            // Check content for error indicators
+            const content = typeof result.content === 'string' ? result.content : JSON.stringify(result.content);
+            const contentLower = content.toLowerCase();
+            if (this.hasErrorIndicators(contentLower)) {
+                const severity = this.determineSeverity(contentLower);
+                errors.push({ message: content.substring(0, 200), severity });
+            }
+        }
+        return errors;
+    }
+    /**
+     * Check if content has error indicators
+     */
+    hasErrorIndicators(content) {
+        const errorKeywords = [
+            'error:',
+            'exception',
+            'failed',
+            'failure',
+            'permission denied',
+            'access denied',
+            'not found',
+            'does not exist',
+            'invalid',
+            'cannot',
+            'unable to',
+            'could not',
+        ];
+        return errorKeywords.some(keyword => content.includes(keyword));
+    }
+    /**
+     * Determine error severity
+     */
+    determineSeverity(message) {
+        const messageLower = message.toLowerCase();
+        const fatalKeywords = [
+            'fatal error',
+            'critical error',
+            'cannot continue',
+            'system failure',
+            'unrecoverable',
+        ];
+        const warningKeywords = ['warning:', 'deprecated', 'caution', 'notice'];
+        if (fatalKeywords.some(keyword => messageLower.includes(keyword))) {
+            return 'fatal';
+        }
+        if (warningKeywords.some(keyword => messageLower.includes(keyword))) {
+            return 'warning';
+        }
+        return 'error';
+    }
+    /**
+     * Categorize errors by type
+     */
+    categorizeErrors(errors) {
+        const categories = new Set();
+        for (const error of errors) {
+            const message = error.message.toLowerCase();
+            // File system errors
+            if (message.includes('not found') || message.includes('does not exist')) {
+                categories.add('file_not_found');
+            }
+            else if (message.includes('permission denied') || message.includes('access denied')) {
+                categories.add('permission_error');
+            }
+            else if (message.includes('file') &&
+                (message.includes('error') || message.includes('failed'))) {
+                categories.add('file_operation_error');
+            }
+            // Code/syntax errors
+            else if (message.includes('syntax error') || message.includes('parse error')) {
+                categories.add('syntax_error');
+            }
+            else if (message.includes('type error') || message.includes('undefined')) {
+                categories.add('type_error');
+            }
+            // Runtime errors
+            else if (message.includes('timeout') || message.includes('timed out')) {
+                categories.add('timeout_error');
+            }
+            else if (message.includes('connection') && message.includes('failed')) {
+                categories.add('connection_error');
+            }
+            // Generic
+            else {
+                categories.add('general_error');
+            }
+        }
+        return Array.from(categories);
+    }
+    /**
+     * Count recovery attempts (retries after errors)
+     */
+    countRecoveryAttempts(session) {
+        let recoveryAttempts = 0;
+        for (let i = 0; i < session.messages.length - 1; i++) {
+            const current = session.messages[i];
+            const next = session.messages[i + 1];
+            // If assistant message has error in tool result, and next is user or assistant retry
+            if (current.type === 'assistant' && (next.type === 'user' || next.type === 'assistant')) {
+                const content = this.extractTextContent(current).toLowerCase();
+                if (this.hasErrorIndicators(content)) {
+                    recoveryAttempts++;
+                }
+            }
+        }
+        return recoveryAttempts;
+    }
+    /**
+     * Extract text content from message
+     */
+    extractTextContent(message) {
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        if (message.content.text) {
+            return message.content.text;
+        }
+        return '';
+    }
+    /**
+     * Generate improvement tips
+     */
+    generateImprovementTips(errorCount, fatalErrors) {
+        const tips = [];
+        if (errorCount > 5) {
+            tips.push('High error rate - consider providing more context or breaking down the task');
+        }
+        if (fatalErrors > 0) {
+            tips.push('Fatal errors detected - review error messages and address root causes');
+        }
+        return tips;
+    }
+}
+//# sourceMappingURL=error.js.map