/** * Execution Controller — Mecanismo central de controle de execução, * prevenção de loops, detecção de estagnação, deduplicação de ferramentas * e recuperação localizada. * * Integra-se diretamente ao `Commander` e ao `Orchestrator` sem criar um * segundo orquestrador paralelo: governa o estado explícito da execução, * separa as fases (Planning → Execution → Validation → Recovery → Finalization), * impõe limites proporcionais (Fast / Standard / Deep), classifica erros em * 14 categorias com políticas próprias e aciona o circuit breaker progressivo * quando detecta repetição sem progresso observável. */ import type { ExecutionMode } from '../contracts/task-contract.js'; /** Estratégia proporcional à dificuldade da tarefa (Fase 2.3). */ export type ExecutionStrategy = 'fast' | 'standard' | 'deep'; /** Fases explícitas do ciclo de vida da execução (Fase 2.2). */ export type ExecutionLifecyclePhase = 'planning' | 'execution' | 'validation' | 'recovery' | 'finalization'; /** Limites rígidos e configuráveis por execução (Fase 3.1). */ export interface StrategyLimits { maxIterations: number; maxLlmTurns: number; maxToolCalls: number; maxDelegations: number; maxRetriesPerStage: number; maxTimeMs: number; maxTokens: number; maxCostUsd?: number; maxConcurrency: number; } /** * Valores padrão conservadores calibrados por estratégia (Fase 3.1). * Uma correção simples (`fast`) tem limites menores que uma tarefa de * arquitetura complexa (`deep`). */ export declare const DEFAULT_STRATEGY_LIMITS: Record; /** Mapeia `ExecutionMode` do Commander para a estratégia proporcional (`fast | standard | deep`). */ export declare function strategyForMode(mode: ExecutionMode, complexity?: number): ExecutionStrategy; /** * Aceita tanto os modos canônicos (`direct | assisted | orchestrated | autonomous`) * quanto os nomes de estratégia proporcional (`fast | standard | deep`). */ export declare function resolveModeAlias(value: string): ExecutionMode | undefined; export type DetailedErrorCategory = 'transient_network' | 'rate_limit' | 'timeout' | 'auth_failure' | 'invalid_arguments' | 'tool_unavailable' | 'code_error' | 'test_failure' | 'missing_dependency' | 'missing_information' | 'permission_denied' | 'configuration_error' | 'incorrect_model_output' | 'unclassified'; export interface ClassifiedError { category: DetailedErrorCategory; message: string; retryable: boolean; maxCategoryRetries: number; requiresStrategyChange: boolean; /** * Quando true, a falha veio de infraestrutura/autenticação/ambiente externo * e NUNCA deve ser registrada como falha de capacidade do agente ou bug da * implementação na memória. */ isInfrastructureOrAuth: boolean; /** Tempo sugerido de espera antes de tentar novamente (respeita Retry-After). */ retryAfterMs?: number; recommendedAction: 'abort_immediately' | 'retry_with_backoff' | 'fix_arguments' | 'use_alternative_tool' | 'targeted_code_repair' | 'targeted_validation_repair' | 'resolve_dependency' | 'replan_stage'; } /** Extrai `Retry-After` (em ms) de uma mensagem de erro quando presente. */ export declare function parseRetryAfterMs(errorText: string): number | undefined; /** * Calcula backoff exponencial com jitter determinístico/limitado, * respeitando `Retry-After` quando fornecido pelo provedor. */ export declare function computeBackoffWithJitter(baseMs: number, attempt: number, opts?: { factor?: number; maxMs?: number; retryAfterMs?: number; jitterRatio?: number; }): number; /** Classifica um erro nas 14 categorias detalhadas com política de recuperação específica. */ export declare function classifyDetailedError(error: string): ClassifiedError; export interface ToolCallRecord { toolId: string; normalizedArgs: string; argsHash: string; nodeId: string; status: 'ok' | 'error'; result?: unknown; error?: string; executedAt: string; durationMs: number; workspaceRevision: number; observableEffect: 'read' | 'write' | 'exec' | 'external'; } export interface ToolDeduplicationDecision { duplicate: boolean; reusable: boolean; stagnantRepeat: boolean; argsHash: string; normalizedArgs: string; cachedResult?: unknown; previousRecord?: ToolCallRecord; reason?: string; } /** Normaliza recursivamente os argumentos de uma tool para comparação e hashing confiáveis. */ export declare function normalizeToolArgs(toolId: string, input: unknown): string; export declare function hashToolArgs(toolId: string, input: unknown): { normalizedArgs: string; argsHash: string; }; export type StagnationSignalKind = 'same_error_repeated' | 'same_artifact_hash' | 'no_criteria_progress' | 'same_plan_repeated' | 'repeated_tool_no_change' | 'handoff_cycle'; export interface StagnationSignal { kind: StagnationSignalKind; nodeId: string; detail: string; attempt: number; detectedAt: string; } /** * Níveis progressivos do Circuit Breaker (Fase 3.4): * 0 = normal * 1 = primeira repetição suspeita (verifica justificativa) * 2 = repetição sem progresso (exige mudança concreta de estratégia) * 3 = repetição do mesmo erro (interrompe ciclo de retry do erro) * 4 = estagnação persistente (pausa/encerra etapa) * 5 = limite rígido atingido (parada obrigatória) */ export type CircuitBreakerLevel = 0 | 1 | 2 | 3 | 4 | 5; export interface ProgressEvidence { nodeId: string; attempt: number; kind: 'new_valid_artifact' | 'artifact_improved' | 'criteria_reduced' | 'error_resolved' | 'files_modified' | 'new_tool_information'; detail: string; at: string; } export interface InvestigatedHypothesis { nodeId: string; attempt: number; symptom: string; probableCause: string; evidenceUsed: string; plannedChange: string; validationCriteria: string[]; outcome: 'pending' | 'resolved' | 'failed'; at: string; } export interface RecordedError { nodeId: string; attempt: number; category: DetailedErrorCategory; message: string; errorHash: string; at: string; } export interface InterruptionInfo { reason: string; category: 'loop_detected' | 'stagnation' | 'budget_exhausted' | 'cancelled' | 'non_recoverable_error' | 'handoff_limit'; atPhase: ExecutionLifecyclePhase; circuitBreakerLevel: CircuitBreakerLevel; completedStages: string[]; pendingStages: string[]; } export interface ExecutionStateSnapshot { runId: string; originalObjective: string; strategy: ExecutionStrategy; lifecyclePhase: ExecutionLifecyclePhase; acceptanceCriteria: string[]; currentPlan: { graphId: string; mode: ExecutionMode; nodes: string[]; planSignature: string; }; activeStage: string | null; completedStages: string[]; pendingStages: string[]; modifiedFiles: string[]; toolsUsed: ToolCallRecord[]; skillsLoaded: string[]; relevantResults: Record; knownErrors: RecordedError[]; investigatedHypotheses: InvestigatedHypothesis[]; attemptsMade: number; llmTurns: number; delegationsCount: number; handoffChain: Array<{ from: string; to: string; nodeId: string; reason: string; at: string; }>; remainingBudget: { iterations: number; llmTurns: number; toolCalls: number; delegations: number; tokens: number; timeMs: number; costUsd?: number; }; deadlineAt: number; lastRetryReason?: string; progressEvidence: ProgressEvidence[]; stagnationSignals: StagnationSignal[]; circuitBreakerLevel: CircuitBreakerLevel; completionCondition: { met: boolean; reason: string; verifiedCount: number; totalRequired: number; }; interrupted?: InterruptionInfo; toolRepeatsAvoided: number; phaseDurationsMs: Record; phaseHistory: Array<{ phase: ExecutionLifecyclePhase; startedAt: number; endedAt?: number; durationMs?: number; detail?: string; }>; } export interface ExecutionControllerOptions { runId: string; objective: string; mode: ExecutionMode; complexity?: number; graphId?: string; nodeIds?: string[]; acceptanceCriteria?: string[]; limits?: Partial; startedAt?: number; } export declare class ExecutionController { readonly runId: string; readonly originalObjective: string; readonly strategy: ExecutionStrategy; readonly limits: StrategyLimits; readonly startedAt: number; readonly deadlineAt: number; private lifecyclePhase; private currentPlan; private activeStage; private readonly completedStages; private readonly pendingStages; private readonly modifiedFiles; private readonly toolsUsed; private readonly skillsLoaded; private readonly relevantResults; private readonly knownErrors; private readonly investigatedHypotheses; private readonly progressEvidence; private readonly stagnationSignals; private readonly handoffChain; private readonly phaseHistory; private readonly acceptanceCriteria; private attemptsMade; private llmTurns; private delegationsCount; private tokensSpent; private costSpentUsd; private workspaceRevision; private toolRepeatsAvoided; private consecutiveStagnantSteps; private circuitBreakerLevel; private lastRetryReason?; private interrupted?; constructor(opts: ExecutionControllerOptions); /** Transita explicitamente entre Planning, Execution, Validation, Recovery e Finalization. */ enterPhase(phase: ExecutionLifecyclePhase, detail?: string): void; /** Fecha a última fase aberta (chamado ao encerrar o run). */ closeCurrentPhase(): void; markStageStarted(nodeId: string, skills?: string[]): void; markStageSkipped(nodeId: string): void; /** Registra um turno de chamada a modelo LLM e verifica o limite de turnos. */ recordLlmTurn(tokens?: number, costUsd?: number): { allowed: boolean; reason?: string; }; /** * Avalia o resultado de uma etapa e detecta progresso observável ou estagnação * (Fase 3.2). */ recordStageOutcome(input: { nodeId: string; attempt: number; kind: string; contentHash: string; valid: boolean; score: number; unmetCriteria: string[]; }): { progressed: boolean; evidence: ProgressEvidence[]; stagnation?: StagnationSignal; }; /** * Registra um erro em uma etapa, classifica sua natureza e verifica se é * uma repetição idêntica sem progresso (Fase 3.2, 3.4 e 4.1). */ recordStageError(nodeId: string, attempt: number, errorText: string): { classified: ClassifiedError; repeatedCount: number; stagnation?: StagnationSignal; circuitBreakerLevel: CircuitBreakerLevel; shouldAbort: boolean; abortReason?: string; }; /** * Registra uma hipótese de correção estruturada antes de reexecutar uma etapa * (Fase 4.3 — evita correções em cascata e repetições cegas). */ recordRecoveryHypothesis(input: { nodeId: string; attempt: number; symptom: string; probableCause: string; evidenceUsed: string; plannedChange: string; validationCriteria: string[]; }): InvestigatedHypothesis; /** * Verifica antes da execução de uma ferramenta se a chamada é uma repetição * de uma operação recente com argumentos equivalentes (Fase 3.3). */ checkToolCall(toolId: string, input: unknown, nodeId: string): ToolDeduplicationDecision; /** Registra a conclusão de uma chamada de ferramenta e atualiza revisões de arquivos quando mutável. */ recordToolExecution(input: { toolId: string; rawArgs: unknown; nodeId: string; ok: boolean; result?: unknown; error?: string; durationMs: number; }): ToolCallRecord; /** * Controle de delegações e limite de handoffs (Fase 6.1 & 6.2). * Impede ciclos A → B → A sem progresso demonstrável e respeita `maxDelegations`. */ recordHandoff(from: string, to: string, nodeId: string, reason: string): { allowed: boolean; cycleDetected: boolean; reason?: string; }; /** * Verifica se um replanejamento produziu exatamente o mesmo plano anterior * (Fase 3.2 — detector de repetição de plano). */ recordPlanUpdate(graphId: string, mode: ExecutionMode, nodes: Array<{ id: string; agent?: string; status?: string; }>): { changed: boolean; stagnation?: StagnationSignal; }; /** Marca explicitamente a execução como interrompida (Fase 3.5 — nunca confundir interrupção com sucesso). */ markInterrupted(reason: string, category: InterruptionInfo['category']): void; get isInterrupted(): boolean; get interruption(): InterruptionInfo | undefined; /** Verifica se todos os erros registrados foram de autenticação/infraestrutura externa. */ get failedOnlyByInfrastructure(): boolean; private escalateCircuitBreaker; /** Devolve o snapshot estruturado completo da execução (Fase 2.1). */ snapshot(opts?: { verifiedCount?: number; totalRequired?: number; }): ExecutionStateSnapshot; } /** * Formata instruções concretas de correção para injetar em `node.metadata.correction` * quando a validação de schema ou a VerificationEngine reprova um artefato. * * Corrige o Gargalo 5 da auditoria: antes, apenas `interpretCritique` populava * `node.metadata.correction`, então uma retentativa por falha de verificação * chamava o modelo com exatamente o mesmo prompt e repetia o mesmo erro. */ export declare function formatValidationCorrection(input: { nodeId: string; attempt: number; errorCategory: DetailedErrorCategory; unmetCriteria: string[]; errorMessage: string; plannedChange: string; }): string; /** * Estima se delegar/expandir uma tarefa em múltiplos agentes compensa o custo * de inicialização e transferência de contexto (Fase 6.1). */ export declare function evaluateDelegationBenefit(input: { complexity: number; domainsCount: number; wordCount: number; isQuestionOrTrivial: boolean; explicitMode?: ExecutionMode; }): { shouldDelegate: boolean; recommendedMode: ExecutionMode; reason: string; }; //# sourceMappingURL=execution-controller.d.ts.map