attocode 0.1.0

package/dist/src/integrations/context-engineering.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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 { stableStringify, type CacheStats } from '../tricks/kv-cache-context.js';
+import { calculateOptimalFrequency, type RecitationState } from '../tricks/recitation.js';
+import { createReconstructionPrompt, type Reference } from '../tricks/reversible-compaction.js';
+import { extractInsights, type Failure, type FailurePattern } from '../tricks/failure-evidence.js';
+import { type DiversityStats } from '../tricks/serialization-diversity.js';
+/**
+ * Configuration for context engineering.
+ */
+export interface ContextEngineeringConfig {
+    /** Enable KV-cache optimization */
+    enableCacheOptimization?: boolean;
+    /** Enable periodic goal recitation */
+    enableRecitation?: boolean;
+    /** Enable reversible compaction */
+    enableReversibleCompaction?: boolean;
+    /** Enable failure tracking */
+    enableFailureTracking?: boolean;
+    /** Enable serialization diversity */
+    enableDiversity?: boolean;
+    /** Static prefix for system prompt (for cache optimization) */
+    staticPrefix?: string;
+    /** Recitation frequency (iterations) */
+    recitationFrequency?: number;
+    /** Diversity level (0-1) */
+    diversityLevel?: number;
+    /** Maximum failures to track */
+    maxFailures?: number;
+    /** Maximum references to preserve during compaction */
+    maxReferences?: number;
+}
+/**
+ * Message format for context engineering.
+ */
+export interface ContextMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    name?: string;
+}
+/**
+ * Context engineering statistics.
+ */
+export interface ContextEngineeringStats {
+    /** KV-cache statistics */
+    cache?: CacheStats;
+    /** Recitation injection count */
+    recitationInjections: number;
+    /** Preserved references from compaction */
+    preservedReferences: number;
+    /** Tracked failures */
+    trackedFailures: number;
+    /** Unresolved failures */
+    unresolvedFailures: number;
+    /** Failure patterns detected */
+    patternsDetected: number;
+    /** Serialization diversity stats */
+    diversity?: DiversityStats;
+}
+/**
+ * Events emitted by context engineering manager.
+ */
+export type ContextEngineeringEvent = {
+    type: 'recitation.injected';
+    iteration: number;
+} | {
+    type: 'failure.recorded';
+    failure: Failure;
+} | {
+    type: 'failure.pattern';
+    pattern: FailurePattern;
+} | {
+    type: 'compaction.completed';
+    references: number;
+} | {
+    type: 'cache.warning';
+    warning: string;
+};
+export type ContextEngineeringEventListener = (event: ContextEngineeringEvent) => void;
+/**
+ * Unified manager for all context engineering features.
+ */
+export declare class ContextEngineeringManager {
+    private config;
+    private cacheContext?;
+    private recitation?;
+    private compactor?;
+    private failureTracker?;
+    private serializer?;
+    private iteration;
+    private recitationInjections;
+    private patternsDetected;
+    private listeners;
+    constructor(config?: ContextEngineeringConfig);
+    /**
+     * Initialize sub-managers based on config.
+     */
+    private initializeSubManagers;
+    /**
+     * Build a cache-optimized system prompt.
+     */
+    buildSystemPrompt(options: {
+        rules?: string;
+        tools?: string;
+        memory?: string;
+        dynamic?: Record<string, string>;
+    }): string;
+    /**
+     * Serialize data with optional diversity.
+     */
+    serialize(data: unknown): string;
+    /**
+     * Inject recitation if needed.
+     */
+    injectRecitation(messages: ContextMessage[], state: Omit<RecitationState, 'iteration'>): ContextMessage[];
+    /**
+     * Update recitation frequency based on context size.
+     */
+    updateRecitationFrequency(contextTokens: number): void;
+    /**
+     * Compact messages with reference preservation.
+     */
+    compact(messages: ContextMessage[], summarize: (msgs: ContextMessage[]) => Promise<string>): Promise<{
+        summary: string;
+        references: Reference[];
+        reconstructionPrompt: string;
+    }>;
+    /**
+     * Search preserved references.
+     */
+    searchReferences(query: string): Reference[];
+    /**
+     * Get preserved references by type.
+     */
+    getReferencesByType(type: string): Reference[];
+    /**
+     * Record a failure.
+     */
+    recordFailure(input: {
+        action: string;
+        args?: Record<string, unknown>;
+        error: string | Error;
+        intent?: string;
+    }): Failure | null;
+    /**
+     * Get failure context for LLM inclusion.
+     */
+    getFailureContext(maxFailures?: number): string;
+    /**
+     * Check if an action has failed recently.
+     */
+    hasRecentFailure(action: string): boolean;
+    /**
+     * Get actionable insights from failures.
+     */
+    getFailureInsights(): string[];
+    /**
+     * Mark a failure as resolved.
+     */
+    resolveFailure(failureId: string): boolean;
+    /**
+     * Get current statistics.
+     */
+    getStats(): ContextEngineeringStats;
+    /**
+     * Get current iteration.
+     */
+    getIteration(): number;
+    /**
+     * Reset iteration counter (e.g., for new session).
+     */
+    resetIteration(): void;
+    /**
+     * Clear all tracked state.
+     */
+    clear(): void;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: ContextEngineeringEventListener): () => void;
+    private emit;
+}
+/**
+ * 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 declare function createContextEngineering(config?: ContextEngineeringConfig): ContextEngineeringManager;
+/**
+ * Create a minimal context engineering manager for testing.
+ */
+export declare function createMinimalContextEngineering(): ContextEngineeringManager;
+/**
+ * Create a full-featured context engineering manager.
+ */
+export declare function createFullContextEngineering(staticPrefix: string): ContextEngineeringManager;
+export { stableStringify, calculateOptimalFrequency, createReconstructionPrompt, extractInsights, };
+//# sourceMappingURL=context-engineering.d.ts.map

package/dist/src/integrations/context-engineering.d.ts.map

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

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

@@ -0,0 +1,394 @@
+/**
+ * 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;
+    // 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,
+            });
+        }
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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 });
+        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 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-engineering.js.map

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