salmon-loop 0.2.3

package/dist/core/context/summarization/index.js

@@ -0,0 +1,27 @@
+/**
+ * Conversation summarization module.
+ *
+ * Provides incremental summarization with async execution for
+ * efficient long-context management.
+ *
+ * @example
+ * ```typescript
+ * import { ConversationSummarizer } from './summarization/index.js';
+ *
+ * const summarizer = new ConversationSummarizer(llmClient, tokenCounter, {
+ *   summaryModel: { model: 'claude-3-5-haiku' }
+ * });
+ *
+ * // Check and trigger summarization
+ * if (summarizer.shouldTrigger(messages)) {
+ *   await summarizer.triggerSummarization(messages);
+ * }
+ *
+ * // Get effective context
+ * const context = summarizer.getEffectiveContext(messages);
+ * ```
+ */
+export { ConversationSummarizer } from './summarizer.js';
+export { buildIncrementalSummaryPrompt, truncateSummary } from './prompts.js';
+export { DEFAULT_SUMMARIZATION_CONFIG } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/core/context/summarization/prompts.js

@@ -0,0 +1,80 @@
+/**
+ * Incremental summary prompts.
+ *
+ * Following LangChain's progressive summarization pattern:
+ * - New messages are added to existing summary
+ * - No need to regenerate entire summary
+ */
+/**
+ * Build prompt for incremental summary.
+ *
+ * Following LangChain's ConversationSummaryMemory pattern.
+ */
+export function buildIncrementalSummaryPrompt(input) {
+    const { currentSummary, newMessages } = input;
+    const formattedMessages = newMessages
+        .map((m) => `${m.role.toUpperCase()}: ${m.content}`)
+        .join('\n\n');
+    const outputContract = `Output format (strict):
+1) Human summary:
+[SUMMARY]
+<concise summary text>
+[/SUMMARY]
+2) Structured state JSON:
+[STATE_JSON]
+{
+  "decisions": [],
+  "constraints": [],
+  "open_questions": [],
+  "pending_tasks": [],
+  "rejected_options": [],
+  "assumptions": [],
+  "risks": [],
+  "owner": []
+}
+[/STATE_JSON]`;
+    if (currentSummary) {
+        return `Current summary:
+${currentSummary}
+
+New lines of conversation:
+${formattedMessages}
+
+Updated summary (integrate new information into current summary, keep it concise and focused on key decisions, code changes, and important context).
+${outputContract}`;
+    }
+    return `Summarize this conversation, capturing:
+- Key decisions and agreements
+- Important code or technical details discussed
+- User preferences and constraints mentioned
+- Pending tasks or open questions
+
+Conversation:
+${formattedMessages}
+
+${outputContract}`;
+}
+/**
+ * Format messages for token counting.
+ */
+export function formatMessagesForCounting(messages) {
+    return messages.map((m) => `${m.role}: ${m.content}`).join('\n');
+}
+/**
+ * Truncate summary if it exceeds max tokens.
+ * Uses a simple character-based estimate for speed.
+ */
+export function truncateSummary(summary, maxTokens, countTokens) {
+    const tokens = countTokens(summary);
+    if (tokens <= maxTokens)
+        return summary;
+    // Estimate character ratio
+    const ratio = maxTokens / tokens;
+    const targetChars = Math.floor(summary.length * ratio * 0.9); // 10% safety margin
+    // Find a good break point
+    const truncated = summary.slice(0, targetChars);
+    const lastSentenceEnd = Math.max(truncated.lastIndexOf('.'), truncated.lastIndexOf('!'), truncated.lastIndexOf('?'));
+    const breakPoint = lastSentenceEnd > targetChars * 0.7 ? lastSentenceEnd + 1 : targetChars;
+    return summary.slice(0, breakPoint) + '\n\n[Summary truncated for length]';
+}
+//# sourceMappingURL=prompts.js.map

package/dist/core/context/summarization/summarizer.js

