salmon-loop 0.2.3

package/dist/core/context/cache/prompt-caching.js

@@ -0,0 +1,207 @@
+/**
+ * Prompt Caching support for different providers.
+ *
+ * Provides unified interface for Claude, OpenAI, and Gemini caching.
+ */
+import { DEFAULT_PROMPT_CACHING_CONFIG } from './types.js';
+/**
+ * Prompt Caching manager.
+ *
+ * Abstracts provider-specific caching mechanisms:
+ * - **Claude**: Uses `cache_control` parameter on content blocks
+ * - **OpenAI**: Uses `user` parameter for cache hints
+ * - **Gemini**: Uses `cachedContent` configuration
+ */
+export class PromptCachingManager {
+    config;
+    stats;
+    cacheHits = 0;
+    cacheMisses = 0;
+    constructor(config = DEFAULT_PROMPT_CACHING_CONFIG) {
+        this.config = config;
+        this.stats = {
+            cachedTokens: 0,
+            totalTokens: 0,
+            cacheHitRate: 0,
+            provider: config.provider,
+        };
+    }
+    /**
+     * Set provider.
+     */
+    setProvider(provider) {
+        this.config.provider = provider;
+        this.stats.provider = provider;
+    }
+    /**
+     * Get current provider.
+     */
+    getProvider() {
+        return this.config.provider;
+    }
+    /**
+     * Mark content block as cacheable (Claude).
+     *
+     * @param content - Content text
+     * @param ttl - Optional TTL in seconds
+     * @returns Cacheable block for Claude API
+     */
+    markCacheableForClaude(content, ttl) {
+        const cacheControl = {
+            type: 'ephemeral',
+            ...(ttl && { ttl }),
+        };
+        return {
+            type: 'text',
+            text: content,
+            cache_control: cacheControl,
+        };
+    }
+    /**
+     * Generate cache hint for OpenAI (via user parameter).
+     *
+     * @param namespace - Cache namespace
+     * @param components - Cache key components
+     * @returns Cache hint string for user parameter
+     */
+    generateOpenAICacheHint(namespace, components) {
+        const hint = {
+            namespace,
+            components,
+        };
+        return `cache:${JSON.stringify(hint)}`;
+    }
+    /**
+     * Generate Gemini cache configuration.
+     *
+     * @param cacheName - Cache identifier
+     * @param ttlSeconds - TTL in seconds
+     * @returns Gemini cache configuration
+     */
+    generateGeminiCacheConfig(cacheName, ttlSeconds) {
+        return {
+            cachedContent: cacheName,
+            ...(ttlSeconds && { ttlSeconds }),
+        };
+    }
+    /**
+     * Check if caching should be enabled for given token count.
+     */
+    shouldCache(tokenCount) {
+        if (!this.config.enabled)
+            return false;
+        return tokenCount >= this.config.minTokensToCache;
+    }
+    /**
+     * Record cache hit.
+     */
+    recordHit(cachedTokens) {
+        this.cacheHits++;
+        this.stats.cachedTokens += cachedTokens;
+        this.updateHitRate();
+    }
+    /**
+     * Record cache miss.
+     */
+    recordMiss() {
+        this.cacheMisses++;
+        this.updateHitRate();
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset statistics.
+     */
+    resetStats() {
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        this.stats = {
+            cachedTokens: 0,
+            totalTokens: 0,
+            cacheHitRate: 0,
+            provider: this.config.provider,
+        };
+    }
+    /**
+     * Prepare messages with caching for Claude.
+     *
+     * @param systemPrompt - System prompt
+     * @param context - Context content
+     * @returns Messages with cache control
+     */
+    prepareClaudeMessages(systemPrompt, context) {
+        const blocks = [];
+        // System prompt is usually static, mark as cacheable
+        if (systemPrompt && this.shouldCache(this.estimateTokens(systemPrompt))) {
+            blocks.push(this.markCacheableForClaude(systemPrompt, this.config.defaultTTL));
+        }
+        else if (systemPrompt) {
+            blocks.push({ type: 'text', text: systemPrompt });
+        }
+        // Context content can be cached
+        const contextBlocks = [];
+        if (context && this.shouldCache(this.estimateTokens(context))) {
+            contextBlocks.push(this.markCacheableForClaude(context, this.config.defaultTTL));
+        }
+        else if (context) {
+            contextBlocks.push({ type: 'text', text: context });
+        }
+        return { system: blocks, messages: contextBlocks };
+    }
+    /**
+     * Prepare request with caching for OpenAI.
+     *
+     * @param namespace - Cache namespace
+     * @param contextHash - Context hash for cache key
+     * @returns User parameter for cache hint
+     */
+    prepareOpenAIRequest(namespace, contextHash) {
+        return this.generateOpenAICacheHint(namespace, [contextHash]);
+    }
+    /**
+     * Prepare request with caching for Gemini.
+     *
+     * @param cacheName - Cache resource name
+     * @returns Gemini cache configuration
+     */
+    prepareGeminiRequest(cacheName) {
+        return this.generateGeminiCacheConfig(cacheName, this.config.defaultTTL);
+    }
+    /**
+     * Update hit rate.
+     */
+    updateHitRate() {
+        const total = this.cacheHits + this.cacheMisses;
+        this.stats.cacheHitRate = total === 0 ? 0 : this.cacheHits / total;
+    }
+    /**
+     * Estimate token count (rough estimate).
+     */
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+}
+/**
+ * Global prompt caching manager instance.
+ */
+let globalInstance = null;
+/**
+ * Get global prompt caching manager.
+ */
+export function getPromptCachingManager() {
+    if (!globalInstance) {
+        globalInstance = new PromptCachingManager();
+    }
+    return globalInstance;
+}
+/**
+ * Reset global instance (for testing).
+ */
+export function resetPromptCachingManager() {
+    globalInstance = null;
+}
+//# sourceMappingURL=prompt-caching.js.map

package/dist/core/context/cache/store-factory.js

@@ -0,0 +1,63 @@
+import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { recordAuditEvent } from '../../observability/audit-trail.js';
+import { resolveContextCachePath } from './path-resolver.js';
+import { MemoryContextCacheStore, PersistentContextCacheStore, } from './store.js';
+export async function createContextCacheStore(repoPath, rawConfig, options) {
+    const cacheConfig = rawConfig?.context?.cache;
+    const pathResolution = await resolveContextCachePath(repoPath, rawConfig, options);
+    const maxEntries = typeof cacheConfig?.maxEntries === 'number' && cacheConfig.maxEntries > 0
+        ? Math.floor(cacheConfig.maxEntries)
+        : undefined;
+    const ttlMs = typeof cacheConfig?.ttlMs === 'number' && cacheConfig.ttlMs > 0
+        ? Math.floor(cacheConfig.ttlMs)
+        : undefined;
+    const maxPayloadBytes = typeof cacheConfig?.maxPayloadBytes === 'number' && cacheConfig.maxPayloadBytes > 0
+        ? Math.floor(cacheConfig.maxPayloadBytes)
+        : undefined;
+    const fallbackToMemoryOnFailure = Boolean(cacheConfig?.fallbackToMemoryOnFailure);
+    const cacheStrict = fallbackToMemoryOnFailure ? false : (cacheConfig?.strict ?? true);
+    const fallbackMode = fallbackToMemoryOnFailure
+        ? 'memory'
+        : 'fail';
+    const cleanupAdapter = new FileAdapter();
+    const cleanupFn = async (details) => {
+        try {
+            await cleanupAdapter.deleteFile(details.filePath);
+        }
+        catch {
+            // best-effort cleanup only
+        }
+    };
+    if (pathResolution.mode === 'persistent' && pathResolution.filePath) {
+        const storeOptions = {
+            strict: cacheStrict,
+            fallbackMode,
+            cleanupFn,
+            maxPayloadBytes,
+        };
+        const persistentStore = new PersistentContextCacheStore(pathResolution.filePath, storeOptions);
+        if (fallbackToMemoryOnFailure) {
+            try {
+                await persistentStore.size();
+            }
+            catch (error) {
+                recordAuditEvent('context.cache.fallback_to_memory', {
+                    filePath: pathResolution.filePath,
+                    error: error instanceof Error ? error.message : String(error ?? 'unknown'),
+                }, { source: 'context.cache', severity: 'medium', scope: 'repo', phase: 'CONTEXT' });
+                return {
+                    store: new MemoryContextCacheStore(),
+                    maxEntries,
+                    ttlMs,
+                };
+            }
+        }
+        return {
+            store: persistentStore,
+            maxEntries,
+            ttlMs,
+        };
+    }
+    return { store: new MemoryContextCacheStore(), maxEntries, ttlMs };
+}
+//# sourceMappingURL=store-factory.js.map

package/dist/core/context/cache/store.js

@@ -0,0 +1,193 @@
+import { Buffer } from 'node:buffer';
+import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { recordAuditEvent } from '../../observability/audit-trail.js';
+import { redactSensitiveValue } from '../../security/redaction.js';
+import { ContextCacheError } from './errors.js';
+export class MemoryContextCacheStore {
+    map = new Map();
+    async get(key) {
+        return this.map.get(key);
+    }
+    async set(key, entry) {
+        this.map.set(key, entry);
+    }
+    async delete(key) {
+        this.map.delete(key);
+    }
+    async entries() {
+        return [...this.map.entries()];
+    }
+    async size() {
+        return this.map.size;
+    }
+    async clear() {
+        this.map.clear();
+    }
+}
+export class PersistentContextCacheStore {
+    filePath;
+    fileAdapter = new FileAdapter();
+    map = new Map();
+    strict;
+    initPromise = null;
+    cleanupFn;
+    fallbackMode;
+    maxPayloadBytes;
+    degradedToMemory = false;
+    constructor(filePath, options) {
+        this.filePath = filePath;
+        this.strict = options?.strict ?? false;
+        this.cleanupFn = options?.cleanupFn;
+        this.fallbackMode = options?.fallbackMode ?? 'fail';
+        this.maxPayloadBytes = options?.maxPayloadBytes;
+    }
+    async ensureLoaded() {
+        if (!this.initPromise) {
+            this.initPromise = this.loadFromDisk();
+        }
+        await this.initPromise;
+    }
+    async loadFromDisk() {
+        try {
+            const raw = await this.fileAdapter.readFile(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed?.version !== 1 || !parsed.entries || typeof parsed.entries !== 'object')
+                return;
+            for (const [key, value] of Object.entries(parsed.entries)) {
+                if (!value || typeof value !== 'object')
+                    continue;
+                this.map.set(key, value);
+            }
+        }
+        catch (error) {
+            if (this.isNotFoundError(error))
+                return;
+            await this.handleLoadFailure(error);
+        }
+    }
+    async handleLoadFailure(error) {
+        const normalized = this.normalizeError(error);
+        const code = this.isCorruptError(normalized)
+            ? 'CONTEXT_CACHE_CORRUPT'
+            : 'CONTEXT_CACHE_IO';
+        const remediation = this.getRemediationMessage(code);
+        const contextError = new ContextCacheError(code, this.filePath, remediation, `Failed to load context cache: ${normalized.message}`, normalized);
+        this.recordLoadFailureAudit(contextError, normalized);
+        await this.attemptCleanup(normalized);
+        const shouldThrow = this.strict || this.fallbackMode === 'fail';
+        if (shouldThrow) {
+            throw contextError;
+        }
+        if (this.fallbackMode === 'memory') {
+            this.degradedToMemory = true;
+        }
+    }
+    normalizeError(error) {
+        if (error instanceof Error)
+            return error;
+        return new Error(String(error ?? 'Unknown context cache error'));
+    }
+    isCorruptError(error) {
+        const lower = error.message.toLowerCase();
+        return (error instanceof SyntaxError ||
+            lower.includes('unexpected token') ||
+            lower.includes('invalid or unexpected') ||
+            lower.includes('json'));
+    }
+    getRemediationMessage(code) {
+        if (code === 'CONTEXT_CACHE_OVERSIZE') {
+            return `Context cache payload too large for ${this.filePath}. Increase the cache size limit or use memory cache.`;
+        }
+        return `Persistent cache ${this.filePath} may be corrupted or inaccessible (code ${code}). Delete the file or switch to memory cache, then retry.`;
+    }
+    recordLoadFailureAudit(contextError, underlying) {
+        recordAuditEvent('context.cache.load_failure', {
+            code: contextError.code,
+            filePath: this.filePath,
+            fallbackMode: this.fallbackMode,
+            remediation: contextError.remediation,
+            error: underlying.message,
+        }, { source: 'context.cache', severity: 'high', scope: 'repo', phase: 'CONTEXT' });
+    }
+    async attemptCleanup(error) {
+        if (!this.cleanupFn)
+            return;
+        try {
+            await this.cleanupFn({ filePath: this.filePath, error });
+        }
+        catch (cleanupError) {
+            const normalizedCleanup = cleanupError instanceof Error
+                ? cleanupError
+                : new Error(String(cleanupError ?? 'Unknown cleanup error'));
+            this.recordCleanupFailure(normalizedCleanup);
+        }
+    }
+    recordCleanupFailure(error) {
+        recordAuditEvent('context.cache.cleanup_failure', {
+            filePath: this.filePath,
+            error: error.message,
+        }, { source: 'context.cache', severity: 'medium', scope: 'repo', phase: 'CONTEXT' });
+    }
+    isNotFoundError(error) {
+        if (!error || typeof error !== 'object')
+            return false;
+        const maybeCode = 'code' in error ? String(error.code ?? '') : '';
+        if (maybeCode === 'ENOENT')
+            return true;
+        const maybeMessage = 'message' in error ? String(error.message ?? '') : '';
+        return maybeMessage.includes('ENOENT');
+    }
+    async flushToDisk() {
+        if (this.degradedToMemory)
+            return;
+        const payload = {
+            version: 1,
+            entries: Object.fromEntries(this.map.entries()),
+        };
+        const redacted = redactSensitiveValue(payload).value;
+        const serialized = JSON.stringify(redacted);
+        if (this.maxPayloadBytes && Buffer.byteLength(serialized, 'utf-8') > this.maxPayloadBytes) {
+            recordAuditEvent('context.cache.oversize', {
+                filePath: this.filePath,
+                bytes: Buffer.byteLength(serialized, 'utf-8'),
+                maxBytes: this.maxPayloadBytes,
+                fallbackMode: this.fallbackMode,
+            }, { source: 'context.cache', severity: 'high', scope: 'repo', phase: 'CONTEXT' });
+            if (this.fallbackMode === 'memory') {
+                this.degradedToMemory = true;
+                return;
+            }
+            throw new ContextCacheError('CONTEXT_CACHE_OVERSIZE', this.filePath, this.getRemediationMessage('CONTEXT_CACHE_OVERSIZE'), `Context cache payload exceeds max size (${this.maxPayloadBytes} bytes)`);
+        }
+        await this.fileAdapter.writeFileAtomic(this.filePath, Buffer.from(serialized, 'utf-8'));
+    }
+    async get(key) {
+        await this.ensureLoaded();
+        return this.map.get(key);
+    }
+    async set(key, entry) {
+        await this.ensureLoaded();
+        this.map.set(key, entry);
+        await this.flushToDisk();
+    }
+    async delete(key) {
+        await this.ensureLoaded();
+        if (!this.map.delete(key))
+            return;
+        await this.flushToDisk();
+    }
+    async entries() {
+        await this.ensureLoaded();
+        return [...this.map.entries()];
+    }
+    async size() {
+        await this.ensureLoaded();
+        return this.map.size;
+    }
+    async clear() {
+        await this.ensureLoaded();
+        this.map.clear();
+        await this.flushToDisk();
+    }
+}
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Prompt Caching types and interfaces.
+ *
+ * Supports Claude, OpenAI, and Gemini Prompt Caching APIs.
+ */
+/**
+ * Default prompt caching configuration.
+ */
+export const DEFAULT_PROMPT_CACHING_CONFIG = {
+    enabled: true,
+    provider: 'claude',
+    minTokensToCache: 1024, // Only cache if > 1024 tokens
+    defaultTTL: 3600, // 1 hour
+};
+//# sourceMappingURL=types.js.map

package/dist/core/context/compression/js-like-comments.js

@@ -0,0 +1,139 @@
+function isRegexAllowedAfter(ch) {
+    if (!ch)
+        return true;
+    return /[=([{:,!?&|;+\-*/%^~<>]/.test(ch);
+}
+export function stripJsLikeComments(input, options = {}) {
+    const preserveJSDoc = options.preserveJSDoc ?? false;
+    let out = '';
+    let i = 0;
+    let state = 'code';
+    let lastSignificant = null;
+    let regexCharClassDepth = 0;
+    const push = (ch) => {
+        out += ch;
+        if (!/\s/.test(ch))
+            lastSignificant = ch;
+    };
+    while (i < input.length) {
+        const ch = input[i];
+        const next = input[i + 1];
+        if (state === 'code') {
+            if (ch === "'" || ch === '"' || ch === '`') {
+                state = ch === "'" ? 'single' : ch === '"' ? 'double' : 'template';
+                push(ch);
+                i++;
+                continue;
+            }
+            if (ch === '/' && next === '/') {
+                state = 'line_comment';
+                i += 2;
+                continue;
+            }
+            if (ch === '/' && next === '*') {
+                const third = input[i + 2];
+                const isJsdoc = third === '*';
+                if (preserveJSDoc && isJsdoc) {
+                    state = 'jsdoc_comment';
+                    push('/');
+                    push('*');
+                    i += 2;
+                    continue;
+                }
+                state = 'block_comment';
+                i += 2;
+                continue;
+            }
+            if (ch === '/' && next && next !== '/' && next !== '*') {
+                if (isRegexAllowedAfter(lastSignificant)) {
+                    state = 'regex';
+                    regexCharClassDepth = 0;
+                    push(ch);
+                    i++;
+                    continue;
+                }
+            }
+            push(ch);
+            i++;
+            continue;
+        }
+        if (state === 'single' || state === 'double') {
+            push(ch);
+            if (ch === '\\') {
+                if (next) {
+                    push(next);
+                    i += 2;
+                    continue;
+                }
+            }
+            if ((state === 'single' && ch === "'") || (state === 'double' && ch === '"')) {
+                state = 'code';
+            }
+            i++;
+            continue;
+        }
+        if (state === 'template') {
+            push(ch);
+            if (ch === '\\') {
+                if (next) {
+                    push(next);
+                    i += 2;
+                    continue;
+                }
+            }
+            if (ch === '`')
+                state = 'code';
+            i++;
+            continue;
+        }
+        if (state === 'regex') {
+            push(ch);
+            if (ch === '\\') {
+                if (next) {
+                    push(next);
+                    i += 2;
+                    continue;
+                }
+            }
+            if (ch === '[')
+                regexCharClassDepth++;
+            if (ch === ']' && regexCharClassDepth > 0)
+                regexCharClassDepth--;
+            if (ch === '/' && regexCharClassDepth === 0) {
+                state = 'code';
+            }
+            i++;
+            continue;
+        }
+        if (state === 'line_comment') {
+            if (ch === '\n') {
+                out += '\n';
+                state = 'code';
+            }
+            i++;
+            continue;
+        }
+        if (state === 'block_comment') {
+            if (ch === '*' && next === '/') {
+                state = 'code';
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (state === 'jsdoc_comment') {
+            push(ch);
+            if (ch === '*' && next === '/') {
+                push(next);
+                state = 'code';
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=js-like-comments.js.map

package/dist/core/context/compression/smart-compress.js

@@ -0,0 +1,61 @@
+import { outlineSource } from '../ast/source-outline.js';
+import { stripJsLikeComments } from './js-like-comments.js';
+import { normalizeWhitespace } from './whitespace.js';
+function shouldPreserveJSDoc(budgetChars) {
+    if (budgetChars === undefined)
+        return false;
+    return budgetChars >= 30_000;
+}
+function compressRelatedFile(file, options) {
+    if (!file.content)
+        return file;
+    if (file.mode === 'outline') {
+        return {
+            ...file,
+            content: normalizeWhitespace(file.content, { maxConsecutiveBlankLines: 1 }),
+        };
+    }
+    const preserveJSDoc = shouldPreserveJSDoc(options.budgetChars);
+    const commentStripped = stripJsLikeComments(file.content, { preserveJSDoc });
+    const normalized = normalizeWhitespace(commentStripped, { maxConsecutiveBlankLines: 1 });
+    // For unusually large "full" related files, downgrade to outline to avoid wasting budget.
+    if (normalized.length > 12_000) {
+        const outline = outlineSource(file.content);
+        const outlineText = normalizeWhitespace(outline, { maxConsecutiveBlankLines: 1 });
+        return {
+            ...file,
+            mode: 'outline',
+            content: outlineText,
+            outline: undefined,
+        };
+    }
+    return { ...file, content: normalized };
+}
+function compressRelatedFiles(relatedFiles, options) {
+    if (!relatedFiles)
+        return relatedFiles;
+    return relatedFiles.map((f) => compressRelatedFile(f, options));
+}
+function compressDiffText(value) {
+    return normalizeWhitespace(value, { maxConsecutiveBlankLines: 1 });
+}
+export function applySmartCompression(context, options = {}) {
+    return {
+        ...context,
+        primaryText: context.primaryText,
+        relatedFiles: compressRelatedFiles(context.relatedFiles, options),
+        rgSnippets: context.rgSnippets.map((s) => ({
+            ...s,
+            content: normalizeWhitespace(s.content ?? '', { maxConsecutiveBlankLines: 0 }),
+        })),
+        gitDiff: context.gitDiff ? compressDiffText(context.gitDiff) : context.gitDiff,
+        stagedDiff: context.stagedDiff ? compressDiffText(context.stagedDiff) : context.stagedDiff,
+        unstagedDiff: context.unstagedDiff
+            ? compressDiffText(context.unstagedDiff)
+            : context.unstagedDiff,
+        untrackedDiff: context.untrackedDiff
+            ? compressDiffText(context.untrackedDiff)
+            : context.untrackedDiff,
+    };
+}
+//# sourceMappingURL=smart-compress.js.map