/**
 * Agent Execution Learning — Agent dimension BRAIN integration.
 *
 * Tracks which agent types succeed or fail on which task types, logs agent
 * decisions to brain_decisions with structured context, provides queries to
 * retrieve agent performance history, and implements basic self-healing by
 * recording failure patterns as brain_observations and surfacing healing
 * suggestions when the same failure pattern recurs.
 *
 * This module bridges the agent registry (tasks.db) with the cognitive
 * memory layer (brain.db) without introducing circular dependencies:
 * - Tasks.db agent tables: agent_instances, agent_error_log (agent-schema.ts)
 * - Brain.db tables: brain_decisions, brain_patterns, brain_observations
 *
 * All brain.db writes are best-effort — failures are silently swallowed so
 * agent lifecycle events never fail due to a brain.db write error.
 *
 * @module agents/execution-learning
 * @task T034
 * @epic T029
 */
import type { BrainDataAccessor } from '../store/memory-accessor.js';
import type { AgentType } from '../store/schema/agent-schema.js';
import type { BrainDecisionRow, BrainObservationRow, BrainPatternRow } from '../store/schema/memory-schema.js';
/**
 * The outcome of an agent's execution attempt on a task.
 */
export type AgentExecutionOutcome = 'success' | 'failure' | 'partial';
/**
 * Context recorded when an agent completes or fails a task.
 */
export interface AgentExecutionEvent {
    /** Agent instance ID (agt_...). */
    agentId: string;
    /** Agent type classification. */
    agentType: AgentType;
    /** Task ID that was attempted. */
    taskId: string;
    /** Task type: 'epic' | 'task' | 'subtask'. */
    taskType: string;
    /** Task labels for richer pattern classification. */
    taskLabels?: string[];
    /** Execution outcome. */
    outcome: AgentExecutionOutcome;
    /** Error message if outcome is 'failure'. */
    errorMessage?: string;
    /** Error classification if outcome is 'failure'. */
    errorType?: 'retriable' | 'permanent' | 'unknown';
    /** Session ID the agent was running under. */
    sessionId?: string;
    /** Duration of execution in milliseconds (optional). */
    durationMs?: number;
}
/**
 * Summary of an agent type's execution performance on a task type.
 */
export interface AgentPerformanceSummary {
    /** Agent type. */
    agentType: AgentType;
    /** Task type this summary is for. */
    taskType: string;
    /** Total execution attempts tracked. */
    totalAttempts: number;
    /** Number of successful attempts. */
    successCount: number;
    /** Number of failed attempts. */
    failureCount: number;
    /** Success rate [0.0 – 1.0]. */
    successRate: number;
    /** Most recent attempt outcome. */
    lastOutcome: AgentExecutionOutcome | null;
    /** Timestamp of the most recent tracked decision. */
    lastSeenAt: string | null;
}
/**
 * A self-healing suggestion derived from failure pattern history.
 */
export interface HealingSuggestion {
    /** Pattern ID from brain_patterns. */
    patternId: string;
    /** Human-readable description of the failure pattern. */
    failurePattern: string;
    /** Times this pattern has been seen. */
    frequency: number;
    /** Mitigation / suggested next action. */
    suggestion: string;
    /** How confident the system is in this suggestion [0.0 – 1.0]. */
    confidence: number;
}
/**
 * Record an agent execution event to brain_decisions.
 *
 * Each event becomes a `tactical` decision entry describing which agent type
 * handled which task type and whether it succeeded. This gives the BRAIN
 * system a queryable history of agent-task execution for pattern extraction.
 *
 * The call is best-effort — if brain.db is unavailable the error is swallowed
 * and null is returned so agent lifecycle code is never disrupted.
 *
 * @param event - Execution event to record
 * @param cwd - Working directory (resolves brain.db path)
 * @returns The stored decision row, or null on failure
 */
export declare function recordAgentExecution(event: AgentExecutionEvent, cwd?: string): Promise<BrainDecisionRow | null>;
/**
 * Internal implementation that accepts a pre-constructed accessor.
 * Separated for testability without touching the real file system.
 *
 * @internal
 */
