attocode 0.1.0

package/dist/src/tricks/kv-cache-context.js

@@ -0,0 +1,377 @@
+/**
+ * Trick P: KV-Cache Aware Context
+ *
+ * Optimizes context structure for LLM KV-cache efficiency.
+ * Cached input tokens cost ~10x less than uncached ones.
+ *
+ * Key principles:
+ * 1. Keep system prompt PREFIX stable (no timestamps, session IDs at start)
+ * 2. Use deterministic JSON serialization (sorted keys)
+ * 3. Mark explicit cache breakpoints
+ * 4. Append-only message history (never modify past messages)
+ *
+ * @example
+ * ```typescript
+ * import { createCacheAwareContext, stableStringify } from './kv-cache-context';
+ *
+ * const context = createCacheAwareContext({
+ *   staticPrefix: 'You are a helpful coding assistant.',
+ *   cacheBreakpoints: ['system_end', 'tools_end'],
+ * });
+ *
+ * // Build system prompt with stable prefix
+ * const systemPrompt = context.buildSystemPrompt({
+ *   rules: rulesContent,
+ *   sessionId: 'abc123',  // Goes at END, not beginning
+ * });
+ *
+ * // Serialize tool calls deterministically
+ * const serialized = stableStringify(toolCall.arguments);
+ * ```
+ */
+// =============================================================================
+// DETERMINISTIC JSON SERIALIZATION
+// =============================================================================
+/**
+ * Stringify JSON with sorted keys for deterministic output.
+ * This ensures the same object always produces the same string,
+ * which is critical for KV-cache efficiency.
+ *
+ * @example
+ * ```typescript
+ * // Standard JSON.stringify - key order not guaranteed
+ * JSON.stringify({ b: 1, a: 2 }); // Could be '{"b":1,"a":2}' or '{"a":2,"b":1}'
+ *
+ * // stableStringify - always same order
+ * stableStringify({ b: 1, a: 2 }); // Always '{"a":2,"b":1}'
+ * ```
+ */
+export function stableStringify(obj, indent) {
+    return JSON.stringify(obj, sortedReplacer, indent);
+}
+/**
+ * JSON replacer that sorts object keys.
+ */
+function sortedReplacer(_key, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return value;
+    }
+    // Sort keys and create new object
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (const k of keys) {
+        sorted[k] = value[k];
+    }
+    return sorted;
+}
+/**
+ * Parse JSON and re-serialize deterministically.
+ * Useful for normalizing JSON strings from external sources.
+ */
+export function normalizeJson(jsonString) {
+    try {
+        const parsed = JSON.parse(jsonString);
+        return stableStringify(parsed);
+    }
+    catch {
+        return jsonString; // Return as-is if not valid JSON
+    }
+}
+// =============================================================================
+// CACHE-AWARE CONTEXT MANAGER
+// =============================================================================
+/**
+ * Manages context in a KV-cache-friendly way.
+ */
+export class CacheAwareContext {
+    config;
+    messageHashes = new Map();
+    listeners = [];
+    breakpointPositions = new Map();
+    constructor(config) {
+        this.config = {
+            staticPrefix: config.staticPrefix,
+            cacheBreakpoints: config.cacheBreakpoints ?? ['system_end'],
+            deterministicJson: config.deterministicJson ?? true,
+            enforceAppendOnly: config.enforceAppendOnly ?? true,
+        };
+    }
+    /**
+     * Build system prompt with stable prefix and dynamic content at END.
+     *
+     * @example
+     * ```typescript
+     * const prompt = context.buildSystemPrompt({
+     *   rules: 'Follow these rules...',
+     *   tools: toolDescriptions,
+     *   dynamic: { sessionId: 'abc', mode: 'build' },
+     * });
+     * // Result:
+     * // "You are a helpful assistant.  <- STABLE (cached)
+     * //
+     * //  ## Rules
+     * //  Follow these rules...         <- Semi-stable (cached if unchanged)
+     * //
+     * //  ## Tools
+     * //  [tool descriptions]           <- Semi-stable
+     * //
+     * //  ---
+     * //  Session: abc | Mode: build"   <- DYNAMIC (not cached)
+     * ```
+     */
+    buildSystemPrompt(options) {
+        const parts = [];
+        let position = 0;
+        // 1. Static prefix (ALWAYS first, never changes)
+        parts.push(this.config.staticPrefix);
+        position += this.config.staticPrefix.length;
+        // Mark system_end breakpoint after static prefix
+        if (this.config.cacheBreakpoints.includes('system_end')) {
+            this.markBreakpoint('system_end', position);
+        }
+        // 2. Rules content (semi-stable)
+        if (options.rules) {
+            parts.push('\n\n## Rules\n' + options.rules);
+            position += options.rules.length + 12;
+            if (this.config.cacheBreakpoints.includes('rules_end')) {
+                this.markBreakpoint('rules_end', position);
+            }
+        }
+        // 3. Tool descriptions (semi-stable)
+        if (options.tools) {
+            parts.push('\n\n## Available Tools\n' + options.tools);
+            position += options.tools.length + 22;
+            if (this.config.cacheBreakpoints.includes('tools_end')) {
+                this.markBreakpoint('tools_end', position);
+            }
+        }
+        // 4. Memory context (changes more frequently)
+        if (options.memory) {
+            parts.push('\n\n## Relevant Context\n' + options.memory);
+            position += options.memory.length + 22;
+            if (this.config.cacheBreakpoints.includes('memory_end')) {
+                this.markBreakpoint('memory_end', position);
+            }
+        }
+        // 5. Dynamic content at END (changes every request)
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            const dynamicParts = [];
+            if (options.dynamic.sessionId) {
+                dynamicParts.push(`Session: ${options.dynamic.sessionId}`);
+            }
+            if (options.dynamic.mode) {
+                dynamicParts.push(`Mode: ${options.dynamic.mode}`);
+            }
+            if (options.dynamic.timestamp) {
+                dynamicParts.push(`Time: ${options.dynamic.timestamp}`);
+            }
+            // Add any custom dynamic values
+            for (const [key, value] of Object.entries(options.dynamic)) {
+                if (!['sessionId', 'mode', 'timestamp'].includes(key) && value) {
+                    dynamicParts.push(`${key}: ${value}`);
+                }
+            }
+            if (dynamicParts.length > 0) {
+                parts.push('\n\n---\n' + dynamicParts.join(' | '));
+            }
+        }
+        return parts.join('');
+    }
+    /**
+     * Validate that messages follow append-only constraint.
+     * Returns violations if any past messages were modified.
+     */
+    validateAppendOnly(messages) {
+        if (!this.config.enforceAppendOnly) {
+            return [];
+        }
+        const violations = [];
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            const currentHash = this.hashMessage(msg);
+            const previousHash = this.messageHashes.get(i);
+            if (previousHash !== undefined && previousHash !== currentHash) {
+                violations.push(`Message at index ${i} was modified (role: ${msg.role})`);
+                this.emit({
+                    type: 'cache.violation',
+                    reason: 'message_modified',
+                    details: `Index ${i}, role ${msg.role}`,
+                });
+            }
+            // Update hash for this position
+            this.messageHashes.set(i, currentHash);
+        }
+        return violations;
+    }
+    /**
+     * Serialize a message in a cache-friendly way.
+     */
+    serializeMessage(message) {
+        if (this.config.deterministicJson) {
+            return stableStringify(message);
+        }
+        return JSON.stringify(message);
+    }
+    /**
+     * Serialize tool arguments deterministically.
+     */
+    serializeToolArgs(args) {
+        if (this.config.deterministicJson) {
+            return stableStringify(args);
+        }
+        return JSON.stringify(args);
+    }
+    /**
+     * Calculate cache statistics for a context.
+     */
+    calculateCacheStats(options) {
+        const { systemPrompt, messages, dynamicContentLength = 0 } = options;
+        // Estimate tokens (~4 chars per token)
+        const totalChars = systemPrompt.length +
+            messages.reduce((sum, m) => sum + m.content.length, 0);
+        const totalTokens = Math.ceil(totalChars / 4);
+        // Cacheable = everything except dynamic content at end
+        const cacheableChars = totalChars - dynamicContentLength;
+        const cacheableTokens = Math.ceil(cacheableChars / 4);
+        const nonCacheableTokens = totalTokens - cacheableTokens;
+        const cacheRatio = cacheableTokens / totalTokens;
+        // Cost savings: cached tokens are ~10x cheaper
+        // If 80% is cached, savings = 0.8 * 0.9 = 0.72 (72% savings)
+        const estimatedSavings = cacheRatio * 0.9;
+        const stats = {
+            cacheableTokens,
+            nonCacheableTokens,
+            cacheRatio,
+            estimatedSavings,
+        };
+        this.emit({ type: 'cache.stats', stats });
+        return stats;
+    }
+    /**
+     * Get breakpoint positions.
+     */
+    getBreakpointPositions() {
+        return new Map(this.breakpointPositions);
+    }
+    /**
+     * Subscribe to cache events.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    /**
+     * Reset message hashes (call when starting new session).
+     */
+    reset() {
+        this.messageHashes.clear();
+        this.breakpointPositions.clear();
+    }
+    // Internal methods
+    hashMessage(message) {
+        // Simple hash for change detection
+        const content = `${message.role}:${message.content}`;
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return hash.toString(16);
+    }
+    markBreakpoint(breakpoint, position) {
+        this.breakpointPositions.set(breakpoint, position);
+        this.emit({ type: 'cache.breakpoint', breakpoint, position });
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a cache-aware context manager.
+ *
+ * @example
+ * ```typescript
+ * const context = createCacheAwareContext({
+ *   staticPrefix: `You are a coding assistant.
+ *
+ * You help users write, debug, and understand code.
+ * Always explain your reasoning.`,
+ *   cacheBreakpoints: ['system_end', 'tools_end'],
+ *   deterministicJson: true,
+ * });
+ * ```
+ */
+export function createCacheAwareContext(config) {
+    return new CacheAwareContext(config);
+}
+// =============================================================================
+// UTILITIES
+// =============================================================================
+/**
+ * Check if a system prompt has timestamps/dynamic content at the start.
+ * Returns warnings about cache-unfriendly patterns.
+ */
+export function analyzeCacheEfficiency(systemPrompt) {
+    const warnings = [];
+    const suggestions = [];
+    // Check for timestamps at start
+    const timestampPatterns = [
+        /^\[?\d{4}-\d{2}-\d{2}/, // ISO date
+        /^\[?\d{1,2}\/\d{1,2}\/\d{4}/, // US date
+        /^Current time:/i,
+        /^Timestamp:/i,
+        /^Date:/i,
+    ];
+    for (const pattern of timestampPatterns) {
+        if (pattern.test(systemPrompt)) {
+            warnings.push('Timestamp/date at start of prompt will invalidate cache');
+            suggestions.push('Move timestamps to END of system prompt');
+            break;
+        }
+    }
+    // Check for session IDs at start
+    if (/^Session( ID)?:/i.test(systemPrompt)) {
+        warnings.push('Session ID at start will invalidate cache');
+        suggestions.push('Move session ID to END of system prompt');
+    }
+    // Check for random/dynamic content at start
+    if (/^(Random|Dynamic|Generated):/i.test(systemPrompt)) {
+        warnings.push('Dynamic content at start will invalidate cache');
+        suggestions.push('Move dynamic content to END of system prompt');
+    }
+    return { warnings, suggestions };
+}
+/**
+ * Format cache stats for display.
+ */
+export function formatCacheStats(stats) {
+    const cachePercent = Math.round(stats.cacheRatio * 100);
+    const savingsPercent = Math.round(stats.estimatedSavings * 100);
+    return `KV-Cache Statistics:
+  Cacheable tokens:     ${stats.cacheableTokens.toLocaleString()}
+  Non-cacheable tokens: ${stats.nonCacheableTokens.toLocaleString()}
+  Cache ratio:          ${cachePercent}%
+  Estimated savings:    ${savingsPercent}% cost reduction`;
+}
+/**
+ * Create a cache-friendly timestamp that goes at the end.
+ */
+export function createEndTimestamp() {
+    return `[Context generated at ${new Date().toISOString()}]`;
+}
+//# sourceMappingURL=kv-cache-context.js.map

package/dist/src/tricks/kv-cache-context.js.map

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

package/dist/src/tricks/recitation.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Trick Q: Recitation / Goal Reinforcement
+ *
+ * Periodically injects task summaries (plans, todos, goals) into the END
+ * of the context to combat "lost in the middle" attention issues.
+ *
+ * Problem: In long conversations (50+ tool calls), the model "forgets"
+ * the original goal because it's buried in the middle of the context.
+ *
+ * Solution: Periodically "recite" the current goal/plan at the context end,
+ * pushing it into the model's recent attention span.
+ *
+ * @example
+ * ```typescript
+ * import { createRecitationManager } from './recitation';
+ *
+ * const recitation = createRecitationManager({
+ *   frequency: 5,  // Every 5 iterations
+ *   sources: ['plan', 'todo', 'goal'],
+ * });
+ *
+ * // In agent loop
+ * const messages = recitation.injectIfNeeded(
+ *   currentMessages,
+ *   { plan, todos, goal, iteration: 15 }
+ * );
+ * ```
+ */
+/**
+ * Sources of content to recite.
+ */
+export type RecitationSource = 'plan' | 'todo' | 'goal' | 'memory' | 'custom';
+/**
+ * Configuration for recitation.
+ */
+export interface RecitationConfig {
+    /** Inject recitation every N iterations (default: 5) */
+    frequency: number;
+    /** Sources to include in recitation */
+    sources: RecitationSource[];
+    /** Maximum tokens for recitation block (default: 500) */
+    maxTokens?: number;
+    /** Custom recitation builder */
+    customBuilder?: (state: RecitationState) => string | null;
+    /** Whether to track injection history */
+    trackHistory?: boolean;
+}
+/**
+ * Current state for building recitation.
+ */
+export interface RecitationState {
+    /** Current iteration number */
+    iteration: number;
+    /** Original user goal/task */
+    goal?: string;
+    /** Current plan with tasks */
+    plan?: PlanState;
+    /** Current todo list */
+    todos?: TodoItem[];
+    /** Relevant memory items */
+    memories?: string[];
+    /** Files currently being worked on */
+    activeFiles?: string[];
+    /** Recent errors encountered */
+    recentErrors?: string[];
+    /** Custom state values */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Plan state.
+ */
+export interface PlanState {
+    description: string;
+    tasks: PlanTask[];
+    currentTaskIndex: number;
+}
+/**
+ * Task in a plan.
+ */
+export interface PlanTask {
+    id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed';
+}
+/**
+ * Todo item.
+ */
+export interface TodoItem {
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+/**
+ * Message for injection.
+ */
+export interface RecitationMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Recitation history entry.
+ */
+export interface RecitationEntry {
+    iteration: number;
+    timestamp: string;
+    content: string;
+    sources: RecitationSource[];
+}
+/**
+ * Events emitted by recitation manager.
+ */
+export type RecitationEvent = {
+    type: 'recitation.injected';
+    iteration: number;
+    sources: RecitationSource[];
+} | {
+    type: 'recitation.skipped';
+    iteration: number;
+    reason: string;
+} | {
+    type: 'recitation.built';
+    content: string;
+    tokenEstimate: number;
+};
+export type RecitationEventListener = (event: RecitationEvent) => void;
+/**
+ * Manages periodic goal/plan recitation.
+ */
+export declare class RecitationManager {
+    private config;
+    private history;
+    private lastInjectionIteration;
+    private listeners;
+    constructor(config: RecitationConfig);
+    /**
+     * Check if recitation should be injected at this iteration.
+     */
+    shouldInject(iteration: number): boolean;
+    /**
+     * Build recitation content from state.
+     */
+    buildRecitation(state: RecitationState): string | null;
+    /**
+     * Inject recitation into messages if needed.
+     * Returns the modified message array.
+     */
+    injectIfNeeded<T extends RecitationMessage>(messages: T[], state: RecitationState): T[];
+    /**
+     * Force recitation injection regardless of frequency.
+     */
+    forceInject<T extends RecitationMessage>(messages: T[], state: RecitationState): T[];
+    /**
+     * Get injection history.
+     */
+    getHistory(): RecitationEntry[];
+    /**
+     * Clear history.
+     */
+    clearHistory(): void;
+    /**
+     * Update configuration.
+     */
+    updateConfig(updates: Partial<RecitationConfig>): void;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: RecitationEventListener): () => void;
+    private buildPlanSummary;
+    private buildTodoSummary;
+    private buildMemorySummary;
+    private truncateContent;
+    private findLastUserMessageIndex;
+    private emit;
+}
+/**
+ * Create a recitation manager.
+ *
+ * @example
+ * ```typescript
+ * const recitation = createRecitationManager({
+ *   frequency: 5,  // Every 5 iterations
+ *   sources: ['goal', 'plan', 'todo'],
+ *   maxTokens: 500,
+ * });
+ *
+ * // In agent loop
+ * const enrichedMessages = recitation.injectIfNeeded(messages, {
+ *   iteration: currentIteration,
+ *   goal: 'Implement user authentication',
+ *   plan: currentPlan,
+ *   todos: currentTodos,
+ * });
+ * ```
+ */
+export declare function createRecitationManager(config: RecitationConfig): RecitationManager;
+/**
+ * Quick helper to build a recitation block without full manager.
+ */
+export declare function buildQuickRecitation(state: RecitationState): string;
+/**
+ * Calculate optimal recitation frequency based on context size.
+ * Longer contexts need more frequent recitation.
+ */
+export declare function calculateOptimalFrequency(contextTokens: number): number;
+/**
+ * Format recitation history for debugging.
+ */
+export declare function formatRecitationHistory(history: RecitationEntry[]): string;
+//# sourceMappingURL=recitation.d.ts.map

package/dist/src/tricks/recitation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recitation.d.ts","sourceRoot":"","sources":["../../../src/tricks/recitation.ts"],"names":[],"mappings":"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"}