@@ -0,0 +1,377 @@
+/**
+ * ConversationSummarizer - Incremental + Async summarization.
+ *
+ * Features:
+ * - Incremental summarization (progressive)
+ * - Async execution (non-blocking)
+ * - Pre-trigger at 90% threshold
+ * - Graceful failure handling
+ *
+ * Based on best practices from LangChain, OpenAI Realtime API, and Voice AI systems.
+ */
+import { getLogger } from '../../observability/logger.js';
+import { buildIncrementalSummaryPrompt, truncateSummary } from './prompts.js';
+import { DEFAULT_SUMMARIZATION_CONFIG } from './types.js';
+/**
+ * ConversationSummarizer manages incremental summarization of chat history.
+ *
+ * @example
+ * ```typescript
+ * const summarizer = new ConversationSummarizer(llmClient, tokenCounter, {
+ *   summaryModel: { model: 'claude-3-5-haiku', temperature: 0 }
+ * });
+ *
+ * // On each new message
+ * if (summarizer.shouldTrigger(messages)) {
+ *   await summarizer.triggerSummarization(messages);
+ * }
+ *
+ * // Get context for LLM
+ * const context = summarizer.getEffectiveContext(messages);
+ * ```
+ */
+export class ConversationSummarizer {
+    llm;
+    tokenCounter;
+    config;
+    state;
+    summaryInProgress = false;
+    initialized = false;
+    constructor(llm, tokenCounter, config = DEFAULT_SUMMARIZATION_CONFIG) {
+        this.llm = llm;
+        this.tokenCounter = tokenCounter;
+        this.config = config;
+        this.state = {
+            summary: '',
+            summaryTokens: 0,
+            summarizedMessageIds: [],
+            lastSummarizedAt: 0,
+            summaryVersion: 2,
+            structuredState: this.createEmptyStructuredState(),
+            contextHash: undefined,
+        };
+    }
+    // ==================== Lifecycle ====================
+    /**
+     * Initialize the summarizer.
+     */
+    async initialize() {
+        this.initialized = true;
+        getLogger().debug('[Summarizer] Initialized');
+    }
+    /**
+     * Dispose resources.
+     */
+    dispose() {
+        this.reset();
+        this.initialized = false;
+    }
+    // ==================== State Management ====================
+    /**
+     * Get current state for persistence.
+     */
+    getState() {
+        return {
+            summary: this.state.summary,
+            summaryTokens: this.state.summaryTokens,
+            summarizedMessageIds: [...this.state.summarizedMessageIds],
+            lastSummarizedAt: this.state.lastSummarizedAt,
+            summaryVersion: this.state.summaryVersion,
+            structuredState: this.state.structuredState
+                ? { ...this.state.structuredState }
+                : this.createEmptyStructuredState(),
+            contextHash: this.state.contextHash,
+        };
+    }
+    /**
+     * Restore state from persistence.
+     */
+    restoreState(state) {
+        this.state = {
+            summary: state.summary,
+            summaryTokens: state.summaryTokens,
+            summarizedMessageIds: [...state.summarizedMessageIds],
+            lastSummarizedAt: state.lastSummarizedAt,
+            summaryVersion: state.summaryVersion ?? 2,
+            structuredState: state.structuredState
+                ? this.normalizeStructuredState(state.structuredState)
+                : this.createEmptyStructuredState(),
+            contextHash: state.contextHash,
+        };
+        getLogger().debug(`[Summarizer] Restored state with ${state.summarizedMessageIds.length} summarized messages`);
+    }
+    /**
+     * Reset summarizer state.
+     */
+    reset() {
+        this.state = {
+            summary: '',
+            summaryTokens: 0,
+            summarizedMessageIds: [],
+            lastSummarizedAt: 0,
+            summaryVersion: 2,
+            structuredState: this.createEmptyStructuredState(),
+            contextHash: undefined,
+        };
+        this.summaryInProgress = false;
+    }
+    // ==================== Context Generation ====================
+    /**
+     * Get effective context for LLM call.
+     * Returns: summary message + recent original messages.
+     */
+    getEffectiveContext(messages) {
+        const result = [];
+        // 1. Add structured state if exists
+        if (this.state.structuredState && this.hasStructuredStateContent(this.state.structuredState)) {
+            result.push({
+                id: 'summary-state',
+                role: 'system',
+                content: `[Conversation structured state v${this.state.summaryVersion ?? 2}]` +
+                    `\ncontextHash=${this.state.contextHash ?? 'none'}\n` +
+                    JSON.stringify(this.state.structuredState),
+                timestamp: this.state.lastSummarizedAt,
+            });
+        }
+        // 2. Add human-readable summary if exists
+        if (this.state.summary) {
+            result.push({
+                id: 'summary',
+                role: 'system',
+                content: `[Previous conversation summary]\n${this.state.summary}`,
+                timestamp: this.state.lastSummarizedAt,
+            });
+        }
+        // 3. Add recent messages not yet summarized
+        const summarizedSet = new Set(this.state.summarizedMessageIds);
+        const recentMessages = messages
+            .filter((m) => !summarizedSet.has(m.id))
+            .slice(-this.config.keepRecentMessages);
+        result.push(...recentMessages);
+        return result;
+    }
+    // ==================== Token Calculation ====================
+    /**
+     * Calculate total tokens for messages.
+     */
+    calculateTokens(messages) {
+        let total = this.state.summaryTokens;
+        const summarizedSet = new Set(this.state.summarizedMessageIds);
+        for (const msg of messages) {
+            if (!summarizedSet.has(msg.id)) {
+                total += this.tokenCounter.count(this.formatMessage(msg));
+            }
+        }
+        return total;
+    }
+    // ==================== Trigger Logic ====================
+    /**
+     * Check if summarization should be triggered.
+     */
+    shouldTrigger(messages) {
+        if (this.summaryInProgress)
+            return false;
+        const tokens = this.calculateTokens(messages);
+        const threshold = this.config.triggerTokens * this.config.preTriggerRatio;
+        return tokens >= threshold && messages.length > this.config.keepRecentMessages;
+    }
+    /**
+     * Get current token usage ratio (0-1).
+     */
+    getUsageRatio(messages) {
+        const tokens = this.calculateTokens(messages);
+        return tokens / this.config.triggerTokens;
+    }
+    // ==================== Summarization Execution ====================
+    /**
+     * Trigger summarization.
+     * If async mode, returns null immediately and runs in background.
+     */
+    async triggerSummarization(messages, contextHash) {
+        if (this.summaryInProgress) {
+            getLogger().debug('[Summarizer] Summary already in progress, skipping');
+            return null;
+        }
+        this.ensureStateAligned(contextHash);
+        if (!this.shouldTrigger(messages)) {
+            return null;
+        }
+        if (this.config.async) {
+            // Fire and forget
+            this.runSummarization(messages, contextHash).catch((err) => {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                getLogger().warn(`[Summarizer] Async summarization failed: ${errMsg}`);
+            });
+            return null;
+        }
+        return this.runSummarization(messages, contextHash);
+    }
+    /**
+     * Force summarization now (for session end or explicit request).
+     */
+    async forceSummarize(messages, contextHash) {
+        this.ensureStateAligned(contextHash);
+        if (messages.length <= this.config.keepRecentMessages) {
+            return null;
+        }
+        return this.runSummarization(messages, contextHash);
+    }
+    /**
+     * Run incremental summarization.
+     */
+    async runSummarization(messages, contextHash) {
+        this.summaryInProgress = true;
+        try {
+            this.ensureStateAligned(contextHash);
+            // 1. Get messages to summarize (exclude recent N)
+            const summarizedSet = new Set(this.state.summarizedMessageIds);
+            const toSummarize = messages
+                .filter((m) => !summarizedSet.has(m.id))
+                .slice(0, -this.config.keepRecentMessages);
+            if (toSummarize.length === 0) {
+                return {
+                    summary: this.state.summary,
+                    messagesSummarized: 0,
+                    tokensBefore: 0,
+                    tokensAfter: this.state.summaryTokens,
+                    tokenReduction: 0,
+                    async: this.config.async,
+                };
+            }
+            // 2. Batch if too many
+            const batch = toSummarize.slice(0, this.config.maxBatchSize);
+            const beforeTokens = batch.reduce((sum, m) => sum + this.tokenCounter.count(this.formatMessage(m)), 0);
+            // 3. Build prompt and call LLM
+            const prompt = buildIncrementalSummaryPrompt({
+                currentSummary: this.composeCurrentSummaryForPrompt(),
+                newMessages: batch,
+            });
+            const response = await this.llm.chat({
+                model: this.config.summaryModel.model,
+                messages: [{ role: 'user', content: prompt }],
+                temperature: this.config.summaryModel.temperature ?? 0,
+                maxTokens: this.config.maxSummaryTokens,
+            });
+            const parsed = this.parseSummaryResponse(response.content);
+            let newSummary = parsed.summary;
+            const afterTokens = this.tokenCounter.count(newSummary);
+            // 4. Truncate if needed
+            if (afterTokens > this.config.maxSummaryTokens) {
+                newSummary = truncateSummary(newSummary, this.config.maxSummaryTokens, (text) => this.tokenCounter.count(text));
+            }
+            // 5. Update state
+            this.state.summary = newSummary;
+            this.state.summaryTokens = this.tokenCounter.count(newSummary);
+            this.state.structuredState = parsed.structuredState;
+            this.state.contextHash = contextHash;
+            this.state.summaryVersion = 2;
+            for (const msg of batch) {
+                this.state.summarizedMessageIds.push(msg.id);
+            }
+            this.state.lastSummarizedAt = Date.now();
+            getLogger().info(`[Summarizer] Summarized ${batch.length} messages, ` +
+                `reduced ${beforeTokens} → ${this.state.summaryTokens} tokens`);
+            return {
+                summary: newSummary,
+                messagesSummarized: batch.length,
+                tokensBefore: beforeTokens,
+                tokensAfter: this.state.summaryTokens,
+                tokenReduction: beforeTokens - this.state.summaryTokens,
+                async: this.config.async,
+            };
+        }
+        catch (error) {
+            getLogger().error('[Summarizer] Summarization failed', error);
+            throw error;
+        }
+        finally {
+            this.summaryInProgress = false;
+        }
+    }
+    // ==================== Private Helpers ====================
+    formatMessage(msg) {
+        return `${msg.role}: ${msg.content}`;
+    }
+    composeCurrentSummaryForPrompt() {
+        if (!this.state.summary && !this.state.structuredState) {
+            return '';
+        }
+        const structured = this.state.structuredState
+            ? `\n\nCurrent structured state:\n${JSON.stringify(this.state.structuredState)}`
+            : '';
+        return `${this.state.summary}${structured}`;
+    }
+    ensureStateAligned(contextHash) {
+        if (!contextHash)
+            return;
+        if (!this.state.contextHash || this.state.contextHash === contextHash)
+            return;
+        getLogger().warn(`[Summarizer] Context hash changed (${this.state.contextHash} -> ${contextHash}), rebuilding summary state`);
+        this.state.summary = '';
+        this.state.summaryTokens = 0;
+        this.state.summarizedMessageIds = [];
+        this.state.structuredState = this.createEmptyStructuredState();
+        this.state.contextHash = undefined;
+        this.state.lastSummarizedAt = 0;
+    }
+    parseSummaryResponse(content) {
+        const summaryMatch = content.match(/\[SUMMARY\]([\s\S]*?)\[\/SUMMARY\]/);
+        const summary = (summaryMatch?.[1] ?? content).trim();
+        const stateMatch = content.match(/\[STATE_JSON\]([\s\S]*?)\[\/STATE_JSON\]/);
+        if (!stateMatch?.[1]) {
+            return { summary, structuredState: this.createEmptyStructuredState() };
+        }
+        try {
+            const parsed = JSON.parse(stateMatch[1]);
+            return { summary, structuredState: this.normalizeStructuredState(parsed) };
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            getLogger().warn(`[Summarizer] Failed to parse structured summary state: ${errMsg}`);
+            return { summary, structuredState: this.createEmptyStructuredState() };
+        }
+    }
+    normalizeStructuredState(input) {
+        const normalized = this.createEmptyStructuredState();
+        if (!input || typeof input !== 'object')
+            return normalized;
+        const source = input;
+        normalized.decisions = this.ensureStringArray(source.decisions);
+        normalized.constraints = this.ensureStringArray(source.constraints);
+        normalized.open_questions = this.ensureStringArray(source.open_questions);
+        normalized.pending_tasks = this.ensureStringArray(source.pending_tasks);
+        normalized.rejected_options = this.ensureStringArray(source.rejected_options);
+        normalized.assumptions = this.ensureStringArray(source.assumptions);
+        normalized.risks = this.ensureStringArray(source.risks);
+        normalized.owner = this.ensureStringArray(source.owner);
+        return normalized;
+    }
+    ensureStringArray(value) {
+        if (!Array.isArray(value))
+            return [];
+        return value.filter((item) => typeof item === 'string');
+    }
+    createEmptyStructuredState() {
+        return {
+            decisions: [],
+            constraints: [],
+            open_questions: [],
+            pending_tasks: [],
+            rejected_options: [],
+            assumptions: [],
+            risks: [],
+            owner: [],
+        };
+    }
+    hasStructuredStateContent(state) {
+        return (state.decisions.length > 0 ||
+            state.constraints.length > 0 ||
+            state.open_questions.length > 0 ||
+            state.pending_tasks.length > 0 ||
+            state.rejected_options.length > 0 ||
+            state.assumptions.length > 0 ||
+            state.risks.length > 0 ||
+            state.owner.length > 0);
+    }
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/core/context/summarization/types.js

@@ -0,0 +1,29 @@
+/**
+ * Summarization types and interfaces.
+ *
+ * Design Principles:
+ * - Incremental summarization (progressive)
+ * - Async execution (non-blocking)
+ * - Model-agnostic configuration
+ */
+/**
+ * Default configuration based on research best practices.
+ * - 3500 token threshold (leaving room for system prompt)
+ * - 90% pre-trigger for smooth UX
+ * - 10 recent messages (5 rounds)
+ * - Async execution by default
+ */
+export const DEFAULT_SUMMARIZATION_CONFIG = {
+    triggerTokens: 3500,
+    preTriggerRatio: 0.9,
+    keepRecentMessages: 10,
+    summaryModel: {
+        model: '', // Set by caller, not hardcoded
+        temperature: 0,
+        maxTokens: 500,
+    },
+    async: true,
+    maxBatchSize: 8,
+    maxSummaryTokens: 500,
+};
+//# sourceMappingURL=types.js.map

package/dist/core/context/targeting/churn-policy.js

@@ -0,0 +1,27 @@
+export const DEFAULT_CHURN_RANKING_POLICY = {
+    primaryBoost: 10000,
+    rerankWeight: 0.35,
+    tieBreakWeight: 0.05,
+};
+let globalChurnRankingPolicy = { ...DEFAULT_CHURN_RANKING_POLICY };
+export function getChurnRankingPolicy() {
+    return { ...globalChurnRankingPolicy };
+}
+export function setChurnRankingPolicy(policy) {
+    if (!policy) {
+        globalChurnRankingPolicy = { ...DEFAULT_CHURN_RANKING_POLICY };
+        return;
+    }
+    globalChurnRankingPolicy = {
+        primaryBoost: typeof policy.primaryBoost === 'number'
+            ? policy.primaryBoost
+            : DEFAULT_CHURN_RANKING_POLICY.primaryBoost,
+        rerankWeight: typeof policy.rerankWeight === 'number'
+            ? policy.rerankWeight
+            : DEFAULT_CHURN_RANKING_POLICY.rerankWeight,
+        tieBreakWeight: typeof policy.tieBreakWeight === 'number'
+            ? policy.tieBreakWeight
+            : DEFAULT_CHURN_RANKING_POLICY.tieBreakWeight,
+    };
+}
+//# sourceMappingURL=churn-policy.js.map