export declare function _recordAgentExecutionWithAccessor(event: AgentExecutionEvent, brain: BrainDataAccessor): Promise<BrainDecisionRow | null>;
/**
 * Retrieve agent execution performance history from brain_decisions.
 *
 * Queries all `tactical` decisions recorded by `recordAgentExecution` and
 * aggregates them into per-(agentType, taskType) performance summaries.
 *
 * @param filters - Optional filters to narrow results
 * @param cwd - Working directory
 * @returns Array of performance summaries sorted by agentType then taskType
 */
export declare function getAgentPerformanceHistory(filters?: {
    agentType?: AgentType;
    taskType?: string;
    limit?: number;
}, cwd?: string): Promise<AgentPerformanceSummary[]>;
/**
 * Internal implementation with injected accessor for testability.
 *
 * @internal
 */
export declare function _getAgentPerformanceHistoryWithAccessor(filters: {
    agentType?: AgentType;
    taskType?: string;
    limit?: number;
}, brain: BrainDataAccessor): Promise<AgentPerformanceSummary[]>;
/**
 * Record a task failure pattern to brain_patterns.
 *
 * When a task fails, the (agentType, taskType, errorType) combination is
 * stored as a `failure` pattern in brain.db. On subsequent failures matching
 * the same combination, the frequency counter is incremented and the success
 * rate updated. This data is what powers `getSelfHealingSuggestions`.
 *
 * The call is best-effort and never throws.
 *
 * @param event - A failure execution event (outcome must be 'failure')
 * @param cwd - Working directory
 * @returns The upserted pattern row, or null on error
 */
export declare function recordFailurePattern(event: AgentExecutionEvent, cwd?: string): Promise<BrainPatternRow | null>;
/**
 * Internal implementation with injected accessor.
 *
 * @internal
 */
export declare function _recordFailurePatternWithAccessor(event: AgentExecutionEvent, brain: BrainDataAccessor): Promise<BrainPatternRow | null>;
/**
 * Store a healing strategy observation to brain_observations.
 *
 * When a failure pattern reaches a significant frequency threshold (≥ 3),
 * a `change` observation is recorded to represent the healing action
 * recommended for future recurrences of the same pattern.
 *
 * The call is best-effort and never throws.
 *
 * @param event - The failure event that triggered healing
 * @param strategy - Human-readable healing strategy description
 * @param cwd - Working directory
 * @returns The stored observation row, or null on error
 */
export declare function storeHealingStrategy(event: AgentExecutionEvent, strategy: string, cwd?: string): Promise<BrainObservationRow | null>;
/**
 * Internal implementation with injected accessor.
 *
 * @internal
 */
export declare function _storeHealingStrategyWithAccessor(event: AgentExecutionEvent, strategy: string, brain: BrainDataAccessor): Promise<BrainObservationRow | null>;
/**
 * Get self-healing suggestions for a given agent type and task type.
 *
 * Queries brain_patterns for known failure patterns matching the
 * (agentType, taskType) combination and returns healing suggestions
 * ordered by frequency (most-seen first).
 *
 * Returns an empty array if no failure patterns are found or brain.db
 * is unavailable.
 *
 * @param agentType - The agent type to check
 * @param taskType - The task type to check
 * @param cwd - Working directory
 * @returns Array of healing suggestions, highest frequency first
 */
export declare function getSelfHealingSuggestions(agentType: AgentType, taskType: string, cwd?: string): Promise<HealingSuggestion[]>;
/**
 * Internal implementation with injected accessor.
 *
 * @internal
 */
export declare function _getSelfHealingSuggestionsWithAccessor(agentType: AgentType, taskType: string, brain: BrainDataAccessor): Promise<HealingSuggestion[]>;
/**
 * Full agent lifecycle event processor.
 *
 * Convenience function that:
 * 1. Records the execution event to brain_decisions
 * 2. On failure: records/updates the failure pattern in brain_patterns
 * 3. On failure with frequency ≥ 3: stores a healing strategy observation
 *
 * Returns a structured result with the recorded IDs and any healing
 * suggestions that now apply.
 *
 * All operations are best-effort — the call never throws.
 *
 * @param event - The execution event
 * @param cwd - Working directory
 */
export declare function processAgentLifecycleEvent(event: AgentExecutionEvent, cwd?: string): Promise<{
    decisionId: string | null;
    patternId: string | null;
    observationId: string | null;
    healingSuggestions: HealingSuggestion[];
}>;
//# sourceMappingURL=execution-learning.d.ts.map