@dcyfr/ai 1.0.3 → 2.1.0

package/dist/ai/delegation/delegation-manager.js

@@ -0,0 +1,773 @@
+/**
+ * DCYFR Delegation Manager — Ralph Loop V2
+ * TLP:AMBER - Internal Use Only
+ *
+ * High-level orchestration layer on top of DelegationContractManager.
+ * Provides failure analysis (analyzeFailure) to categorise why a contract
+ * failed so that the Ralph Loop can rewrite the prompt and retry.
+ *
+ * @module delegation/delegation-manager
+ * @version 1.0.0
+ * @date 2026-02-26
+ *
+ * ## Failure Categories
+ *
+ * | Category               | Primary Signal                              |
+ * |------------------------|---------------------------------------------|
+ * | context_overflow       | "token limit" / "truncated" in logs         |
+ * | wrong_direction        | file changes outside declared task scope    |
+ * | missing_requirements   | "Cannot find name" TypeScript errors        |
+ * | stuck_on_complexity    | 0 commits after > 2 hours                   |
+ * | unknown                | no other signal detected                    |
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+/** Maximum retry attempts before human escalation */
+const MAX_RETRIES = 3;
+/** Default JSONL log path (relative to process.cwd) */
+const DEFAULT_REWRITE_LOG_PATH = 'data/rewrite-history.jsonl';
+/**
+ * Phrases that indicate the model hit a context/token limit.
+ * Matched case-insensitively against logs + error_output.
+ */
+const CONTEXT_OVERFLOW_SIGNALS = [
+    'token limit',
+    'truncated',
+    'context length exceeded',
+    'max_tokens',
+    'maximum context',
+    'context window',
+    'too many tokens',
+];
+/**
+ * Phrases that indicate missing TypeScript / module requirements.
+ * Matched case-insensitively against logs + error_output.
+ */
+const MISSING_REQUIREMENTS_SIGNALS = [
+    'Cannot find name',
+    'Cannot find module',
+    'has no exported member',
+    'Property .* does not exist',
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Public types
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Why a delegation contract failed.
+ *
+ * Used by Ralph Loop V2 to select the appropriate prompt-rewrite strategy.
+ */
+export var FailureCategory;
+(function (FailureCategory) {
+    /** Agent ran out of context window / token budget */
+    FailureCategory["CONTEXT_OVERFLOW"] = "context_overflow";
+    /** Agent made changes outside the declared task scope */
+    FailureCategory["WRONG_DIRECTION"] = "wrong_direction";
+    /** TypeScript / module requirements were not satisfied */
+    FailureCategory["MISSING_REQUIREMENTS"] = "missing_requirements";
+    /** Agent made no progress (zero commits) after the 2-hour threshold */
+    FailureCategory["STUCK_ON_COMPLEXITY"] = "stuck_on_complexity";
+    /** No specific signal detected — generic failure */
+    FailureCategory["UNKNOWN"] = "unknown";
+})(FailureCategory || (FailureCategory = {}));
+/**
+ * Number of memory entries to retrieve per category during rewriting.
+ * Kept small to avoid token bloat — the Ralph Loop prioritises precision.
+ */
+const MEMORY_QUERY_LIMIT = 3;
+/**
+ * Default context window size in tokens.
+ *
+ * 128,000 tokens covers GPT-4o, Claude 3.5 Sonnet, and most Gemini variants.
+ * Override per-task via `RewriteTask.contextWindowTokens` when targeting a
+ * model with a different window.
+ */
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 128_000;
+/**
+ * Fraction of the context window reserved for the prompt.
+ *
+ * The remaining 20% is left for the model's output tokens.  When a rewritten
+ * prompt would exceed this budget, older injected context blocks are
+ * summarised to a 1-sentence placeholder, while the last 3 blocks are kept
+ * verbatim.
+ */
+const PROMPT_BUDGET_RATIO = 0.8;
+/**
+ * Maximum number of injected context blocks to keep verbatim when trimming.
+ * Older blocks (lower index) are summarised to a 1-sentence placeholder.
+ */
+const VERBATIM_BLOCK_KEEP_COUNT = 3;
+/**
+ * Minimum successful retries a pattern must have before it is considered
+ * high-confidence and used to short-circuit the standard rewrite strategies.
+ */
+const HIGH_CONFIDENCE_MIN = 5;
+/**
+ * Isolated memory namespace for all Ralph Loop V2 prompt patterns.
+ * Using a dedicated namespace prevents pattern data from polluting regular
+ * agent workflow memories.
+ */
+const PATTERN_NAMESPACE = 'ralph-loop-v2-patterns';
+// ─────────────────────────────────────────────────────────────────────────────
+// DelegationManager
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * High-level delegation orchestration.
+ *
+ * Ralph Loop V2 entry point — wraps `DelegationContractManager` and adds the
+ * `analyzeFailure()` method used to categorise failures before prompt rewrite.
+ *
+ * @example
+ * ```typescript
+ * import { DelegationManager } from './delegation-manager.js';
+ *
+ * const dm = new DelegationManager();
+ * const analysis = dm.analyzeFailure({
+ *   contract: myContract,
+ *   logs: contractLogs,
+ *   changed_files: ['src/billing/invoice.ts', 'README.md'],
+ *   task_scope_paths: ['src/billing'],
+ *   commit_count: 0,
+ *   elapsed_ms: 3 * 60 * 60 * 1000,
+ * });
+ *
+ * // analysis.category === FailureCategory.STUCK_ON_COMPLEXITY
+ * ```
+ */
+export class DelegationManager {
+    // ------------------------------------------------------------------
+    // Private helpers
+    // ------------------------------------------------------------------
+    /**
+     * Returns `true` when any phrase in `needles` appears case-insensitively
+     * in `haystack`.
+     */
+    static containsAny(haystack, needles) {
+        const lower = haystack.toLowerCase();
+        return needles.some(n => lower.includes(n.toLowerCase()));
+    }
+    /**
+     * Checks whether `file` is outside ALL of `scopePaths`.
+     * A file is "in scope" when it starts with at least one scope prefix.
+     */
+    static isOutOfScope(file, scopePaths) {
+        return !scopePaths.some(prefix => file.startsWith(prefix));
+    }
+    // ------------------------------------------------------------------
+    // Public API
+    // ------------------------------------------------------------------
+    /**
+     * Analyses why a delegation contract failed and returns a structured
+     * `FailureAnalysis` for use by Ralph Loop V2 prompt rewriting.
+     *
+     * Detection priority (highest confidence first):
+     * 1. `context_overflow`  — keyword match in logs/error_output
+     * 2. `missing_requirements` — "Cannot find name" / module errors
+     * 3. `wrong_direction`   — out-of-scope file changes
+     * 4. `stuck_on_complexity` — zero commits > 2 h
+     * 5. `unknown`           — no signal found
+     *
+     * All four checks are run; the category with the highest confidence wins.
+     * Every detected signal is included in `analysis.signals` regardless of
+     * which category is selected, giving the rewriter a complete picture.
+     */
+    analyzeFailure(result) {
+        const signals = [];
+        const candidates = [];
+        const combinedText = `${result.logs ?? ''} ${result.error_output ?? ''}`.trim();
+        // ── 1. Context overflow ────────────────────────────────────────────────
+        const overflowMatches = CONTEXT_OVERFLOW_SIGNALS.filter(phrase => combinedText.toLowerCase().includes(phrase.toLowerCase()));
+        if (overflowMatches.length > 0) {
+            for (const phrase of overflowMatches) {
+                signals.push(`context_overflow signal: "${phrase}" found in logs`);
+            }
+            candidates.push({ category: FailureCategory.CONTEXT_OVERFLOW, confidence: 1.0 });
+        }
+        // ── 2. Missing requirements ────────────────────────────────────────────
+        const missingMatches = MISSING_REQUIREMENTS_SIGNALS.filter(phrase => DelegationManager.containsAny(combinedText, [phrase]));
+        if (missingMatches.length > 0) {
+            for (const phrase of missingMatches) {
+                signals.push(`missing_requirements signal: "${phrase}" found in output`);
+            }
+            candidates.push({ category: FailureCategory.MISSING_REQUIREMENTS, confidence: 1.0 });
+        }
+        // ── 3. Wrong direction ─────────────────────────────────────────────────
+        const changedFiles = result.changed_files ?? [];
+        const scopePaths = result.task_scope_paths ?? [];
+        if (changedFiles.length > 0 && scopePaths.length > 0) {
+            const outOfScope = changedFiles.filter(f => DelegationManager.isOutOfScope(f, scopePaths));
+            if (outOfScope.length > 0) {
+                for (const f of outOfScope) {
+                    signals.push(`wrong_direction signal: "${f}" is outside task scope (${scopePaths.join(', ')})`);
+                }
+                const confidence = outOfScope.length / changedFiles.length;
+                candidates.push({ category: FailureCategory.WRONG_DIRECTION, confidence });
+            }
+        }
+        // ── 4. Stuck on complexity ────────────────────────────────────────────
+        const commitCount = result.commit_count ?? -1;
+        const elapsedMs = result.elapsed_ms ?? 0;
+        if (commitCount === 0 && elapsedMs > TWO_HOURS_MS) {
+            const hoursElapsed = (elapsedMs / (60 * 60 * 1000)).toFixed(1);
+            signals.push(`stuck_on_complexity signal: 0 commits after ${hoursElapsed}h (threshold: 2h)`);
+            candidates.push({ category: FailureCategory.STUCK_ON_COMPLEXITY, confidence: 1.0 });
+        }
+        // ── 5. Select winner ─────────────────────────────────────────────────
+        if (candidates.length === 0) {
+            return {
+                category: FailureCategory.UNKNOWN,
+                confidence: 0.3,
+                signals: ['no specific failure signal detected'],
+                contract_id: result.contract.contract_id,
+            };
+        }
+        // Sort descending by confidence; stable sort keeps insertion order on ties
+        const sorted = candidates.slice().sort((a, b) => b.confidence - a.confidence);
+        const winner = sorted[0];
+        return {
+            category: winner.category,
+            confidence: winner.confidence,
+            signals,
+            contract_id: result.contract.contract_id,
+        };
+    }
+    // ------------------------------------------------------------------
+    // rewritePrompt
+    // ------------------------------------------------------------------
+    /**
+     * Rewrites a task prompt based on the failure category detected by
+     * `analyzeFailure()`, optionally enriching it with context retrieved
+     * from the memory layer.
+     *
+     * Strategy per category:
+     * - `context_overflow`     — scope the prompt to the 3 most relevant files
+     * - `wrong_direction`      — prepend customer requirement quotes from memory
+     * - `missing_requirements` — append type definitions from memory
+     * - `stuck_on_complexity`  — decompose the task into 2–3 sub-tasks
+     * - `unknown`              — return the original prompt unchanged
+     *
+     * @param task            - Task information including the original prompt
+     * @param failureCategory - Category identified by `analyzeFailure()`
+     * @param memory          - Memory layer instance for context lookups
+     * @returns               Rewritten prompt + audit log of applied context
+     */
+    async rewritePrompt(task, failureCategory, memory) {
+        let raw = null;
+        // ── Pattern shortcut — check for a high-confidence learned pattern first ───
+        // Skip pattern lookup for UNKNOWN: no strategy exists so there can be no
+        // learned pattern, and the memory round-trip would produce no useful result.
+        if (failureCategory !== FailureCategory.UNKNOWN) {
+            const pattern = await this.queryHighConfidencePattern(task.agentId ?? task.taskId, failureCategory, memory);
+            if (pattern !== null) {
+                const rewrittenPrompt = pattern.effectiveRewrite
+                    ? `HIGH CONFIDENCE PATTERN (${pattern.successCount} prior successes — using learned strategy):\n` +
+                        `${pattern.effectiveRewrite}\n\n` +
+                        task.originalPrompt
+                    : task.originalPrompt;
+                raw = {
+                    rewrittenPrompt,
+                    strategy: failureCategory,
+                    appliedContext: [
+                        `pattern shortcut: using high-confidence pattern for ${failureCategory} ` +
+                            `(capability=${pattern.capability}, successCount=${pattern.successCount}, ` +
+                            `lastSuccessAt=${pattern.lastSuccessAt})`,
+                    ],
+                };
+            }
+        }
+        if (raw === null) {
+            switch (failureCategory) {
+                case FailureCategory.CONTEXT_OVERFLOW:
+                    raw = await this.rewriteForContextOverflow(task, memory);
+                    break;
+                case FailureCategory.WRONG_DIRECTION:
+                    raw = await this.rewriteForWrongDirection(task, memory);
+                    break;
+                case FailureCategory.MISSING_REQUIREMENTS:
+                    raw = await this.rewriteForMissingRequirements(task, memory);
+                    break;
+                case FailureCategory.STUCK_ON_COMPLEXITY:
+                    raw = await this.rewriteForStuckOnComplexity(task, memory);
+                    break;
+                default:
+                    raw = {
+                        rewrittenPrompt: task.originalPrompt,
+                        strategy: FailureCategory.UNKNOWN,
+                        appliedContext: ['no rewrite strategy for unknown category — prompt returned unchanged'],
+                    };
+            }
+        }
+        return this.applyTokenBudget(raw, task);
+    }
+    // ------------------------------------------------------------------
+    // Private rewrite strategies
+    // ------------------------------------------------------------------
+    /**
+     * Trim scope: query memory for the most relevant 3 files to this task
+     * and rewrite the prompt to focus only on those files.
+     */
+    async rewriteForContextOverflow(task, memory) {
+        const appliedContext = [];
+        const memResults = await memory.searchAgentMemories(task.agentId ?? task.taskId, `relevant files for ${task.taskId}`, MEMORY_QUERY_LIMIT);
+        const relevantFiles = memResults.map(r => r.content);
+        appliedContext.push(`context_overflow: queried memory for relevant files (found ${relevantFiles.length})`);
+        // Also honour explicit changedFiles — intersection with scope paths
+        const scopedFiles = (task.changedFiles ?? [])
+            .filter(f => (task.taskScopePaths ?? []).some(p => f.startsWith(p)))
+            .slice(0, MEMORY_QUERY_LIMIT);
+        const allFiles = [...new Set([...relevantFiles, ...scopedFiles])].slice(0, MEMORY_QUERY_LIMIT);
+        let rewrittenPrompt = task.originalPrompt;
+        if (allFiles.length > 0) {
+            const fileList = allFiles.map(f => `- ${f}`).join('\n');
+            rewrittenPrompt =
+                `SCOPE RESTRICTION (context budget exceeded on previous attempt):\n` +
+                    `Focus ONLY on these ${allFiles.length} file(s):\n${fileList}\n\n` +
+                    task.originalPrompt;
+            appliedContext.push(`context_overflow: scoped prompt to files: ${allFiles.join(', ')}`);
+        }
+        else {
+            appliedContext.push('context_overflow: no files found in memory — trimming strategy adds scope header only');
+            rewrittenPrompt =
+                `SCOPE RESTRICTION (context budget exceeded on previous attempt):\n` +
+                    `Complete only the minimal change needed for this task.\n\n` +
+                    task.originalPrompt;
+        }
+        return { rewrittenPrompt, strategy: FailureCategory.CONTEXT_OVERFLOW, appliedContext };
+    }
+    /**
+     * Add customer requirement quotes: query memory for meeting notes / customer
+     * quotes relevant to the task and prepend them as alignment context.
+     */
+    async rewriteForWrongDirection(task, memory) {
+        const appliedContext = [];
+        const memResults = await memory.searchAgentMemories(task.agentId ?? task.taskId, `customer requirements meeting notes ${task.taskId}`, MEMORY_QUERY_LIMIT);
+        appliedContext.push(`wrong_direction: queried memory for customer quotes (found ${memResults.length})`);
+        let rewrittenPrompt = task.originalPrompt;
+        if (memResults.length > 0) {
+            const quotes = memResults
+                .map((r, i) => `[Requirement ${i + 1}] ${r.content}`)
+                .join('\n\n');
+            rewrittenPrompt =
+                `ALIGNMENT CONTEXT (previous attempt went out of scope):\n` +
+                    `These are the customer requirements this task must satisfy:\n\n` +
+                    `${quotes}\n\n` +
+                    `Stay strictly within the following scope: ${(task.taskScopePaths ?? []).join(', ')}\n\n` +
+                    task.originalPrompt;
+            for (const r of memResults) {
+                appliedContext.push(`wrong_direction: injected customer quote (relevance ${r.relevance.toFixed(2)}): "${r.content.slice(0, 80)}..."`);
+            }
+        }
+        else {
+            const scopeNote = (task.taskScopePaths ?? []).length > 0
+                ? `Stay strictly within: ${task.taskScopePaths.join(', ')}`
+                : 'Stay strictly within the originally declared task scope.';
+            rewrittenPrompt =
+                `SCOPE REMINDER (previous attempt went out of scope):\n` +
+                    `${scopeNote}\n\n` +
+                    task.originalPrompt;
+            appliedContext.push('wrong_direction: no memory quotes found — added scope reminder header');
+        }
+        return { rewrittenPrompt, strategy: FailureCategory.WRONG_DIRECTION, appliedContext };
+    }
+    /**
+     * Append type definitions: query memory for type definitions relevant to
+     * the task and append them as explicit type context.
+     */
+    async rewriteForMissingRequirements(task, memory) {
+        const appliedContext = [];
+        const memResults = await memory.searchAgentMemories(task.agentId ?? task.taskId, `TypeScript type definitions interfaces for ${task.taskId}`, MEMORY_QUERY_LIMIT);
+        appliedContext.push(`missing_requirements: queried memory for type definitions (found ${memResults.length})`);
+        let rewrittenPrompt = task.originalPrompt;
+        if (memResults.length > 0) {
+            const typeDefs = memResults
+                .map((r, i) => `// Type Definition ${i + 1}\n${r.content}`)
+                .join('\n\n');
+            rewrittenPrompt =
+                task.originalPrompt +
+                    `\n\nREQUIRED TYPE DEFINITIONS (use exactly as shown):\n` +
+                    `\`\`\`typescript\n${typeDefs}\n\`\`\``;
+            for (const r of memResults) {
+                appliedContext.push(`missing_requirements: appended type def (relevance ${r.relevance.toFixed(2)})`);
+            }
+        }
+        else {
+            rewrittenPrompt =
+                task.originalPrompt +
+                    `\n\nNOTE: Ensure all required TypeScript types and module imports are ` +
+                    `declared before use. Run \`tsc --noEmit\` and fix all type errors before submitting.`;
+            appliedContext.push('missing_requirements: no type defs in memory — added tsc reminder');
+        }
+        return { rewrittenPrompt, strategy: FailureCategory.MISSING_REQUIREMENTS, appliedContext };
+    }
+    /**
+     * Decompose into sub-tasks: break the original prompt into 2–3 focused
+     * sub-tasks so the agent can make incremental forward progress.
+     */
+    async rewriteForStuckOnComplexity(task, memory) {
+        const appliedContext = [];
+        // Query memory for any prior decomposition patterns for this task type
+        const memResults = await memory.searchAgentMemories(task.agentId ?? task.taskId, `task decomposition sub-tasks breakdown ${task.taskId}`, MEMORY_QUERY_LIMIT);
+        appliedContext.push(`stuck_on_complexity: queried memory for decomposition patterns (found ${memResults.length})`);
+        let subTaskBlock;
+        if (memResults.length > 0) {
+            // Use memory-sourced decomposition
+            subTaskBlock = memResults
+                .map((r, i) => `Sub-task ${i + 1}: ${r.content}`)
+                .join('\n\n');
+            appliedContext.push('stuck_on_complexity: using memory-sourced sub-task decomposition');
+        }
+        else {
+            // Heuristic decomposition — split the original prompt into 3 phases
+            subTaskBlock =
+                `Sub-task 1: Write the minimal implementation skeleton (types + function signatures only; no logic yet)\n` +
+                    `Sub-task 2: Implement the core logic and add unit tests\n` +
+                    `Sub-task 3: Wire up integration points, fix type errors, and verify with \`npm run test\``;
+            appliedContext.push('stuck_on_complexity: heuristic 3-phase decomposition applied');
+        }
+        const rewrittenPrompt = `TASK DECOMPOSITION (agent was stuck — complete one sub-task at a time and commit after each):\n\n` +
+            `${subTaskBlock}\n\n` +
+            `Original task for reference:\n${task.originalPrompt}`;
+        return { rewrittenPrompt, strategy: FailureCategory.STUCK_ON_COMPLEXITY, appliedContext };
+    }
+    // ------------------------------------------------------------------
+    // Pattern learning
+    // ------------------------------------------------------------------
+    /**
+     * Persist a rewrite pattern to the memory layer after a successful retry.
+     *
+     * Call this from `runWithRetry` callbacks (or from application code) when a
+     * rewritten prompt leads to a successful contract execution.  Each stored
+     * pattern carries a `successCount`; once a pattern reaches
+     * `HIGH_CONFIDENCE_MIN` (5) successes it will be used as a shortcut by
+     * `rewritePrompt()`.
+     *
+     * @param options - Pattern metadata including capability, category, and count
+     * @param memory  - Memory layer instance to persist the pattern into
+     * @returns The memory ID assigned by the provider
+     *
+     * @example
+     * ```typescript
+     * await dm.learnPattern(
+     *   {
+     *     agentId: 'my-agent',
+     *     taskId: 'task-auth',
+     *     capability: 'code_generation',
+     *     failureCategory: FailureCategory.CONTEXT_OVERFLOW,
+     *     contextType: 'scope_restriction',
+     *     successCount: existingPattern ? existingPattern.successCount + 1 : 1,
+     *     effectiveRewrite: rewriteResult.rewrittenPrompt,
+     *   },
+     *   memory,
+     * );
+     * ```
+     */
+    async learnPattern(options, memory) {
+        const pattern = {
+            capability: options.capability,
+            failureCategory: options.failureCategory,
+            contextType: options.contextType,
+            successCount: options.successCount,
+            lastSuccessAt: new Date().toISOString(),
+            effectiveRewrite: options.effectiveRewrite,
+        };
+        const sessionId = `${options.capability}__${options.failureCategory}__${options.taskId}`;
+        return memory.addAgentMemory(PATTERN_NAMESPACE, sessionId, pattern);
+    }
+    /**
+     * Queries the memory layer for a high-confidence pattern matching the given
+     * failure category and agent.
+     *
+     * A pattern is considered high-confidence when `successCount >=
+     * HIGH_CONFIDENCE_MIN` (5).  The method returns the best matching
+     * high-confidence pattern or `null` if none is found.
+     *
+     * @param agentId         - Agent namespace for the pattern lookup
+     * @param failureCategory - Category to search for
+     * @param memory          - Memory layer instance
+     * @returns Highest-successCount high-confidence pattern, or `null`
+     */
+    async queryHighConfidencePattern(agentId, failureCategory, memory) {
+        let results;
+        try {
+            results = await memory.searchAgentMemories(PATTERN_NAMESPACE, `${failureCategory} ${agentId}`, HIGH_CONFIDENCE_MIN);
+        }
+        catch {
+            // Memory lookup failures must never break the rewrite pipeline
+            return null;
+        }
+        const patterns = [];
+        for (const r of results) {
+            // Primary path: structured data via metadata.state (dcyfr-memory impl)
+            const state = r.metadata?.['state'];
+            if (state?.failureCategory === failureCategory && typeof state.successCount === 'number') {
+                patterns.push(state);
+                continue;
+            }
+            // Fallback: try JSON.parse on content (some providers serialise inline)
+            try {
+                const parsed = JSON.parse(r.content);
+                if (parsed?.failureCategory === failureCategory && typeof parsed.successCount === 'number') {
+                    patterns.push(parsed);
+                }
+            }
+            catch {
+                // Not JSON — skip
+            }
+        }
+        const highConfidence = patterns.filter(p => p.successCount >= HIGH_CONFIDENCE_MIN);
+        if (highConfidence.length === 0)
+            return null;
+        // Return the pattern with the highest successCount
+        return highConfidence.reduce((best, p) => p.successCount > best.successCount ? p : best);
+    }
+    // ------------------------------------------------------------------
+    // Token budget management
+    // ------------------------------------------------------------------
+    /**
+     * Estimates the token count of a string using the 1-token ≈ 4-characters
+     * heuristic (industry standard for English prose and TypeScript code).
+     *
+     * The result is intentionally an over-estimate for safety — it is slightly
+     * higher than exact tiktoken counts on average, which means the budget cap
+     * will trigger a little early rather than too late.
+     *
+     * @param text - The string to estimate tokens for
+     * @returns Estimated token count (always ≥ 1)
+     */
+    estimateTokens(text) {
+        return Math.max(1, Math.ceil(text.length / 4));
+    }
+    /**
+     * Summarises older injected context blocks to a 1-sentence placeholder,
+     * keeping the `keepVerbatim` most-recent blocks intact.
+     *
+     * Blocks are delimited by double newlines.  If there are `keepVerbatim` or
+     * fewer blocks the section is returned unmodified.
+     *
+     * @param section      - The injected section text (header or footer)
+     * @param keepVerbatim - Number of recent blocks to preserve verbatim
+     * @returns The (possibly summarised) section text
+     */
+    summarizeInjectedSection(section, keepVerbatim) {
+        const trimmed = section.trim();
+        if (!trimmed)
+            return section;
+        const blocks = section.split(/\n\n+/);
+        const nonEmpty = blocks.filter(b => b.trim());
+        if (nonEmpty.length <= keepVerbatim)
+            return section;
+        const olderCount = nonEmpty.length - keepVerbatim;
+        const keptBlocks = nonEmpty.slice(olderCount);
+        const summary = `[${olderCount} earlier context block(s) summarized to save token budget — ` +
+            `see rewrite log for full content]`;
+        return summary + '\n\n' + keptBlocks.join('\n\n');
+    }
+    /**
+     * Applies the token budget cap to a raw `RewriteResult`.
+     *
+     * 1. Estimates `originalTokens`, `addedTokens`, and `finalTokens`.
+     * 2. If `finalTokens > budgetTokens` (80% of context window), trims the
+     *    injected additions by summarising older context blocks while keeping
+     *    the last `VERBATIM_BLOCK_KEEP_COUNT` (3) blocks verbatim.
+     * 3. The original prompt is always preserved verbatim.
+     * 4. Appends token budget telemetry to `appliedContext`.
+     *
+     * @param result - Raw rewrite result from a strategy or pattern shortcut
+     * @param task   - Original task (used for context window override + prompt)
+     * @returns Updated result with `tokenBudget` populated
+     */
+    applyTokenBudget(result, task) {
+        const contextWindowTokens = task.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+        const budgetTokens = Math.floor(contextWindowTokens * PROMPT_BUDGET_RATIO);
+        const originalTokens = this.estimateTokens(task.originalPrompt);
+        let { rewrittenPrompt } = result;
+        const rawTokens = this.estimateTokens(rewrittenPrompt);
+        const wasOverBudget = rawTokens > budgetTokens;
+        if (wasOverBudget) {
+            // Locate the original prompt within the rewritten output so we can split
+            // it into header (prepended context) and footer (appended context).
+            const origIdx = rewrittenPrompt.indexOf(task.originalPrompt);
+            if (origIdx !== -1) {
+                const header = rewrittenPrompt.slice(0, origIdx);
+                const footer = rewrittenPrompt.slice(origIdx + task.originalPrompt.length);
+                const trimmedHeader = this.summarizeInjectedSection(header, VERBATIM_BLOCK_KEEP_COUNT);
+                const trimmedFooter = this.summarizeInjectedSection(footer, VERBATIM_BLOCK_KEEP_COUNT);
+                rewrittenPrompt = trimmedHeader + task.originalPrompt + trimmedFooter;
+            }
+        }
+        const finalTokens = this.estimateTokens(rewrittenPrompt);
+        const addedTokens = Math.max(0, finalTokens - originalTokens);
+        const tokenBudget = {
+            originalTokens,
+            addedTokens,
+            finalTokens,
+            budgetTokens,
+            overBudget: wasOverBudget,
+        };
+        const appliedContext = [...result.appliedContext];
+        if (wasOverBudget) {
+            appliedContext.push(`token-budget: over-budget — trimmed injected blocks ` +
+                `(raw=${rawTokens}, final=${finalTokens}, budget=${budgetTokens} tokens)`);
+        }
+        appliedContext.push(`token-budget: originalTokens=${originalTokens}, addedTokens=${addedTokens}, ` +
+            `finalTokens=${finalTokens}, budgetTokens=${budgetTokens}`);
+        return { ...result, rewrittenPrompt, appliedContext, tokenBudget };
+    }
+    // ------------------------------------------------------------------
+    // runWithRetry — Ralph Loop V2 orchestration
+    // ------------------------------------------------------------------
+    /**
+     * Ralph Loop V2 retry orchestration.
+     *
+     * Runs `executeAttempt` up to `maxRetries` times.  After each failure:
+     * 1. Calls `analyzeFailure()` to categorise the problem.
+     * 2. Calls `rewritePrompt()` to produce an improved prompt.
+     * 3. Logs the rewrite to `data/rewrite-history.jsonl`.
+     *
+     * If the maximum number of attempts is reached without success, an
+     * escalation notification is sent via Telegram (requires
+     * `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` env vars).
+     *
+     * @example
+     * ```typescript
+     * const result = await dm.runWithRetry({
+     *   initialPrompt: 'Implement auth module.',
+     *   taskId: 'task-auth',
+     *   memory,
+     *   executeAttempt: async (prompt) => {
+     *     // ... run agent, return ContractResult
+     *   },
+     *   isSuccess: (r) => (r.commit_count ?? 0) > 0 && !r.error_output,
+     * });
+     * ```
+     */
+    async runWithRetry(options) {
+        const maxRetries = options.maxRetries ?? MAX_RETRIES;
+        const logPath = options.logPath === null ? null : (options.logPath ?? DEFAULT_REWRITE_LOG_PATH);
+        const attempts = [];
+        let currentPrompt = options.initialPrompt;
+        let escalated = false;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            const result = await options.executeAttempt(currentPrompt, attempt);
+            if (options.isSuccess(result)) {
+                attempts.push({ attempt, prompt: currentPrompt, result });
+                return {
+                    success: true,
+                    attempts,
+                    finalResult: result,
+                    totalAttempts: attempt,
+                    escalated: false,
+                };
+            }
+            const analysis = this.analyzeFailure(result);
+            if (attempt === maxRetries) {
+                // Final attempt failed — escalate before returning
+                attempts.push({ attempt, prompt: currentPrompt, result, analysis });
+                escalated = await this.sendTelegramEscalation(options.taskId, maxRetries, analysis);
+                break;
+            }
+            const rewriteTask = {
+                originalPrompt: currentPrompt,
+                taskId: options.taskId,
+                agentId: options.agentId,
+                changedFiles: result.changed_files,
+                taskScopePaths: options.taskScopePaths ?? result.task_scope_paths,
+            };
+            const rewrite = await this.rewritePrompt(rewriteTask, analysis.category, options.memory);
+            if (logPath !== null) {
+                await this.appendRewriteLog(logPath, {
+                    taskId: options.taskId,
+                    contractId: result.contract.contract_id,
+                    attempt,
+                    failureCategory: analysis.category,
+                    confidence: analysis.confidence,
+                    signals: analysis.signals,
+                    promptBeforeLength: currentPrompt.length,
+                    promptAfterLength: rewrite.rewrittenPrompt.length,
+                    appliedContext: rewrite.appliedContext,
+                });
+            }
+            attempts.push({ attempt, prompt: currentPrompt, result, analysis, rewrite });
+            currentPrompt = rewrite.rewrittenPrompt;
+        }
+        return {
+            success: false,
+            attempts,
+            finalResult: attempts[attempts.length - 1].result,
+            totalAttempts: attempts.length,
+            escalated,
+        };
+    }
+    // ------------------------------------------------------------------
+    // Private helpers — escalation + logging
+    // ------------------------------------------------------------------
+    /**
+     * Sends a Telegram message to notify humans of a triple-failure escalation.
+     *
+     * Reads `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from `process.env`.
+     * When either is missing, logs a warning and returns `false` (silent skip).
+     *
+     * @returns `true` if the message was sent, `false` otherwise.
+     */
+    async sendTelegramEscalation(taskId, maxRetries, analysis) {
+        const token = process.env['TELEGRAM_BOT_TOKEN'];
+        const chatId = process.env['TELEGRAM_CHAT_ID'];
+        if (!token || !chatId) {
+            // Not configured — skip silently (warn in case someone is watching)
+            process.stderr.write(`[DelegationManager] Telegram escalation skipped: ` +
+                `TELEGRAM_BOT_TOKEN or TELEGRAM_CHAT_ID not set.\n`);
+            return false;
+        }
+        const message = `🚨 *Ralph Loop V2 Escalation*\n` +
+            `Task *${taskId}* failed after *${maxRetries}* attempt(s).\n` +
+            `Category: \`${analysis.category}\` (confidence: ${(analysis.confidence * 100).toFixed(0)}%)\n` +
+            `Signals:\n${analysis.signals.map(s => `• ${s}`).join('\n')}\n` +
+            `Contract: \`${analysis.contract_id}\`\n` +
+            `Requires human review.`;
+        const url = `https://api.telegram.org/bot${token}/sendMessage`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ chat_id: chatId, text: message, parse_mode: 'Markdown' }),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                process.stderr.write(`[DelegationManager] Telegram API error ${response.status}: ${body}\n`);
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            process.stderr.write(`[DelegationManager] Telegram fetch failed: ${String(err)}\n`);
+            return false;
+        }
+    }
+    /**
+     * Appends one JSONL entry to the rewrite-history log.
+     * Creates the parent directory if it doesn't exist.
+     */
+    async appendRewriteLog(logPath, entry) {
+        const record = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            ...entry,
+        });
+        try {
+            await mkdir(dirname(logPath), { recursive: true });
+            await appendFile(logPath, `${record}\n`, 'utf8');
+        }
+        catch (err) {
+            // Non-fatal — log errors should never break the retry loop
+            process.stderr.write(`[DelegationManager] Failed to write rewrite log: ${String(err)}\n`);
+        }
+    }
+}
+/**
+ * Default singleton — suitable for non-test usage.
+ */
+export const delegationManager = new DelegationManager();
+//# sourceMappingURL=delegation-manager.js.map