import { ConversationTurn, Finding, Intent, SubAgentResult, ContextSummary, FindingReference, ReferencedEntity } from '../types';
import type { AgentResponse } from '../types/agentProtocol';
import { EntityStore } from './entityStore';
import { TraceAgentState, TraceAgentExperiment } from '../state/traceAgentState';
/**
 * Enhanced session context for multi-turn dialogue
 * Tracks conversation history and enables cross-turn finding references
 */
export declare class EnhancedSessionContext {
    private sessionId;
    private traceId;
    private turns;
    private findings;
    private findingTurnMap;
    private references;
    private topicsDiscussed;
    private openQuestions;
    private entityStore;
    private workingMemory;
    private traceAgentState;
    constructor(sessionId: string, traceId: string);
    /**
     * Get the current TraceAgentState (if any).
     */
    getTraceAgentState(): TraceAgentState | null;
    /**
     * Get or create TraceAgentState for this (sessionId, traceId).
     * This is the durable single-source-of-truth used by the goal-driven agent loop.
     */
    getOrCreateTraceAgentState(userGoalSeed?: string): TraceAgentState;
    /**
     * Replace TraceAgentState (e.g., restored from persistence).
     */
    setTraceAgentState(state: any): void;
    /**
     * Refresh TraceAgentState.coverage deterministically from current caches.
     *
     * Coverage is used to:
     * - Avoid repeating experiments (planner sees what's already covered)
     * - Explain "why next" decisions (explicit scope rationale)
     *
     * Data sources (v1):
     * - EntityStore analyzed IDs → entities.frames/sessions
     * - Evidence provenance timeRange/agentId → timeRanges/domains
     */
    refreshTraceAgentCoverage(): void;
    /**
     * Update goal fields from intent understanding (best-effort).
     */
    updateTraceAgentGoalFromIntent(primaryGoal?: string): void;
    /**
     * Append a turn log entry (minimal audit trail in v1).
     */
    recordTraceAgentTurn(params: {
        turnId: string;
        turnIndex: number;
        query: string;
        followUpType?: string;
        intentPrimaryGoal?: string;
        conclusion?: string;
        confidence?: number;
    }): void;
    /**
     * Ingest tool outputs as durable evidence digests (v1).
     * This lets later stages build "evidence chains" with provenance instead of free-text.
     *
     * Note: we intentionally store only compact digests here to keep state small.
     */
    ingestEvidenceFromResponses(responses: AgentResponse[], hint?: {
        stageName?: string;
        round?: number;
    }): string[];
    /**
     * Add a single compact evidence digest (derived from multiple tool outputs, summaries, etc.).
     */
    addEvidenceDigest(params: {
        kind: 'sql' | 'skill' | 'derived';
        title: string;
        digest: string;
        source?: Record<string, any>;
    }): string;
    /**
     * Start an "experiment" (goal-driven agent loop primitive).
     * Experiments are the unit of work we budget (maxExperimentsPerTurn).
     */
    startTraceAgentExperiment(params: {
        type: TraceAgentExperiment['type'];
        objective: string;
    }): string;
    /**
     * Complete an experiment and attach produced evidence IDs.
     */
    completeTraceAgentExperiment(params: {
        id: string;
        status: TraceAgentExperiment['status'];
        producedEvidenceIds?: string[];
        error?: string;
    }): void;
    /**
     * Record a contradiction (data conflict) detected during synthesis.
     */
    recordTraceAgentContradiction(params: {
        description: string;
        severity?: 'minor' | 'major' | 'critical';
        evidenceIds?: string[];
        hypothesisIds?: string[];
    }): string | null;
    /**
     * Get the entity store for frame/session caching.
     * Used by follow-up resolution and drill-down executor.
     */
    getEntityStore(): EntityStore;
    /**
     * Add a new conversation turn
     */
    addTurn(query: string, intent: Intent, result?: SubAgentResult, turnFindings?: Finding[]): ConversationTurn;
    /**
     * Mark a turn as completed
     */
    completeTurn(turnId: string, result: SubAgentResult, newFindings?: Finding[]): void;
    /**
     * Attach route-level post-processing metadata (claim support, verifier output,
     * etc.) to the latest completed turn so resume/status APIs do not drop it.
     */
    annotateLatestCompletedTurn(patch: Partial<SubAgentResult>): void;
    /**
     * Get a specific finding by ID
     */
    getFinding(id: string): Finding | undefined;
    /**
     * Get all findings from a specific turn
     */
    getFindingsFromTurn(turnId: string): Finding[];
    /**
     * Get the turn where a finding was discovered
     */
    getTurnForFinding(findingId: string): ConversationTurn | undefined;
    /**
     * Add a reference between findings
     */
    addFindingReference(fromFindingId: string, toFindingId: string, refType: FindingReference['refType']): void;
    /**
     * Query context by keywords - returns relevant turns
     */
    queryContext(keywords: string[]): ConversationTurn[];
    /**
     * Add an open question
     */
    addOpenQuestion(question: string): void;
    /**
     * Resolve/remove an open question
     */
    resolveQuestion(question: string): void;
    /**
     * Generate a context summary for LLM consumption
     * This creates a compact representation for context-aware prompts
     */
    generateContextSummary(): ContextSummary;
    /**
     * Generate a prompt-friendly context string
     * Used for injecting context into LLM prompts
     *
     * Enhanced to include referenceable entity identifiers (frame_id, session_id)
     * so LLM can understand what entities are available for drill-down.
     */
    generatePromptContext(maxTokens?: number): string;
    /**
     * Update semantic working memory using the final assistant conclusion.
     * This is deterministic (no extra LLM calls) and designed for prompt injection.
     */
    updateWorkingMemoryFromConclusion(params: {
        turnIndex: number;
        query: string;
        conclusion: string;
        confidence?: number;
    }): void;
    /**
     * Build a short, prompt-friendly semantic memory context.
     */
    private generateWorkingMemoryContext;
    private fallbackKeyFindingTitles;
    /**
     * Extract referenceable entities from all findings
     *
     * Returns entities (frames, sessions, etc.) that can be referenced
     * in follow-up queries. Used by LLM to understand what drill-down
     * targets are available.
     *
     * Priority: EntityStore (richer + stable) -> findings scan (fallback)
     */
    extractReferenceableEntities(): ReferencedEntity[];
    /**
     * Get all turns
     */
    getAllTurns(): ConversationTurn[];
    /**
     * Get the last N turns
     */
    getRecentTurns(n: number): ConversationTurn[];
    /**
     * Get all findings
     */
    getAllFindings(): Finding[];
    /**
     * Get session ID
     */
    getSessionId(): string;
    /**
     * Get trace ID
     */
    getTraceId(): string;
    /**
     * Serialize context for persistence
     */
    serialize(): string;
    /**
     * Deserialize context from persistence
     */
    static deserialize(json: string): EnhancedSessionContext;
}
/**
 * Session context manager - manages multiple sessions with LRU eviction
 *
 * Key improvements:
 * - Uses sessionId+traceId as compound key to prevent context cross-contamination
 * - LRU eviction policy to prevent memory leaks
 * - Automatic cleanup of stale sessions
 */
