attocode 0.2.4 → 0.2.5

package/dist/src/integrations/context/context-engineering.js

@@ -0,0 +1,437 @@
+/**
+ * Context Engineering Integration
+ *
+ * Integrates the Manus-inspired context engineering tricks (P, Q, R, S, T)
+ * into the production agent for improved performance and reliability.
+ *
+ * Features:
+ * - P: KV-Cache Aware Context - ~10x cost reduction on cached tokens
+ * - Q: Recitation / Goal Reinforcement - Combat "lost in middle" attention
+ * - R: Reversible Compaction - Preserve retrieval keys during summarization
+ * - S: Failure Evidence Preservation - Learn from mistakes, avoid loops
+ * - T: Serialization Diversity - Prevent few-shot pattern collapse
+ */
+import { createCacheAwareContext, stableStringify, analyzeCacheEfficiency, } from '../../tricks/kv-cache-context.js';
+import { createRecitationManager, calculateOptimalFrequency, } from '../../tricks/recitation.js';
+import { createReversibleCompactor, createReconstructionPrompt, } from '../../tricks/reversible-compaction.js';
+import { createFailureTracker, extractInsights, } from '../../tricks/failure-evidence.js';
+import { createDiverseSerializer, } from '../../tricks/serialization-diversity.js';
+// =============================================================================
+// CONTEXT ENGINEERING MANAGER
+// =============================================================================
+/**
+ * Unified manager for all context engineering features.
+ */
+export class ContextEngineeringManager {
+    config;
+    // Sub-managers
+    cacheContext;
+    recitation;
+    compactor;
+    failureTracker;
+    serializer;
+    // Shared state (optional, injected for swarm workers)
+    sharedState = null;
+    // State
+    iteration = 0;
+    recitationInjections = 0;
+    patternsDetected = 0;
+    listeners = [];
+    constructor(config = {}) {
+        this.config = {
+            enableCacheOptimization: config.enableCacheOptimization ?? true,
+            enableRecitation: config.enableRecitation ?? true,
+            enableReversibleCompaction: config.enableReversibleCompaction ?? true,
+            enableFailureTracking: config.enableFailureTracking ?? true,
+            enableDiversity: config.enableDiversity ?? false, // Off by default
+            staticPrefix: config.staticPrefix ?? 'You are a helpful AI assistant.',
+            recitationFrequency: config.recitationFrequency ?? 5,
+            diversityLevel: config.diversityLevel ?? 0.2,
+            maxFailures: config.maxFailures ?? 30,
+            maxReferences: config.maxReferences ?? 50,
+        };
+        this.initializeSubManagers();
+    }
+    /**
+     * Initialize sub-managers based on config.
+     */
+    initializeSubManagers() {
+        if (this.config.enableCacheOptimization) {
+            this.cacheContext = createCacheAwareContext({
+                staticPrefix: this.config.staticPrefix,
+                cacheBreakpoints: ['system_end', 'tools_end', 'rules_end'],
+                deterministicJson: true,
+                enforceAppendOnly: true,
+            });
+        }
+        if (this.config.enableRecitation) {
+            this.recitation = createRecitationManager({
+                frequency: this.config.recitationFrequency,
+                sources: ['goal', 'plan', 'todo'],
+                maxTokens: 500,
+                trackHistory: true,
+            });
+        }
+        if (this.config.enableReversibleCompaction) {
+            this.compactor = createReversibleCompactor({
+                preserveTypes: ['file', 'url', 'function', 'error', 'command'],
+                maxReferences: this.config.maxReferences,
+                deduplicate: true,
+            });
+        }
+        if (this.config.enableFailureTracking) {
+            this.failureTracker = createFailureTracker({
+                maxFailures: this.config.maxFailures,
+                preserveStackTraces: true,
+                detectRepeats: true,
+                repeatWarningThreshold: 3,
+            });
+            // Listen for patterns
+            this.failureTracker.on((event) => {
+                if (event.type === 'pattern.detected') {
+                    this.patternsDetected++;
+                    this.emit({ type: 'failure.pattern', pattern: event.pattern });
+                }
+            });
+        }
+        if (this.config.enableDiversity) {
+            this.serializer = createDiverseSerializer({
+                variationLevel: this.config.diversityLevel,
+                preserveSemantics: true,
+                varyKeyOrder: true,
+                varyIndentation: true,
+            });
+        }
+    }
+    /**
+     * Bind to shared state for cross-worker failure learning and reference pooling.
+     * Called after construction when a worker joins a swarm.
+     * Replaces the local failure tracker with the shared one.
+     */
+    setSharedState(shared) {
+        this.sharedState = shared;
+        // Replace local failure tracker with shared one so all workers
+        // read/write to the same tracker
+        if (this.failureTracker) {
+            this.failureTracker = shared.getFailureTracker();
+        }
+    }
+    /**
+     * Build a cache-optimized system prompt.
+     */
+    buildSystemPrompt(options) {
+        if (!this.cacheContext) {
+            // Fallback: simple concatenation
+            const parts = [this.config.staticPrefix];
+            if (options.rules)
+                parts.push('\n\n## Rules\n' + options.rules);
+            if (options.tools)
+                parts.push('\n\n## Tools\n' + options.tools);
+            if (options.memory)
+                parts.push('\n\n## Context\n' + options.memory);
+            if (options.dynamic) {
+                const dynamicParts = Object.entries(options.dynamic)
+                    .map(([k, v]) => `${k}: ${v}`)
+                    .join(' | ');
+                parts.push('\n\n---\n' + dynamicParts);
+            }
+            return parts.join('');
+        }
+        // Analyze for warnings
+        const systemPrompt = this.cacheContext.buildSystemPrompt(options);
+        const analysis = analyzeCacheEfficiency(systemPrompt);
+        for (const warning of analysis.warnings) {
+            this.emit({ type: 'cache.warning', warning });
+        }
+        return systemPrompt;
+    }
+    /**
+     * Build a cache-optimized system prompt as CacheableContent blocks.
+     * Each section gets a `cache_control: { type: 'ephemeral' }` marker
+     * so the LLM provider can use prompt caching (60-70% cost reduction).
+     *
+     * Falls back to a single text block (no cache markers) if KV-cache
+     * context is not configured.
+     */
+    buildCacheableSystemPrompt(options) {
+        if (!this.cacheContext) {
+            // No KV-cache context configured — return empty array to signal
+            // "no caching available". The caller (agent.ts) will fall back to
+            // a plain string system message instead of sending unmarked blocks.
+            return [];
+        }
+        return this.cacheContext.buildCacheableSystemPrompt(options);
+    }
+    /**
+     * Serialize data with optional diversity.
+     */
+    serialize(data) {
+        if (this.serializer) {
+            return this.serializer.serialize(data);
+        }
+        // Use stable stringify for cache efficiency
+        return stableStringify(data);
+    }
+    /**
+     * Inject recitation if needed.
+     */
+    injectRecitation(messages, state) {
+        this.iteration++;
+        if (!this.recitation) {
+            return messages;
+        }
+        // Cast to compatible type - tool messages are preserved but not used in recitation
+        const result = this.recitation.injectIfNeeded(messages, {
+            ...state,
+            iteration: this.iteration,
+        });
+        if (result.length > messages.length) {
+            this.recitationInjections++;
+            this.emit({ type: 'recitation.injected', iteration: this.iteration });
+        }
+        return result;
+    }
+    /**
+     * Update recitation frequency based on context size.
+     */
+    updateRecitationFrequency(contextTokens) {
+        if (this.recitation) {
+            const frequency = calculateOptimalFrequency(contextTokens);
+            this.recitation.updateConfig({ frequency });
+        }
+    }
+    /**
+     * Compact messages with reference preservation.
+     */
+    async compact(messages, summarize) {
+        if (!this.compactor) {
+            // Fallback: simple summarization
+            const summary = await summarize(messages);
+            return {
+                summary,
+                references: [],
+                reconstructionPrompt: '',
+            };
+        }
+        const result = await this.compactor.compact(messages, { summarize });
+        // Push references to shared pool for cross-worker access
+        if (this.sharedState && result.references.length > 0) {
+            this.sharedState.addReferences(result.references);
+        }
+        this.emit({
+            type: 'compaction.completed',
+            references: result.references.length,
+        });
+        return {
+            summary: result.summary,
+            references: result.references,
+            reconstructionPrompt: createReconstructionPrompt(result.references),
+        };
+    }
+    /**
+     * Search preserved references.
+     */
+    searchReferences(query) {
+        return this.compactor?.searchReferences(query) || [];
+    }
+    /**
+     * Get preserved references by type.
+     */
+    getReferencesByType(type) {
+        return this.compactor?.getReferencesByType(type) || [];
+    }
+    /**
+     * Record a failure.
+     */
+    recordFailure(input) {
+        if (!this.failureTracker) {
+            return null;
+        }
+        const failure = this.failureTracker.recordFailure({
+            ...input,
+            iteration: this.iteration,
+        });
+        this.emit({ type: 'failure.recorded', failure });
+        return failure;
+    }
+    /**
+     * Get failure context for LLM inclusion.
+     */
+    getFailureContext(maxFailures = 10) {
+        return this.failureTracker?.getFailureContext({ maxFailures }) || '';
+    }
+    /**
+     * Check if an action has failed recently.
+     */
+    hasRecentFailure(action) {
+        return this.failureTracker?.hasRecentFailure(action, 120000) || false;
+    }
+    /**
+     * Get actionable insights from failures.
+     */
+    getFailureInsights() {
+        if (!this.failureTracker)
+            return [];
+        return extractInsights(this.failureTracker.getUnresolvedFailures());
+    }
+    /**
+     * Mark a failure as resolved.
+     */
+    resolveFailure(failureId) {
+        return this.failureTracker?.resolveFailure(failureId) || false;
+    }
+    /**
+     * Get the underlying failure tracker for external integrations.
+     * Useful for connecting to LearningStore for cross-session learning.
+     */
+    getFailureTracker() {
+        return this.failureTracker;
+    }
+    /**
+     * Get current statistics.
+     */
+    getStats() {
+        const stats = {
+            recitationInjections: this.recitationInjections,
+            preservedReferences: this.compactor?.getPreservedReferences().length || 0,
+            trackedFailures: this.failureTracker?.getStats().total || 0,
+            unresolvedFailures: this.failureTracker?.getStats().unresolved || 0,
+            patternsDetected: this.patternsDetected,
+        };
+        if (this.serializer) {
+            stats.diversity = this.serializer.getStats();
+        }
+        return stats;
+    }
+    /**
+     * Get current iteration.
+     */
+    getIteration() {
+        return this.iteration;
+    }
+    /**
+     * Reset iteration counter (e.g., for new session).
+     */
+    resetIteration() {
+        this.iteration = 0;
+        this.recitationInjections = 0;
+    }
+    /**
+     * Clear all tracked state.
+     */
+    clear() {
+        this.iteration = 0;
+        this.recitationInjections = 0;
+        this.patternsDetected = 0;
+        this.cacheContext?.reset();
+        this.recitation?.clearHistory();
+        this.compactor?.clear();
+        this.failureTracker?.clear();
+        this.serializer?.resetStats();
+    }
+    /**
+     * Subscribe to events.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a context engineering manager.
+ *
+ * @example
+ * ```typescript
+ * const contextEng = createContextEngineering({
+ *   enableCacheOptimization: true,
+ *   enableRecitation: true,
+ *   enableFailureTracking: true,
+ *   staticPrefix: 'You are a coding assistant.',
+ *   recitationFrequency: 5,
+ * });
+ *
+ * // Build cache-optimized system prompt
+ * const systemPrompt = contextEng.buildSystemPrompt({
+ *   rules: rulesContent,
+ *   tools: toolDescriptions,
+ *   dynamic: { sessionId: 'abc123' },
+ * });
+ *
+ * // Inject recitation during agent loop
+ * const messages = contextEng.injectRecitation(currentMessages, {
+ *   goal: 'Implement user auth',
+ *   plan: currentPlan,
+ *   todos: currentTodos,
+ * });
+ *
+ * // Record failures
+ * try {
+ *   await tool.execute(args);
+ * } catch (error) {
+ *   contextEng.recordFailure({
+ *     action: tool.name,
+ *     args,
+ *     error,
+ *   });
+ * }
+ *
+ * // Include failure context in prompts
+ * const failureContext = contextEng.getFailureContext();
+ * ```
+ */
+export function createContextEngineering(config = {}) {
+    return new ContextEngineeringManager(config);
+}
+/**
+ * Create a minimal context engineering manager for testing.
+ */
+export function createMinimalContextEngineering() {
+    return new ContextEngineeringManager({
+        enableCacheOptimization: false,
+        enableRecitation: false,
+        enableReversibleCompaction: false,
+        enableFailureTracking: true, // Keep failure tracking
+        enableDiversity: false,
+    });
+}
+/**
+ * Create a full-featured context engineering manager.
+ */
+export function createFullContextEngineering(staticPrefix) {
+    return new ContextEngineeringManager({
+        enableCacheOptimization: true,
+        enableRecitation: true,
+        enableReversibleCompaction: true,
+        enableFailureTracking: true,
+        enableDiversity: true,
+        staticPrefix,
+        diversityLevel: 0.2,
+        recitationFrequency: 5,
+        maxFailures: 50,
+        maxReferences: 100,
+    });
+}
+// =============================================================================
+// EXPORTS
+// =============================================================================
+export { 
+// Re-export from tricks for convenience
+stableStringify, calculateOptimalFrequency, createReconstructionPrompt, extractInsights, };
+//# sourceMappingURL=context-engineering.js.map

package/dist/src/integrations/context/context-engineering.js.map

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

package/dist/src/integrations/context/file-cache.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared File Cache
+ *
+ * Provides an in-memory LRU file cache shared across parent and child agents.
+ * Eliminates redundant file reads in multi-agent workflows where parent + N children
+ * each independently read the same large files (e.g., agent.ts at 212KB).
+ *
+ * The cache is created by the parent agent and passed to subagents via config.
+ * Since subagents run in the same process, they share the same Map reference.
+ *
+ * Cache invalidation:
+ * - Write operations to a file invalidate its cache entry
+ * - Entries expire after a configurable TTL (default: 5 minutes)
+ * - LRU eviction when max cache size is exceeded
+ *
+ * All file paths are normalized via path.resolve() to ensure consistent cache
+ * keys regardless of relative vs absolute path usage across agents.
+ */
+import type { TraceCollector } from '../../tracing/trace-collector.js';
+export interface FileCacheEntry {
+    content: string;
+    timestamp: number;
+    size: number;
+    /** How many times this entry has been served from cache */
+    hits: number;
+}
+export interface FileCacheConfig {
+    /** Maximum total cache size in bytes (default: 5MB) */
+    maxCacheBytes?: number;
+    /** Time-to-live for cache entries in ms (default: 5 minutes) */
+    ttlMs?: number;
+    /** Whether to enable cache statistics tracking */
+    trackStats?: boolean;
+    /** Optional trace collector for emitting filecache.event trace events */
+    traceCollector?: TraceCollector;
+    /** Agent ID to include in trace events */
+    agentId?: string;
+}
+export interface FileCacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Total invalidations (from writes) */
+    invalidations: number;
+    /** Total evictions (from LRU) */
+    evictions: number;
+    /** Current number of entries */
+    entries: number;
+    /** Current cache size in bytes */
+    currentBytes: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+}
+export declare class SharedFileCache {
+    private cache;
+    private accessOrder;
+    private currentBytes;
+    private readonly maxCacheBytes;
+    private readonly ttlMs;
+    private readonly trackStats;
+    private readonly traceCollector?;
+    private readonly agentId?;
+    private hits;
+    private misses;
+    private invalidations;
+    private evictions;
+    constructor(config?: FileCacheConfig);
+    /** Normalize path to ensure consistent cache keys across agents */
+    private normalizePath;
+    /**
+     * Get a file's content from cache.
+     * Returns undefined if not cached, expired, or evicted.
+     */
+    get(filePath: string): string | undefined;
+    /**
+     * Store a file's content in cache.
+     * Evicts LRU entries if needed to make room.
+     */
+    set(filePath: string, content: string): void;
+    /**
+     * Invalidate a cache entry (called when a file is written/modified).
+     */
+    invalidate(filePath: string): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): FileCacheStats;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): void;
+    private delete;
+    private touchLRU;
+}
+export declare function createSharedFileCache(config?: FileCacheConfig): SharedFileCache;
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/src/integrations/context/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../../../src/integrations/context/file-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAMvE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAGlC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAK;gBAEV,MAAM,GAAE,eAAoB;IAQxC,mEAAmE;IACnE,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAyDzC;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IA2C5C;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAkBlC;;OAEG;IACH,QAAQ,IAAI,cAAc;IAa1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,QAAQ;CAOjB;AAMD,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,eAAe,CAE/E"}