attocode 0.2.3 → 0.2.5

package/dist/src/integrations/budget/dynamic-budget.js

@@ -0,0 +1,151 @@
+/**
+ * Dynamic Budget Rebalancing
+ *
+ * Extends SharedBudgetPool with dynamic rebalancing that prevents
+ * starvation when spawning subagents sequentially.
+ *
+ * Key features:
+ * - setExpectedChildren(count) for upfront capacity planning
+ * - Sequential spawn cap: never take >60% of remaining budget
+ * - Rebalance on child completion (return unused budget to pool)
+ * - Priority-based allocation (critical children get more)
+ */
+import { SharedBudgetPool } from './budget-pool.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const PRIORITY_MULTIPLIERS = {
+    low: 0.5,
+    normal: 1.0,
+    high: 1.5,
+    critical: 2.0,
+};
+const DEFAULT_DYNAMIC_CONFIG = {
+    maxRemainingRatio: 0.6,
+    minPerExpectedChild: 10000,
+    autoRebalance: true,
+};
+// =============================================================================
+// DYNAMIC BUDGET POOL
+// =============================================================================
+export class DynamicBudgetPool extends SharedBudgetPool {
+    dynamicConfig;
+    expectedChildren = 0;
+    spawnedCount = 0;
+    completedCount = 0;
+    childPriorities = new Map();
+    constructor(config) {
+        super(config);
+        this.dynamicConfig = {
+            ...config,
+            maxRemainingRatio: config.maxRemainingRatio ?? DEFAULT_DYNAMIC_CONFIG.maxRemainingRatio,
+            minPerExpectedChild: config.minPerExpectedChild ?? DEFAULT_DYNAMIC_CONFIG.minPerExpectedChild,
+            autoRebalance: config.autoRebalance ?? DEFAULT_DYNAMIC_CONFIG.autoRebalance,
+        };
+    }
+    /**
+     * Set the expected number of children for capacity planning.
+     * This adjusts maxPerChild to ensure fair distribution.
+     */
+    setExpectedChildren(count) {
+        this.expectedChildren = count;
+        this.updateMaxPerChild();
+    }
+    /**
+     * Set priority for a child agent.
+     */
+    setChildPriority(priority) {
+        this.childPriorities.set(priority.childId, priority);
+    }
+    /**
+     * Reserve with dynamic capacity planning.
+     * Respects expected children and remaining ratio cap.
+     */
+    reserveDynamic(childId, priority) {
+        // Set priority if provided
+        if (priority) {
+            this.setChildPriority({ childId, priority });
+        }
+        // Calculate dynamic max for this child
+        const stats = this.getStats();
+        const remaining = stats.tokensRemaining;
+        if (remaining <= 0)
+            return null;
+        // Cap at maxRemainingRatio of remaining budget
+        const ratioCap = Math.floor(remaining * this.dynamicConfig.maxRemainingRatio);
+        // Reserve for expected future children
+        const unreservedChildren = Math.max(0, this.expectedChildren - this.spawnedCount - 1);
+        const reserveForFuture = unreservedChildren * this.dynamicConfig.minPerExpectedChild;
+        const afterReserve = Math.max(0, remaining - reserveForFuture);
+        // Apply priority multiplier
+        const priorityLevel = this.childPriorities.get(childId)?.priority ?? 'normal';
+        const multiplier = PRIORITY_MULTIPLIERS[priorityLevel] ?? 1.0;
+        const priorityAdjusted = Math.floor(afterReserve * multiplier / Math.max(1, unreservedChildren + 1));
+        // Final allocation: min of all caps
+        const dynamicMax = Math.min(ratioCap, afterReserve, Math.max(priorityAdjusted, this.dynamicConfig.minPerExpectedChild));
+        // Temporarily set max per child for this reservation
+        this.setMaxPerChild(dynamicMax);
+        const allocation = this.reserve(childId);
+        this.resetMaxPerChild();
+        if (allocation) {
+            this.spawnedCount++;
+        }
+        return allocation;
+    }
+    /**
+     * Release with optional auto-rebalancing.
+     */
+    releaseDynamic(childId) {
+        this.release(childId);
+        this.completedCount++;
+        this.childPriorities.delete(childId);
+    }
+    /**
+     * Get enhanced stats including dynamic info.
+     */
+    getDynamicStats() {
+        const base = this.getStats();
+        const pending = this.spawnedCount - this.completedCount;
+        return {
+            ...base,
+            expectedChildren: this.expectedChildren,
+            spawnedCount: this.spawnedCount,
+            completedCount: this.completedCount,
+            pendingCount: pending,
+            avgPerChild: this.spawnedCount > 0
+                ? Math.floor(base.tokensUsed / this.spawnedCount)
+                : 0,
+        };
+    }
+    // ===========================================================================
+    // INTERNAL
+    // ===========================================================================
+    updateMaxPerChild() {
+        if (this.expectedChildren <= 0)
+            return;
+        const stats = this.getStats();
+        const remaining = stats.tokensRemaining;
+        const unreserved = Math.max(1, this.expectedChildren - this.spawnedCount);
+        // Fair share: remaining / unreserved children, capped by ratio
+        const fairShare = Math.floor(remaining / unreserved);
+        const ratioCap = Math.floor(remaining * this.dynamicConfig.maxRemainingRatio);
+        this.setMaxPerChild(Math.min(fairShare, ratioCap));
+    }
+}
+/**
+ * Create a dynamic budget pool from a parent's budget.
+ */
+export function createDynamicBudgetPool(parentBudgetTokens, parentReserveRatio = 0.25, config) {
+    const parentReserve = Math.floor(parentBudgetTokens * parentReserveRatio);
+    const poolTokens = parentBudgetTokens - parentReserve;
+    return new DynamicBudgetPool({
+        totalTokens: poolTokens,
+        maxPerChild: Math.min(config?.maxPerChild ?? 100000, poolTokens),
+        totalCost: 0.50,
+        maxCostPerChild: 0.25,
+        maxRemainingRatio: config?.maxRemainingRatio ?? 0.6,
+        minPerExpectedChild: config?.minPerExpectedChild ?? 10000,
+        autoRebalance: config?.autoRebalance ?? true,
+    });
+}
+//# sourceMappingURL=dynamic-budget.js.map

