attocode 0.1.0

package/dist/src/tricks/json-utils.js

@@ -0,0 +1,247 @@
+/**
+ * Trick: JSON Utilities
+ *
+ * Robust JSON parsing utilities that handle:
+ * - Nested objects (the regex `\{[^}]*\}` problem)
+ * - Strings containing braces
+ * - Escaped quotes
+ * - Malformed JSON with recovery
+ * - LLM response extraction (code blocks, tool calls)
+ */
+// =============================================================================
+// CORE: EXTRACT JSON OBJECT
+// =============================================================================
+/**
+ * Extract a complete JSON object from text using brace-depth tracking.
+ *
+ * Unlike regex `\{[^}]*\}`, this properly handles:
+ * - Nested objects: `{"a": {"b": 1}}`
+ * - Nested arrays: `{"a": [1, [2, 3]]}`
+ * - Strings containing braces: `{"text": "hello { } world"}`
+ * - Escaped quotes: `{"text": "he said \"hi\""}`
+ *
+ * @param text - The text to search for JSON
+ * @param startFrom - Optional index to start searching from
+ * @returns The extracted JSON string and its end index, or null if not found
+ */
+export function extractJsonObject(text, startFrom = 0) {
+    // Find the first `{`
+    const start = text.indexOf('{', startFrom);
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < text.length; i++) {
+        const char = text[i];
+        // Handle escape sequences inside strings
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (char === '\\' && inString) {
+            escape = true;
+            continue;
+        }
+        // Toggle string state on unescaped quotes
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        // Only count braces outside of strings
+        if (!inString) {
+            if (char === '{' || char === '[')
+                depth++;
+            if (char === '}' || char === ']')
+                depth--;
+            if (depth === 0) {
+                // Found complete JSON object
+                return {
+                    json: text.slice(start, i + 1),
+                    endIndex: i + 1,
+                };
+            }
+        }
+    }
+    // Incomplete JSON (unclosed braces)
+    return null;
+}
+/**
+ * Extract all JSON objects from text.
+ */
+export function extractAllJsonObjects(text) {
+    const results = [];
+    let position = 0;
+    while (position < text.length) {
+        const extracted = extractJsonObject(text, position);
+        if (!extracted)
+            break;
+        results.push(extracted.json);
+        position = extracted.endIndex;
+    }
+    return results;
+}
+// =============================================================================
+// SAFE PARSE: MULTI-LEVEL FALLBACK
+// =============================================================================
+/**
+ * Safely parse JSON with multi-level fallback and recovery.
+ *
+ * Fallback levels:
+ * 1. Direct JSON.parse
+ * 2. Extract JSON object from surrounding text
+ * 3. Attempt malformed JSON recovery (if enabled)
+ *
+ * @param input - Raw input (may be JSON or text containing JSON)
+ * @param options - Parsing options
+ */
+export function safeParseJson(input, options = {}) {
+    const { context, attemptRecovery = true } = options;
+    if (!input || typeof input !== 'string') {
+        return {
+            success: false,
+            error: `Invalid input${context ? ` for ${context}` : ''}: expected string`,
+        };
+    }
+    const trimmed = input.trim();
+    // Level 1: Direct parse
+    try {
+        const value = JSON.parse(trimmed);
+        return { success: true, value };
+    }
+    catch {
+        // Continue to fallbacks
+    }
+    // Level 2: Extract JSON object from text
+    const extracted = extractJsonObject(trimmed);
+    if (extracted) {
+        try {
+            const value = JSON.parse(extracted.json);
+            return { success: true, value };
+        }
+        catch {
+            // Continue to recovery
+        }
+    }
+    // Level 3: Attempt recovery (if enabled)
+    if (attemptRecovery) {
+        const recovered = attemptJsonRecovery(trimmed);
+        if (recovered) {
+            try {
+                const value = JSON.parse(recovered);
+                return { success: true, value, recovered: true };
+            }
+            catch {
+                // Recovery failed
+            }
+        }
+    }
+    return {
+        success: false,
+        error: `Failed to parse JSON${context ? ` for ${context}` : ''}: ${trimmed.slice(0, 50)}...`,
+    };
+}
+/**
+ * Attempt to recover malformed JSON.
+ *
+ * Handles common issues:
+ * - Trailing commas: `{"a": 1,}`
+ * - Single quotes: `{'a': 1}`
+ * - Unquoted keys: `{a: 1}`
+ * - Missing quotes on string values: `{"a": hello}`
+ */
+function attemptJsonRecovery(input) {
+    let fixed = input;
+    // Remove trailing commas before } or ]
+    fixed = fixed.replace(/,(\s*[}\]])/g, '$1');
+    // Replace single quotes with double quotes (simple cases only)
+    // This is intentionally conservative to avoid breaking strings with apostrophes
+    if (fixed.includes("'") && !fixed.includes('"')) {
+        fixed = fixed.replace(/'/g, '"');
+    }
+    // Try to quote unquoted keys: {foo: 1} -> {"foo": 1}
+    fixed = fixed.replace(/\{(\s*)([a-zA-Z_][a-zA-Z0-9_]*)(\s*):/g, '{$1"$2"$3:');
+    fixed = fixed.replace(/,(\s*)([a-zA-Z_][a-zA-Z0-9_]*)(\s*):/g, ',$1"$2"$3:');
+    // Only return if something changed
+    return fixed !== input ? fixed : null;
+}
+// =============================================================================
+// TOOL CALL EXTRACTION
+// =============================================================================
+/**
+ * Extract a tool call from an LLM response.
+ *
+ * Handles multiple formats:
+ * - Code block: ```json\n{"tool": "x", "input": {...}}\n```
+ * - Inline JSON: {"tool": "x", "input": {...}}
+ * - Nested inputs: {"tool": "x", "input": {"a": {"b": 1}}}
+ *
+ * @param response - The LLM response text
+ * @returns The extracted tool call, or null if not found
+ */
+export function extractToolCallJson(response) {
+    // Try code block first (most common format)
+    const codeBlockPatterns = [
+        /```json\s*([\s\S]*?)```/,
+        /```\s*([\s\S]*?)```/,
+    ];
+    for (const pattern of codeBlockPatterns) {
+        const match = response.match(pattern);
+        if (match) {
+            const result = parseToolCallObject(match[1]);
+            if (result)
+                return result;
+        }
+    }
+    // Try extracting raw JSON from the response
+    const extracted = extractJsonObject(response);
+    if (extracted) {
+        const result = parseToolCallObject(extracted.json);
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Parse a potential tool call object.
+ */
+function parseToolCallObject(text) {
+    const result = safeParseJson(text, {
+        context: 'tool call',
+    });
+    if (!result.success || !result.value)
+        return null;
+    const obj = result.value;
+    // Validate tool call structure
+    if (typeof obj.tool !== 'string')
+        return null;
+    return {
+        tool: obj.tool,
+        input: obj.input ?? {},
+    };
+}
+/**
+ * Extract multiple tool calls from a response.
+ */
+export function extractAllToolCalls(response) {
+    const results = [];
+    // Try code blocks first
+    const codeBlockPattern = /```(?:json)?\s*([\s\S]*?)```/g;
+    let match;
+    while ((match = codeBlockPattern.exec(response)) !== null) {
+        const result = parseToolCallObject(match[1]);
+        if (result)
+            results.push(result);
+    }
+    // If no code blocks found tool calls, try raw JSON objects
+    if (results.length === 0) {
+        const jsonObjects = extractAllJsonObjects(response);
+        for (const json of jsonObjects) {
+            const result = parseToolCallObject(json);
+            if (result)
+                results.push(result);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=json-utils.js.map

package/dist/src/tricks/json-utils.js.map

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

package/dist/src/tricks/kv-cache-context.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 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);
+ * ```
+ */
+/**
+ * Configuration for cache-aware context.
+ */
+export interface CacheAwareConfig {
+    /** Static prefix that never changes (maximizes cache hits) */
+    staticPrefix: string;
+    /** Points where cache can be safely broken */
+    cacheBreakpoints?: CacheBreakpoint[];
+    /** Whether to use deterministic JSON serialization */
+    deterministicJson?: boolean;
+    /** Whether to validate append-only constraint */
+    enforceAppendOnly?: boolean;
+}
+/**
+ * Cache breakpoint markers.
+ */
+export type CacheBreakpoint = 'system_end' | 'tools_end' | 'rules_end' | 'memory_end' | 'custom';
+/**
+ * Dynamic content that goes at the END of system prompt.
+ */
+export interface DynamicContent {
+    /** Current session ID */
+    sessionId?: string;
+    /** Current timestamp */
+    timestamp?: string;
+    /** Current mode */
+    mode?: string;
+    /** Any other dynamic values */
+    [key: string]: string | undefined;
+}
+/**
+ * Cache statistics.
+ */
+export interface CacheStats {
+    /** Estimated cacheable tokens */
+    cacheableTokens: number;
+    /** Estimated non-cacheable tokens */
+    nonCacheableTokens: number;
+    /** Cache efficiency ratio */
+    cacheRatio: number;
+    /** Estimated cost savings (0-1) */
+    estimatedSavings: number;
+}
+/**
+ * Message for context building.
+ */
+export interface ContextMessage {
+    id?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    timestamp?: string;
+}
+/**
+ * Events emitted by cache-aware context.
+ */
+export type CacheEvent = {
+    type: 'cache.breakpoint';
+    breakpoint: CacheBreakpoint;
+    position: number;
+} | {
+    type: 'cache.violation';
+    reason: string;
+    details: string;
+} | {
+    type: 'cache.stats';
+    stats: CacheStats;
+};
+export type CacheEventListener = (event: CacheEvent) => void;
+/**
+ * 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 declare function stableStringify(obj: unknown, indent?: number): string;
+/**
+ * Parse JSON and re-serialize deterministically.
+ * Useful for normalizing JSON strings from external sources.
+ */
+export declare function normalizeJson(jsonString: string): string;
+/**
+ * Manages context in a KV-cache-friendly way.
+ */
+export declare class CacheAwareContext {
+    private config;
+    private messageHashes;
+    private listeners;
+    private breakpointPositions;
+    constructor(config: CacheAwareConfig);
+    /**
+     * 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: {
+        rules?: string;
+        tools?: string;
+        memory?: string;
+        dynamic?: DynamicContent;
+    }): string;
+    /**
+     * Validate that messages follow append-only constraint.
+     * Returns violations if any past messages were modified.
+     */
+    validateAppendOnly(messages: ContextMessage[]): string[];
+    /**
+     * Serialize a message in a cache-friendly way.
+     */
+    serializeMessage(message: ContextMessage): string;
+    /**
+     * Serialize tool arguments deterministically.
+     */
+    serializeToolArgs(args: Record<string, unknown>): string;
+    /**
+     * Calculate cache statistics for a context.
+     */
+    calculateCacheStats(options: {
+        systemPrompt: string;
+        messages: ContextMessage[];
+        dynamicContentLength?: number;
+    }): CacheStats;
+    /**
+     * Get breakpoint positions.
+     */
+    getBreakpointPositions(): Map<CacheBreakpoint, number>;
+    /**
+     * Subscribe to cache events.
+     */
+    on(listener: CacheEventListener): () => void;
+    /**
+     * Reset message hashes (call when starting new session).
+     */
+    reset(): void;
+    private hashMessage;
+    private markBreakpoint;
+    private emit;
+}
+/**
+ * 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 declare function createCacheAwareContext(config: CacheAwareConfig): CacheAwareContext;
+/**
+ * Check if a system prompt has timestamps/dynamic content at the start.
+ * Returns warnings about cache-unfriendly patterns.
+ */
+export declare function analyzeCacheEfficiency(systemPrompt: string): {
+    warnings: string[];
+    suggestions: string[];
+};
+/**
+ * Format cache stats for display.
+ */
+export declare function formatCacheStats(stats: CacheStats): string;
+/**
+ * Create a cache-friendly timestamp that goes at the end.
+ */
+export declare function createEndTimestamp(): string;
+//# sourceMappingURL=kv-cache-context.d.ts.map

package/dist/src/tricks/kv-cache-context.d.ts.map

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