export declare class SessionContextManager {
    private sessions;
    private accessOrder;
    private maxSessions;
    private maxAgeMs;
    constructor(options?: {
        maxSessions?: number;
        maxAgeMs?: number;
    });
    /**
     * Build composite key from sessionId and traceId
     */
    private buildKey;
    /**
     * Get or create a session context
     * If traceId changes for the same sessionId, creates a new context
     */
    getOrCreate(sessionId: string, traceId: string): EnhancedSessionContext;
    /**
     * Inject/replace a session context (used for persistence restore).
     *
     * This enables cross-restart restoration by installing a deserialized
     * EnhancedSessionContext directly into the manager, preserving internal
     * state (turn IDs, references, openQuestions, etc.).
     */
    set(sessionId: string, traceId: string, ctx: EnhancedSessionContext): void;
    /**
     * Get a session context by sessionId and traceId
     */
    get(sessionId: string, traceId?: string): EnhancedSessionContext | undefined;
    /**
     * Remove a session context
     */
    remove(sessionId: string, traceId?: string): void;
    /**
     * List all session IDs (returns unique sessionIds)
     */
    listSessions(): string[];
    /**
     * Get stats about the session manager
     */
    getStats(): {
        sessionCount: number;
        contextCount: number;
        oldestAccessMs: number;
    };
    /**
     * Cleanup stale sessions based on maxAgeMs
     *
     * Note: Sessions with no turns are considered "fresh" and are not evicted,
     * since they were just created and haven't had a chance to record activity.
     */
    cleanupStale(): number;
    private cleanupOldTracesForSession;
    private touchKey;
    private removeFromAccessOrder;
    private evictIfNeeded;
}
export declare const sessionContextManager: SessionContextManager;
//# sourceMappingURL=enhancedSessionContext.d.ts.map