package/dist/src/integrations/budget/dynamic-budget.js.map

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

package/dist/src/integrations/budget/economics.d.ts

@@ -0,0 +1,435 @@
+/**
+ * Lesson 25: Execution Economics System
+ *
+ * Replaces hard-coded iteration limits with intelligent budget management:
+ * - Token budgets (primary constraint)
+ * - Cost budgets (maps to real API costs)
+ * - Time budgets (wall-clock limits)
+ * - Progress detection (stuck vs productive)
+ * - Adaptive limits with extension requests
+ *
+ * Phase 3b: Core manager + presets. Loop detection and phase tracking
+ * are extracted into loop-detector.ts and phase-tracker.ts respectively.
+ */
+import type { SharedEconomicsState } from '../../shared/shared-economics-state.js';
+export { computeToolFingerprint, extractBashResult, extractBashFileTarget, LoopDetector, type RecentToolCall, } from './loop-detector.js';
+export { PhaseTracker } from './phase-tracker.js';
+/**
+ * Configurable economics thresholds for tuning doom loop and exploration detection.
+ * Passed via ExecutionBudget.tuning; defaults are used when omitted.
+ */
+export interface EconomicsTuning {
+    /** Threshold for exact doom loop detection (default: 3) */
+    doomLoopThreshold?: number;
+    /** Threshold for fuzzy doom loop detection (default: doomLoopThreshold + 1) */
+    doomLoopFuzzyThreshold?: number;
+    /** Unique files read before exploration saturation warning (default: 10) */
+    explorationFileThreshold?: number;
+    /** Iterations in exploration with diminishing returns before warning (default: 5) */
+    explorationIterThreshold?: number;
+    /** Iterations with zero tool calls before forceTextOnly (default: 5) */
+    zeroProgressThreshold?: number;
+    /** Iteration checkpoint for adaptive budget reduction (default: 5) */
+    progressCheckpoint?: number;
+    /** Max tool calls to execute from a single LLM response (default: 25) */
+    maxToolCallsPerResponse?: number;
+    /** Max consecutive tool failures before circuit breaker trips (default: 5) */
+    circuitBreakerFailureThreshold?: number;
+}
+/**
+ * Execution budget configuration.
+ */
+export interface ExecutionBudget {
+    /** Enforcement policy for hard token/cost/duration limits. */
+    enforcementMode?: 'strict' | 'doomloop_only';
+    maxTokens: number;
+    maxCost: number;
+    maxDuration: number;
+    softTokenLimit: number;
+    softCostLimit: number;
+    softDurationLimit: number;
+    targetIterations: number;
+    maxIterations: number;
+    /** Configurable thresholds for economics behavior tuning */
+    tuning?: EconomicsTuning;
+}
+/**
+ * Current execution usage.
+ */
+export interface ExecutionUsage {
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    duration: number;
+    iterations: number;
+    toolCalls: number;
+    llmCalls: number;
+    /** Baseline context tokens (not counted toward budget) */
+    baselineContextTokens: number;
+    /** Running total of all input tokens across all LLM calls (for debugging) */
+    cumulativeInputTokens: number;
+}
+/**
+ * Progress tracking state.
+ */
+export interface ProgressState {
+    filesRead: Set<string>;
+    filesModified: Set<string>;
+    commandsRun: string[];
+    recentToolCalls: Array<{
+        tool: string;
+        args: string;
+        timestamp: number;
+    }>;
+    lastMeaningfulProgress: number;
+    stuckCount: number;
+}
+/**
+ * Doom loop detection state (OpenCode pattern).
+ * Detects when agent is stuck calling the same tool repeatedly.
+ */
+export interface LoopDetectionState {
+    /** Whether a doom loop was detected */
+    doomLoopDetected: boolean;
+    /** The tool that's being called repeatedly */
+    lastTool: string | null;
+    /** How many consecutive times the same call was made */
+    consecutiveCount: number;
+    /** Threshold for doom loop detection (default: 3) */
+    threshold: number;
+    /** Threshold for fuzzy doom loop detection (default: threshold + 1) */
+    fuzzyThreshold: number;
+    /** Timestamp of last doom loop warning */
+    lastWarningTime: number;
+}
+/**
+ * Exploration phase state - tracks whether agent is gathering info vs taking action.
+ */
+export interface PhaseState {
+    /** Current phase of execution */
+    phase: 'exploring' | 'planning' | 'acting' | 'verifying';
+    /** Iteration when exploration started */
+    explorationStartIteration: number;
+    /** Unique files read during exploration */
+    uniqueFilesRead: Set<string>;
+    /** Unique search queries performed */
+    uniqueSearches: Set<string>;
+    /** Files that have been modified */
+    filesModified: Set<string>;
+    /** Number of test runs */
+    testsRun: number;
+    /** Whether phase transition is recommended */
+    shouldTransition: boolean;
+    /** Iterations spent in current phase */
+    iterationsInPhase: number;
+    /** Files read in recent iterations (for diminishing returns) */
+    recentNewFiles: number;
+    /** Whether the last test passed */
+    lastTestPassed: boolean | null;
+    /** Consecutive test failures count */
+    consecutiveTestFailures: number;
+    /** Whether agent is in a test-fix cycle */
+    inTestFixCycle: boolean;
+    /** Consecutive bash command failures (any command, not just tests) */
+    consecutiveBashFailures: number;
+    /** Consecutive turns where LLM produced text only (no tool calls) */
+    consecutiveTextOnlyTurns: number;
+}
+/**
+ * Phase-aware budget allocation config.
+ * Prevents spending too long in exploration and reserves time for verification.
+ */
+export interface PhaseBudgetConfig {
+    /** Max percent of iterations for exploration (default: 30%) */
+    maxExplorationPercent: number;
+    /** Percent of iterations reserved for verification (default: 20%) */
+    reservedVerificationPercent: number;
+    /** Whether phase budget enforcement is enabled */
+    enabled: boolean;
+}
+/**
+ * Budget check result.
+ */
+export interface BudgetCheckResult {
+    canContinue: boolean;
+    reason?: string;
+    budgetType?: 'tokens' | 'cost' | 'duration' | 'iterations';
+    isHardLimit: boolean;
+    isSoftLimit: boolean;
+    percentUsed: number;
+    suggestedAction?: 'continue' | 'request_extension' | 'stop' | 'warn';
+    /** Force text-only response (no tool calls allowed) */
+    forceTextOnly?: boolean;
+    /** Prompt to inject for contextual guidance */
+    injectedPrompt?: string;
+    /** Graduated budget severity level */
+    budgetMode?: 'none' | 'warn' | 'restricted' | 'hard';
+    /** Whether task-switching is allowed (false only at hard limits) */
+    allowTaskContinuation?: boolean;
+}
+/**
+ * Extension request.
+ */
+export interface ExtensionRequest {
+    currentUsage: ExecutionUsage;
+    budget: ExecutionBudget;
+    reason: string;
+    suggestedExtension: Partial<ExecutionBudget>;
+}
+/**
+ * Economics events.
+ */
+export type EconomicsEvent = {
+    type: 'budget.warning';
+    budgetType: string;
+    percentUsed: number;
+    remaining: number;
+} | {
+    type: 'budget.exceeded';
+    budgetType: string;
+    limit: number;
+    actual: number;
+} | {
+    type: 'progress.stuck';
+    stuckCount: number;
+    lastProgress: number;
+} | {
+    type: 'progress.made';
+    filesRead: number;
+    filesModified: number;
+} | {
+    type: 'extension.requested';
+    request: ExtensionRequest;
+} | {
+    type: 'extension.granted';
+    extension: Partial<ExecutionBudget>;
+} | {
+    type: 'extension.denied';
+    reason: string;
+} | {
+    type: 'doom_loop.detected';
+    tool: string;
+    consecutiveCount: number;
+} | {
+    type: 'phase.transition';
+    from: string;
+    to: string;
+    reason: string;
+} | {
+    type: 'exploration.saturation';
+    filesRead: number;
+    iterations: number;
+};
+export type EconomicsEventListener = (event: EconomicsEvent) => void;
+/**
+ * Timeout wrapup prompt - injected when a subagent is about to be stopped due to timeout.
+ * Forces a structured JSON summary so the parent agent can make intelligent follow-up decisions.
+ */
+export declare const TIMEOUT_WRAPUP_PROMPT = "[System] You are about to be stopped due to timeout. You MUST respond with a structured summary NOW.\n\nRespond with ONLY this JSON (no tool calls):\n{\n  \"findings\": [\"what you discovered or accomplished\"],\n  \"actionsTaken\": [\"files read, modifications made, commands run\"],\n  \"failures\": [\"what failed or was blocked\"],\n  \"remainingWork\": [\"what you didn't finish\"],\n  \"suggestedNextSteps\": [\"what the parent agent should do next\"]\n}";
+/**
+ * ExecutionEconomicsManager handles budget tracking and progress detection.
+ *
+ * Delegates loop detection to LoopDetector and phase tracking to PhaseTracker.
+ */
+export declare class ExecutionEconomicsManager {
+    private budget;
+    private usage;
+    private progress;
+    private loopDetector;
+    private phaseTracker;
+    private phaseBudget;
+    private startTime;
+    private pausedDuration;
+    private pauseStart;
+    private listeners;
+    private extensionHandler?;
+    private sharedEconomics;
+    private workerId;
+    private originalMaxIterations;
+    private baseline;
+    private lastInputTokens;
+    constructor(budget?: Partial<ExecutionBudget>, sharedEconomics?: SharedEconomicsState, workerId?: string);
+    /**
+     * Pause duration tracking (e.g., while subagents are running).
+     * Prevents the parent agent's wall-clock timer from advancing
+     * during subagent execution.
+     */
+    pauseDuration(): void;
+    /**
+     * Resume duration tracking after subagent completes.
+     */
+    resumeDuration(): void;
+    /**
+     * Get the effective duration accounting for paused time.
+     */
+    private getEffectiveDuration;
+    /**
+     * Configure phase-aware budget allocation.
+     * Only active when enabled=true (eval mode). TUI mode leaves it off.
+     */
+    setPhaseBudget(config: PhaseBudgetConfig): void;
+    /**
+     * Set baseline context tokens for incremental accounting.
+     * Tokens up to this baseline are not counted toward the budget.
+     */
+    setBaseline(tokens: number): void;
+    /**
+     * Get current baseline context tokens.
+     */
+    getBaseline(): number;
+    /**
+     * Update baseline after compaction reduces context size.
+     */
+    updateBaseline(tokens: number): void;
+    /**
+     * Estimate the incremental cost of the next LLM call.
+     * Subtracts baseline from input tokens to give incremental cost.
+     */
+    estimateNextCallCost(inputTokens: number, outputTokens: number): number;
+    /**
+     * Set the extension request handler.
+     */
+    setExtensionHandler(handler: (request: ExtensionRequest) => Promise<Partial<ExecutionBudget> | null>): void;
+    /**
+     * Record token usage from an LLM call.
+     * When a baseline is set, uses incremental accounting: only tokens beyond what
+     * was seen in the previous call are counted toward the budget.
+     * @param inputTokens - Number of input tokens
+     * @param outputTokens - Number of output tokens
+     * @param model - Model name (for fallback pricing calculation)
+     * @param actualCost - Actual cost from provider (e.g., OpenRouter returns this directly)
+     * @param cacheReadTokens - Tokens served from cache (deducted from incremental input)
+     */
+    recordLLMUsage(inputTokens: number, outputTokens: number, model?: string, actualCost?: number, cacheReadTokens?: number): void;
+    /**
+     * Record a text-only turn (LLM response with no tool calls).
+     * Increments the consecutive text-only turn counter for summary-loop detection.
+     */
+    recordTextOnlyTurn(): void;
+    /**
+     * Record a tool call for progress tracking and loop detection.
+     */
+    recordToolCall(toolName: string, args: Record<string, unknown>, _result?: unknown): void;
+    /**
+     * Check if execution can continue.
+     */
+    checkBudget(): BudgetCheckResult;
+    /**
+     * Request a budget extension.
+     */
+    requestExtension(reason: string): Promise<boolean>;
+    /**
+     * Extend the budget.
+     */
+    extendBudget(extension: Partial<ExecutionBudget>): void;
+    /**
+     * Get current usage.
+     */
+    getUsage(): ExecutionUsage;
+    /**
+     * Get current budget.
+     */
+    getBudget(): ExecutionBudget;
+    /**
+     * Get a formatted budget status string for context awareness.
+     * Used by subagents to understand their remaining resources.
+     */
+    getBudgetStatusString(): string;
+    /**
+     * Check if approaching budget limit (for proactive warnings).
+     */
+    isApproachingLimit(): {
+        approaching: boolean;
+        metric: string;
+        percentUsed: number;
+    };
+    /**
+     * Get progress state.
+     */
+    getProgress(): {
+        filesRead: number;
+        filesModified: number;
+        commandsRun: number;
+        isStuck: boolean;
+        stuckCount: number;
+    };
+    /**
+     * Get actual file paths modified during this session.
+     */
+    getModifiedFilePaths(): string[];
+    /**
+     * Get doom loop detection state.
+     */
+    getLoopState(): LoopDetectionState;
+    /**
+     * Get exploration phase state.
+     */
+    getPhaseState(): {
+        phase: string;
+        uniqueFilesRead: number;
+        uniqueSearches: number;
+        filesModified: number;
+        testsRun: number;
+        shouldTransition: boolean;
+        iterationsInPhase: number;
+        lastTestPassed: boolean | null;
+        consecutiveTestFailures: number;
+        inTestFixCycle: boolean;
+        consecutiveBashFailures: number;
+    };
+    /**
+     * Subscribe to events.
+     */
+    on(listener: EconomicsEventListener): () => void;
+    /**
+     * Reset usage (start new task).
+     */
+    reset(): void;
+    private emit;
+    private isStuck;
+}
+/**
+ * Create an economics manager with optional budget configuration.
+ */
+export declare function createEconomicsManager(budget?: Partial<ExecutionBudget>): ExecutionEconomicsManager;
+/**
+ * Quick task budget - for simple queries.
+ */
+export declare const QUICK_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Standard task budget - for typical development tasks.
+ */
+export declare const STANDARD_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Subagent budget - constrained budget for spawned subagents.
+ * Smaller than STANDARD to ensure subagents don't consume all parent's resources.
+ * The 100k token limit gives subagents room to work while leaving budget for the parent
+ * and other parallel subagents.
+ */
+export declare const SUBAGENT_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Large task budget - for complex multi-step tasks.
+ */
+export declare const LARGE_BUDGET: Partial<ExecutionBudget>;
+/**
+ * TUI root agent budget - no time limit, high iteration cap.
+ * The TUI root agent must be able to run as long as needed (swarm tasks,
+ * multi-step workflows). Duration is effectively unlimited; token/cost
+ * limits still apply as a safety net.
+ */
+export declare const TUI_ROOT_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Unlimited budget - no limits (use with caution).
+ */
+export declare const UNLIMITED_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Swarm worker budget - tight constraints for small specialist models.
+ * Each worker gets a small slice of the total swarm budget.
+ */
+export declare const SWARM_WORKER_BUDGET: Partial<ExecutionBudget>;
+/**
+ * Swarm orchestrator budget - moderate budget for decomposition and quality gates.
+ */
+export declare const SWARM_ORCHESTRATOR_BUDGET: Partial<ExecutionBudget>;
+//# sourceMappingURL=economics.d.ts.map

package/dist/src/integrations/budget/economics.d.ts.map

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