attocode 0.2.3 → 0.2.5

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

@@ -0,0 +1,274 @@
+/**
+ * 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, type CacheableContentBlock } from '../../tricks/kv-cache-context.js';
+import { calculateOptimalFrequency, type RecitationState } from '../../tricks/recitation.js';
+import { createReconstructionPrompt, type Reference } from '../../tricks/reversible-compaction.js';
+import { FailureTracker, extractInsights, type Failure, type FailurePattern } from '../../tricks/failure-evidence.js';
+import { type DiversityStats } from '../../tricks/serialization-diversity.js';
+import type { SharedContextState } from '../../shared/shared-context-state.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 sharedState;
+    private iteration;
+    private recitationInjections;
+    private patternsDetected;
+    private listeners;
+    constructor(config?: ContextEngineeringConfig);
+    /**
+     * Initialize sub-managers based on config.
+     */
+    private initializeSubManagers;
+    /**
+     * 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: SharedContextState): void;
+    /**
+     * Build a cache-optimized system prompt.
+     */
+    buildSystemPrompt(options: {
+        rules?: string;
+        tools?: string;
+        memory?: string;
+        dynamic?: Record<string, string>;
+    }): string;
+    /**
+     * 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: {
+        rules?: string;
+        tools?: string;
+        memory?: string;
+        dynamic?: Record<string, string>;
+    }): CacheableContentBlock[];
+    /**
+     * 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 the underlying failure tracker for external integrations.
+     * Useful for connecting to LearningStore for cross-session learning.
+     */
+    getFailureTracker(): FailureTracker | undefined;
+    /**
+     * 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, };
+export type { CacheableContentBlock } from '../../tricks/kv-cache-context.js';
+//# sourceMappingURL=context-engineering.d.ts.map

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

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