/**
 * Detailed trace event types for incremental agent tracing
 *
 * This file defines 12 trace event types for comprehensive agent debugging:
 * - 6 core events: iteration:detail, llm:call, tool:execution, memory:snapshot, decision:point, synthesis:forced
 * - 6 debugging events: error:captured, prompt:diff, tool:filter, context:trim, stopping:analysis, llm:validation
 */
type TraceEventType = 'task:start' | 'task:end' | 'iteration:detail' | 'llm:call' | 'tool:execution' | 'memory:snapshot' | 'decision:point' | 'synthesis:forced' | 'memory:fact_added' | 'memory:archive_store' | 'memory:summarization_result' | 'memory:summarization_llm_call' | 'error:captured' | 'prompt:diff' | 'tool:filter' | 'context:trim' | 'context:snapshot' | 'context:diff' | 'stopping:analysis' | 'llm:validation';
/**
 * Base trace entry for all events
 */
interface BaseTraceEntry {
    /** Auto-increment sequence number (1, 2, 3...) */
    seq: number;
    /** ISO 8601 timestamp */
    timestamp: string;
    /** Event type discriminator */
    type: TraceEventType;
    /** Which iteration (1-based) - optional for non-iteration events */
    iteration?: number;
}
/**
 * task:start — includes systemPrompt and available tools.
 * Complementary to agent:start (which is in AgentEvent/events.ts).
 */
interface TaskStartEvent extends BaseTraceEntry {
    type: 'task:start';
    iteration: number;
    task: string;
    tier: string;
    systemPrompt: string;
    availableTools: Array<{
        name: string;
        description: string;
    }>;
}
/** task:end — final result summary at execution loop exit */
interface TaskEndEvent extends BaseTraceEntry {
    type: 'task:end';
    iteration: number;
    success: boolean;
    stopped?: boolean;
    summary: string;
    error?: string;
    filesCreated: string[];
    filesModified: string[];
    filesRead: string[];
    totalIterations: number;
    totalTokens: number;
}
/**
 * 1. iteration:detail - Full context at start of iteration
 */
interface IterationDetailEvent extends BaseTraceEntry {
    type: 'iteration:detail';
    iteration: number;
    config: {
        maxIterations: number;
        mode: 'instant' | 'auto' | 'thinking';
        temperature: number;
    };
    availableTools: {
        total: number;
        tools: string[];
    };
    context: {
        messagesCount: number;
        totalTokens: number;
        conversationSummary: string;
    };
}
/**
 * 2. llm:call - LLM request and response with cost tracking
 */
interface LLMCallEvent extends BaseTraceEntry {
    type: 'llm:call';
    iteration: number;
    request: {
        model: string;
        temperature: number;
        maxTokens: number;
        tools: string[];
    };
    response: {
        content: string | null;
        toolCalls?: Array<{
            id: string;
            name: string;
            input: Record<string, unknown>;
        }>;
        stopReason: 'tool_use' | 'end_turn' | 'max_tokens' | 'stop_sequence';
        usage: {
            inputTokens: number;
            outputTokens: number;
            totalTokens: number;
        };
    };
    timing: {
        startedAt: string;
        completedAt: string;
        durationMs: number;
    };
    cost: {
        inputCost: number;
        outputCost: number;
        totalCost: number;
        currency: 'USD';
    };
}
/**
 * 3. tool:execution - Tool call execution with result
 */
interface ToolExecutionEvent extends BaseTraceEntry {
    type: 'tool:execution';
    iteration: number;
    tool: {
        name: string;
        callId: string;
    };
    input: Record<string, unknown>;
    output: {
        success: boolean;
        result?: unknown;
        error?: {
            message: string;
            code?: string;
            stack?: string;
        };
        truncated: boolean;
        originalLength?: number;
    };
    timing: {
        startedAt: string;
        completedAt: string;
        durationMs: number;
    };
    metadata?: {
        filesRead?: string[];
        searchesPerformed?: number;
        [key: string]: unknown;
    };
}
/**
 * 4. memory:snapshot - Memory state at point in time
 */
interface MemorySnapshotEvent extends BaseTraceEntry {
    type: 'memory:snapshot';
    iteration: number;
    sessionMemory: {
        conversationHistory: number;
        userPreferences: Record<string, unknown>;
    };
    sharedMemory: {
        facts: string[];
        findings: string[];
    };
    executionMemory: {
        filesRead: string[];
        searchesMade: number;
        toolsUsed: Record<string, number>;
    };
    /** Two-tier memory: FactSheet snapshot (Tier 1) */
    factSheet?: {
        totalFacts: number;
        estimatedTokens: number;
        byCategory: Record<string, number>;
    };
    /** Two-tier memory: ArchiveMemory snapshot (Tier 2) */
    archive?: {
        totalEntries: number;
        uniqueFiles: number;
        totalChars: number;
    };
}
/**
 * 5. decision:point - Agent decision reasoning
 */
interface DecisionPointEvent extends BaseTraceEntry {
    type: 'decision:point';
    iteration: number;
    decision: 'tool_selection' | 'stopping_condition' | 'synthesis';
    toolSelection?: {
        chosenTool: string;
        reasoning: string;
        alternatives: Array<{
            tool: string;
            reason: string;
        }>;
    };
    stoppingCondition?: {
        shouldStop: boolean;
        reason: string;
    };
}
/**
 * 6. synthesis:forced - Forced synthesis trace event
 */
interface SynthesisForcedTraceEvent extends BaseTraceEntry {
    type: 'synthesis:forced';
    iteration: number;
    trigger: {
        reason: 'last_iteration' | 'max_iterations' | 'no_tool_call' | 'user_request';
        lastIteration: number;
        lastToolCall?: string;
    };
    synthesisPrompt: string;
    synthesisResponse: {
        content: string;
        tokens: number;
        durationMs: number;
    };
}
/**
 * memory:fact_added - Emitted when a fact is added/merged in the FactSheet
 */
interface FactAddedEvent extends BaseTraceEntry {
    type: 'memory:fact_added';
    iteration: number;
    fact: {
        id: string;
        category: string;
        fact: string;
        confidence: number;
        source: string;
        merged: boolean;
        superseded?: string;
    };
    factSheetStats: {
        totalFacts: number;
        estimatedTokens: number;
        byCategory: Record<string, number>;
    };
}
/**
 * memory:archive_store - Emitted when a tool output is archived
 */
interface ArchiveStoreEvent extends BaseTraceEntry {
    type: 'memory:archive_store';
    iteration: number;
    entry: {
        id: string;
        toolName: string;
        filePath?: string;
        outputLength: number;
        estimatedTokens: number;
        keyFactsExtracted: number;
    };
    archiveStats: {
        totalEntries: number;
        totalChars: number;
        uniqueFiles: number;
        evicted: number;
    };
}
/**
 * memory:summarization_result - Emitted after each LLM fact extraction cycle
 */
interface SummarizationResultEvent extends BaseTraceEntry {
    type: 'memory:summarization_result';
    iteration: number;
    input: {
        iterationRange: [number, number];
        messagesCount: number;
        inputChars: number;
        inputTokens: number;
    };
    output: {
        factsExtracted: number;
        factsByCategory: Record<string, number>;
        outputTokens: number;
        llmDurationMs: number;
    };
    delta: {
        factSheetBefore: number;
        factSheetAfter: number;
        tokensBefore: number;
        tokensAfter: number;
        newFacts: number;
        mergedFacts: number;
        evictedFacts: number;
    };
    efficiency: {
        compressionRatio: number;
        factDensity: number;
        newFactRate: number;
    };
}
/**
 * memory:summarization_llm_call - Raw LLM call made by SmartSummarizer.
 * Useful for debugging fact extraction quality: see exact prompt sent and
 * raw response received. Emitted alongside memory:summarization_result.
 */
interface SummarizationLLMCallEvent extends BaseTraceEntry {
    type: 'memory:summarization_llm_call';
    iteration: number;
    /** Exact prompt sent to LLM (full text, untruncated) */
    prompt: string;
    /** Raw LLM response content before JSON parsing */
    rawResponse: string;
    /** Whether JSON parsing succeeded */
    parseSuccess: boolean;
    /** Parse error message if parsing failed */
    parseError?: string;
    timing: {
        durationMs: number;
        outputTokens: number;
    };
}
/**
 * 7. error:captured - Error with full context
 */
interface ErrorCapturedEvent extends BaseTraceEntry {
    type: 'error:captured';
    iteration: number;
    error: {
        message: string;
        stack: string;
        code?: string;
        name: string;
    };
    context: {
        lastLLMCall?: {
            request: Record<string, unknown>;
            response: Record<string, unknown>;
            durationMs: number;
        };
        lastToolCall?: {
            name: string;
            input: Record<string, unknown>;
            output?: unknown;
            error?: string;
        };
        currentMessages: Array<{
            role: 'system' | 'user' | 'assistant';
            contentPreview: string;
        }>;
        memoryState: {
            filesRead: string[];
            searchesMade: number;
        };
        availableTools: string[];
    };
    agentStack: {
        currentPhase?: string;
        currentStep?: string;
        iterationHistory: number[];
    };
}
/**
 * 8. prompt:diff - Changes to prompt between iterations
 */
interface PromptDiffEvent extends BaseTraceEntry {
    type: 'prompt:diff';
    iteration: number;
    diff: {
        messagesAdded: number;
        messagesRemoved: number;
        totalMessages: number;
        changes: Array<{
            type: 'added' | 'removed' | 'modified';
            role: 'system' | 'user' | 'assistant';
            contentPreview: string;
            index: number;
        }>;
        contextGrowth: {
            tokensBefore: number;
            tokensAfter: number;
            delta: number;
        };
    };
}
/**
 * 9. tool:filter - Tool filtering logic
 */
interface ToolFilterEvent extends BaseTraceEntry {
    type: 'tool:filter';
    iteration: number;
    filtering: {
        before: {
            totalTools: number;
            tools: string[];
        };
        after: {
            totalTools: number;
            tools: string[];
        };
        filtered: Array<{
            name: string;
            reason: 'last_iteration' | 'mode_restriction' | 'tier_restriction' | 'custom';
            explanation: string;
        }>;
    };
}
/**
 * 10. context:trim - Context trimming/summarization
 */
interface ContextTrimEvent extends BaseTraceEntry {
    type: 'context:trim';
    iteration: number;
    trimming: {
        trigger: 'max_tokens' | 'max_messages' | 'manual';
        before: {
            messageCount: number;
            estimatedTokens: number;
        };
        after: {
            messageCount: number;
            estimatedTokens: number;
        };
        removed: {
            messageCount: number;
            tokensRemoved: number;
            contentPreview: string;
        };
        strategy: 'sliding_window' | 'summarization' | 'importance_based';
    };
}
/**
 * 10b. context:snapshot - Full context window snapshot before LLM call
 */
interface ContextSnapshotEvent extends BaseTraceEntry {
    type: 'context:snapshot';
    iteration: number;
    messageCount: number;
    totalChars: number;
    estimatedTokens: number;
    toolCount: number;
    tier: string;
    slidingWindow: {
        fullHistorySize: number;
        windowedSize: number;
        droppedMessages: number;
    };
    messages: Array<{
        index: number;
        role: string;
        chars: number;
        truncated?: boolean;
        toolCalls?: string[];
        toolCallId?: string;
        preview?: string;
    }>;
}
/**
 * 11. stopping:analysis - Stopping condition analysis
 */
interface StoppingAnalysisEvent extends BaseTraceEntry {
    type: 'stopping:analysis';
    iteration: number;
    conditions: {
        maxIterationsReached: boolean;
        timeoutReached: boolean;
        foundTarget: boolean;
        sufficientContext: boolean;
        diminishingReturns: boolean;
        userInterrupt: boolean;
        error: boolean;
    };
    reasoning: string;
    metrics: {
        iterationsUsed: number;
        iterationsRemaining: number;
        timeElapsedMs: number;
        timeRemainingMs?: number;
        toolCallsInLast3Iterations: number;
        confidenceScore?: number;
    };
}
/**
 * 12. llm:validation - LLM response validation
 */
interface LLMValidationEvent extends BaseTraceEntry {
    type: 'llm:validation';
    iteration: number;
    validation: {
        stopReason: 'tool_use' | 'end_turn' | 'max_tokens' | 'stop_sequence';
        isValid: boolean;
        checks: {
            hasContent: boolean;
            hasToolCalls: boolean;
            toolCallsValid: boolean;
            jsonParseable: boolean;
            schemaValid: boolean;
        };
        issues: Array<{
            severity: 'error' | 'warning' | 'info';
            check: string;
            message: string;
            recovery?: string;
        }>;
    };
}
/**
 * Discriminated union of all trace event types
 */
type DetailedTraceEntry = TaskStartEvent | TaskEndEvent | IterationDetailEvent | LLMCallEvent | ToolExecutionEvent | MemorySnapshotEvent | DecisionPointEvent | SynthesisForcedTraceEvent | FactAddedEvent | ArchiveStoreEvent | SummarizationResultEvent | SummarizationLLMCallEvent | ErrorCapturedEvent | PromptDiffEvent | ToolFilterEvent | ContextTrimEvent | ContextSnapshotEvent | StoppingAnalysisEvent | LLMValidationEvent;

/**
 * Verification types for agent responses
 *
 * Cross-tier verification system to detect hallucinations
 * and assess response quality.
 */
/**
 * Warning codes for verification issues
 */
type VerificationWarningCode = 'UNVERIFIED_FILE' | 'UNVERIFIED_PACKAGE' | 'UNVERIFIED_CLASS' | 'UNVERIFIED_FUNCTION' | 'LOW_CONFIDENCE' | 'INCOMPLETE_ANSWER' | 'CONTRADICTION' | 'VERIFICATION_FAILED';
/**
 * Warning about potential issues in agent response
 */
interface VerificationWarning {
    code: VerificationWarningCode;
    message: string;
    details?: Record<string, unknown>;
}
/**
 * Result of cross-tier verification
 */
interface VerificationResult {
    /** Entities mentioned in answer (files, packages, classes) */
    mentions: string[];
    /** Mentions that were verified against tool results */
    verifiedMentions: string[];
    /** Mentions that could NOT be verified (potential hallucinations) */
    unverifiedMentions: string[];
    /** Overall confidence in answer correctness (0-1) */
    confidence: number;
    /** How complete is the answer (0-1) */
    completeness: number;
    /** Aspects of the question that weren't addressed */
    gaps: string[];
    /** Warnings about potential issues */
    warnings: VerificationWarning[];
    /** Brief reasoning for the assessment */
    reasoning: string;
}
/**
 * Quality metrics for agent response
 */
interface QualityMetrics {
    /** Overall confidence in answer (0-1) */
    confidence: number;
    /** How complete relative to question (0-1) */
    completeness: number;
    /** Unanswered aspects */
    gaps: string[];
    /** Verifier's reasoning */
    reasoning: string;
}
/**
 * Input for cross-tier verification
 */
interface VerificationInput {
    /** Original task/question */
    task: string;
    /** Agent's final answer */
    answer: string;
    /** Summary of tool results (files read, commands run, etc.) */
    toolResultsSummary: string;
    /** List of files that were actually read */
    filesRead?: string[];
    /** Executor tier (to determine verifier tier) */
    executorTier?: 'small' | 'medium' | 'large';
}
/**
 * Raw output from verifier LLM (via tool call)
 */
interface VerificationOutput {
    /** Entities mentioned in answer (files, packages, classes) */
    mentions: string[];
    /** Which mentions appear in tool results */
    verified: string[];
    /** Which mentions could NOT be verified */
    unverified: string[];
    /** Overall confidence in answer (0-1) */
    confidence: number;
    /** How complete is the answer (0-1) */
    completeness: number;
    /** What aspects of the question weren't addressed */
    gaps: string[];
    /** Potential issues found */
    warnings: string[];
    /** Brief reasoning for the assessment */
    reasoning: string;
}
/**
 * Record of a single tool call and its result
 */
interface ToolResultRecord {
    /** Tool name (e.g., 'fs:read', 'mind:rag-query') */
    tool: string;
    /** Input parameters */
    input: Record<string, unknown>;
    /** Tool output */
    output: string;
    /** When the tool was called */
    timestamp?: string;
}
/**
 * Summary of tool results for verifier
 */
interface ToolResultsSummary {
    /** Human-readable summary for verifier */
    text: string;
    /** Files that were read */
    filesRead: string[];
    /** Files that were created/modified */
    filesWritten: string[];
    /** Commands that were executed */
    commandsRun: string[];
    /** Searches that were performed */
    searchQueries: string[];
}
/**
 * Thresholds for verification-based decisions
 */
interface VerificationThresholds {
    /** Max unverified mentions before retry */
    maxUnverifiedMentions: number;
    /** Min confidence before reformulation */
    minConfidence: number;
    /** Min confidence to mark as uncertain */
    uncertainConfidence: number;
    /** Min completeness before follow-up tasks */
    minCompleteness: number;
    /** Max retries per subtask */
    maxRetries: number;
}
/**
 * Default verification thresholds
 */
declare const DEFAULT_VERIFICATION_THRESHOLDS: VerificationThresholds;
/**
 * Verification event data (for agent events)
 */
interface VerificationEventData {
    /** Verification result */
    verification: VerificationResult;
    /** Which subtask/task was verified */
    taskId?: string;
    /** Executor tier used */
    executorTier?: 'small' | 'medium' | 'large';
    /** Verifier tier used */
    verifierTier?: 'small' | 'medium' | 'large';
    /** Duration of verification in ms */
    durationMs?: number;
}

/**
 * @module @kb-labs/agent-contracts/turn
 * Turn-based conversation schema for agent UI
 *
 * A Turn represents a complete interaction cycle (user message → agent response).
 * Backend assembles Turns from raw AgentEvents, frontend simply renders.
 */
/**
 * Lightweight summary of a file change for Turn.metadata.
 * Does not include before/after content to keep turn history compact.
 */
interface FileChangeSummary {
    changeId: string;
    filePath: string;
    operation: 'write' | 'patch' | 'delete';
    timestamp: string;
    linesAdded?: number;
    linesRemoved?: number;
    /** True when the file was newly created by the agent */
    isNew: boolean;
    sizeAfter: number;
    approved?: boolean;
}
interface RollbackResult {
    rolledBack: number;
    skipped: number;
    conflicts?: ConflictInfo[];
}
interface ConflictInfo {
    filePath: string;
    changeId: string;
    reason: string;
}
/**
 * A turn represents a complete agent interaction cycle.
 * Assembled from multiple events by the backend.
 */
interface Turn {
    /** Unique turn ID (derived from root agent run ID) */
    id: string;
    /** Turn type determines rendering strategy */
    type: 'user' | 'assistant' | 'system';
    /** Turn sequence number in session (1-based) */
    sequence: number;
    /** Timestamp of first event in turn */
    startedAt: string;
    /** Timestamp of last event in turn (null if incomplete) */
    completedAt: string | null;
    /** Turn completion status */
    status: 'streaming' | 'completed' | 'failed' | 'cancelled';
    /** Optional error if turn failed */
    error?: {
        code: string;
        message: string;
        details?: unknown;
    };
    /** Ordered steps within this turn */
    steps: TurnStep[];
    /** Metadata for debugging */
    metadata: {
        agentId: string;
        agentName?: string;
        taskId?: string;
        totalTokens?: number;
        totalDurationMs?: number;
        /** Run ID that produced this assistant turn */
        runId?: string;
        /** Summary of files changed during this turn (populated on run completion) */
        fileChanges?: FileChangeSummary[];
    };
}
/**
 * A step is a single action within a turn.
 * Maps to event types from the event stream.
 */
type TurnStep = ThinkingStep | ToolUseStep | ToolResultStep | SubAgentStep | TextStep | ErrorStep;
/** Agent reasoning/planning step */
interface ThinkingStep {
    type: 'thinking';
    id: string;
    timestamp: string;
    content: string;
    /** Optional structured thinking (from extended_thinking) */
    structured?: {
        reasoning: string;
        nextActions: string[];
    };
}
/** Tool invocation step — unified: starts as pending, updated in-place when done */
interface ToolUseStep {
    type: 'tool_use';
    id: string;
    timestamp: string;
    toolName: string;
    input: Record<string, unknown>;
    /** Optional tool call ID for correlation */
    toolCallId?: string;
    /** Execution status — backend updates in-place on tool:end / tool:error */
    status: 'pending' | 'done' | 'error';
    /** Whether tool execution succeeded (false = tool returned an error result) */
    success?: boolean;
    /** Set when status = done */
    output?: unknown;
    /** Set when status = error */
    error?: string;
    /** Set when status = done */
    durationMs?: number;
    /**
     * Optional rich metadata from tool event — propagated from ToolEventMetadata.
     * Includes diff, filePath, resultCount, confidence, exitCode, etc.
     */
    metadata?: {
        /** File path being operated on */
        filePath?: string;
        /** File content (for fs:read) */
        fileContent?: string;
        /** Unified diff output (for fs:edit, fs:patch, fs:write) */
        diff?: string;
        /** Content before the change */
        oldContent?: string;
        /** Content after the change */
        newContent?: string;
        /** Lines changed count */
        linesChanged?: number;
        /** Lines added */
        linesAdded?: number;
        /** Lines removed */
        linesRemoved?: number;
        /** Search result count (for grep, glob, rag-query) */
        resultCount?: number;
        /** Search results */
        results?: unknown[];
        /** Search/RAG query text */
        query?: string;
        /** Confidence score 0-1 (for RAG queries) */
        confidence?: number;
        /** Exit code (for bash/shell tools) */
        exitCode?: number;
        /** Command that was executed */
        command?: string;
        /** Stdout output */
        stdout?: string;
        /** Stderr output */
        stderr?: string;
        /** Human-readable summary from the tool */
        summary?: string;
        /** UI rendering hint */
        uiHint?: 'code' | 'diff' | 'table' | 'json' | 'markdown' | 'plain' | 'todo';
        /** Any extra structured data */
        structured?: Record<string, unknown>;
    };
}
/**
 * @deprecated Use ToolUseStep with status field instead.
 * Kept for backward compatibility with old session data.
 */
interface ToolResultStep {
    type: 'tool_result';
    id: string;
    timestamp: string;
    toolName: string;
    toolCallId?: string;
    success: boolean;
    output?: unknown;
    error?: string;
    durationMs?: number;
}
/** Sub-agent invocation (nested turn reference) */
interface SubAgentStep {
    type: 'subagent';
    id: string;
    timestamp: string;
    /** Reference to nested turn ID */
    turnId: string;
    agentName: string;
    task: string;
    /** Status of sub-agent execution */
    status: 'running' | 'completed' | 'failed';
    /** Summary of sub-agent result (once completed) */
    summary?: string;
}
/** Plain text output step */
interface TextStep {
    type: 'text';
    id: string;
    timestamp: string;
    content: string;
    /** Optional role (user/assistant/system) */
    role?: string;
}
/** Error step */
interface ErrorStep {
    type: 'error';
    id: string;
    timestamp: string;
    code: string;
    message: string;
    details?: unknown;
}

/**
 * Agent Event System
 *
 * Simple callback-based event streaming for agents.
 * Client decides how to handle events (CLI, WebSocket, SSE, etc.)
 */
/**
 * All possible agent event types
 */
type AgentEventType = 'agent:start' | 'agent:end' | 'agent:error' | 'iteration:start' | 'iteration:end' | 'llm:start' | 'llm:chunk' | 'llm:stream' | 'llm:end' | 'thinking:start' | 'thinking:chunk' | 'thinking:end' | 'tool:start' | 'tool:end' | 'tool:error' | 'subtask:start' | 'subtask:end' | 'synthesis:forced' | 'synthesis:start' | 'synthesis:complete' | 'memory:read' | 'memory:write' | 'verification:start' | 'verification:complete' | 'progress:update' | 'status:change' | 'middleware:decision' | 'llm:debug';
/**
 * Base event structure
 *
 * Hierarchical Event Correlation:
 * - agentId: unique ID for each agent instance
 * - parentAgentId: for child agents, the ID of parent (orchestrator)
 * - toolCallId: for tool events, correlates start/end/error for same tool call
 * - startedAt: for *:end events, timestamp when the operation started (for duration calc)
 */
interface AgentEventBase {
    type: AgentEventType;
    timestamp: string;
    sessionId?: string;
    taskId?: string;
    /** Unique ID for this agent instance (e.g., "agent-abc123") */
    agentId?: string;
    /** Parent agent ID for sub-agents spawned by main agent */
    parentAgentId?: string;
    /** For tool events: correlates tool:start → tool:end/tool:error */
    toolCallId?: string;
    /** For *:end events: when the operation started (ISO string) */
    startedAt?: string;
    /** Monotonic sequence number within a single run (assigned by RunManager) */
    seq?: number;
    /** Run ID that produced this event (assigned before persistence) */
    runId?: string;
    /** Global monotonic sequence across all runs in a session (assigned by SessionManager on persist) */
    sessionSeq?: number;
    /** Optional extra metadata (e.g., workingDir, agentName) added at persist time */
    metadata?: Record<string, unknown>;
}
/**
 * Agent lifecycle events
 */
interface AgentStartEvent extends AgentEventBase {
    type: 'agent:start';
    data: {
        task: string;
        tier: string;
        maxIterations: number;
        toolCount: number;
        /** Token budget config (for debugging budget-related stops) */
        budget?: {
            maxTokens: number;
            softLimitRatio: number;
            hardLimitRatio: number;
        };
        /** Workspace topology discovered at startup */
        workspaceTopology?: string[];
        /** Working directory */
        workingDir?: string;
    };
}
interface AgentEndEvent extends AgentEventBase {
    type: 'agent:end';
    data: {
        success: boolean;
        summary: string;
        iterations: number;
        tokensUsed: number;
        durationMs: number;
        filesCreated: string[];
        filesModified: string[];
        stopReason?: string;
        answer?: string;
    };
}
interface AgentErrorEvent extends AgentEventBase {
    type: 'agent:error';
    data: {
        error: string;
        iteration?: number;
        recoverable: boolean;
    };
}
/**
 * Iteration events
 */
interface IterationStartEvent extends AgentEventBase {
    type: 'iteration:start';
    data: {
        iteration: number;
        maxIterations: number;
    };
}
interface IterationEndEvent extends AgentEventBase {
    type: 'iteration:end';
    data: {
        iteration: number;
        hadToolCalls: boolean;
        toolCallCount: number;
        /** Cumulative tokens used across all iterations so far */
        cumulativeTokens?: number;
    };
}
/**
 * LLM events
 */
interface LLMStartEvent extends AgentEventBase {
    type: 'llm:start';
    data: {
        tier: string;
        iteration?: number;
        messageCount: number;
        toolCount?: number;
        systemPromptChars?: number;
    };
}
interface LLMChunkEvent extends AgentEventBase {
    type: 'llm:chunk';
    data: {
        chunk: string;
        index: number;
    };
}
interface LLMStreamEvent extends AgentEventBase {
    type: 'llm:stream';
    data: {
        chunk: string;
        index?: number;
    };
}
interface ThinkingStartEvent extends AgentEventBase {
    type: 'thinking:start';
    data: {
        content?: string;
    };
}
interface ThinkingChunkEvent extends AgentEventBase {
    type: 'thinking:chunk';
    data: {
        content: string;
    };
}
interface ThinkingEndEvent extends AgentEventBase {
    type: 'thinking:end';
    data: {
        content?: string;
    };
}
interface LLMEndEvent extends AgentEventBase {
    type: 'llm:end';
    data: {
        tokensUsed: number;
        /** Prompt tokens for this LLM call (for debugging). */
        promptTokens?: number;
        /** Completion tokens for this LLM call (for debugging). */
        completionTokens?: number;
        durationMs: number;
        hasToolCalls: boolean;
        /** Number of tool calls in this response. */
        toolCallCount?: number;
        stopReason?: string;
        /** First ~500 chars of LLM response content (always included for debugging). */
        content?: string;
    };
}
/**
 * Tool events
 *
 * Flexible structure for any tool:
 * - input: always present, contains tool arguments
 * - output: result string (for tool:end)
 * - metadata: optional extra data for UI (diff, fileContent, etc.)
 */
interface ToolStartEvent extends AgentEventBase {
    type: 'tool:start';
    data: {
        /** Tool name (e.g., 'fs:edit', 'mind:rag-query') */
        toolName: string;
        /** Tool input arguments */
        input: Record<string, unknown>;
        /** Optional metadata for UI (e.g., file preview before edit) */
        metadata?: ToolEventMetadata;
    };
}
interface ToolEndEvent extends AgentEventBase {
    type: 'tool:end';
    data: {
        /** Tool name */
        toolName: string;
        /** Whether tool execution succeeded */
        success: boolean;
        /** Tool output (result string) */
        output?: string;
        /** Execution duration in milliseconds */
        durationMs: number;
        /** Output length in characters */
        outputLength?: number;
        /** Optional metadata for UI (e.g., diff, structured result) */
        metadata?: ToolEventMetadata;
    };
}
interface ToolErrorEvent extends AgentEventBase {
    type: 'tool:error';
    data: {
        /** Tool name */
        toolName: string;
        /** Error message */
        error: string;
        /** Optional metadata for UI (e.g., stack trace, context) */
        metadata?: ToolEventMetadata;
    };
}
/**
 * Tool event metadata for UI display
 *
 * This is intentionally flexible - each tool can add its own data.
 * UI clients can check for specific fields and render accordingly.
 */
interface ToolEventMetadata {
    /** File path being operated on */
    filePath?: string;
    /** File content (for read operations) */
    fileContent?: string;
    /** Diff output (for edit operations) - can be unified diff format */
    diff?: string;
    /** Old content before edit */
    oldContent?: string;
    /** New content after edit */
    newContent?: string;
    /** Lines changed count */
    linesChanged?: number;
    /** Lines added count */
    linesAdded?: number;
    /** Lines removed count */
    linesRemoved?: number;
    /** Search query used */
    query?: string;
    /** Number of results found */
    resultCount?: number;
    /** Search results array (flexible structure) */
    results?: Array<{
        file?: string;
        line?: number;
        content?: string;
        score?: number;
        [key: string]: unknown;
    }>;
    /** Confidence score (0-1) for RAG queries */
    confidence?: number;
    /** Command executed */
    command?: string;
    /** Exit code */
    exitCode?: number;
    /** stdout output */
    stdout?: string;
    /** stderr output */
    stderr?: string;
    /** Memory entry type */
    memoryType?: string;
    /** Memory scope */
    memoryScope?: 'session' | 'shared';
    /** Structured data for any tool (for new tools without specific fields) */
    structured?: Record<string, unknown>;
    /** Raw JSON for complex outputs */
    rawJson?: string;
    /** Human-readable summary for UI */
    summary?: string;
    /** UI hint for how to render this event */
    uiHint?: 'code' | 'diff' | 'table' | 'json' | 'markdown' | 'plain';
}
interface SubtaskStartEvent extends AgentEventBase {
    type: 'subtask:start';
    data: {
        subtaskId: string;
        description: string;
        index: number;
        total: number;
    };
}
interface SubtaskEndEvent extends AgentEventBase {
    type: 'subtask:end';
    data: {
        subtaskId: string;
        success: boolean;
        summary?: string;
    };
}
/**
 * Synthesis events (forced answer synthesis on last iteration)
 */
interface SynthesisForcedEvent extends AgentEventBase {
    type: 'synthesis:forced';
    data: {
        iteration: number;
        reason: string;
        messagesCount: number;
    };
}
interface SynthesisStartEvent extends AgentEventBase {
    type: 'synthesis:start';
    data: {
        iteration: number;
        promptLength: number;
    };
}
interface SynthesisCompleteEvent extends AgentEventBase {
    type: 'synthesis:complete';
    data: {
        iteration: number;
        contentLength: number;
        hasContent: boolean;
        tokensUsed: number;
        previewFirst200: string;
    };
}
/**
 * Memory events
 */
interface MemoryReadEvent extends AgentEventBase {
    type: 'memory:read';
    data: {
        source: 'shared' | 'session';
        entryCount: number;
    };
}
interface MemoryWriteEvent extends AgentEventBase {
    type: 'memory:write';
    data: {
        target: 'shared' | 'session';
        entryType: string;
        content: string;
    };
}
/**
 * Verification events (Anti-Hallucination)
 */
interface VerificationStartEvent extends AgentEventBase {
    type: 'verification:start';
    data: {
        /** What is being verified */
        target: 'subtask' | 'synthesis';
        /** Subtask ID (if verifying subtask) */
        subtaskId?: string;
        /** Executor tier */
        executorTier: 'small' | 'medium' | 'large';
        /** Verifier tier (one level above executor) */
        verifierTier: 'small' | 'medium' | 'large';
    };
}
interface VerificationCompleteEvent extends AgentEventBase {
    type: 'verification:complete';
    data: {
        /** What was verified */
        target: 'subtask' | 'synthesis';
        /** Subtask ID (if verifying subtask) */
        subtaskId?: string;
        /** Overall confidence (0-1) */
        confidence: number;
        /** Completeness (0-1) */
        completeness: number;
        /** Verified mentions */
        verifiedMentions: string[];
        /** Unverified mentions (potential hallucinations) */
        unverifiedMentions: string[];
        /** Gaps in the answer */
        gaps: string[];
        /** Verification warnings */
        warnings: string[];
        /** Duration in milliseconds */
        durationMs: number;
        /** Action taken based on verification */
        action?: 'accepted' | 'retry' | 'reformulate' | 'follow_up';
    };
}
/**
 * Progress events
 */
interface ProgressUpdateEvent extends AgentEventBase {
    type: 'progress:update';
    data: {
        phase: string;
        progress: number;
        message?: string;
        budgetUsedTokens?: number;
        budgetRemainingTokens?: number;
        budgetTotalTokens?: number;
    };
}
interface StatusChangeEvent extends AgentEventBase {
    type: 'status:change';
    data: {
        status: 'idle' | 'thinking' | 'executing' | 'waiting' | 'done' | 'error' | 'analyzing' | 'planning' | 'researching' | 'finalizing';
        message?: string;
        toolName?: string;
        budgetUsedTokens?: number;
        budgetRemainingTokens?: number;
        budgetTotalTokens?: number;
    };
}
/**
 * Middleware decision events
 * Emitted when middleware takes a notable action (budget warning, context trim, loop detection, etc.)
 */
interface MiddlewareDecisionEvent extends AgentEventBase {
    type: 'middleware:decision';
    data: {
        middleware: string;
        decision: string;
        details: Record<string, unknown>;
    };
}
/**
 * LLM debug event — full prompt and response content
 * Only emitted when AgentConfig.debug = true
 */
interface LLMDebugEvent extends AgentEventBase {
    type: 'llm:debug';
    data: {
        iteration: number;
        systemPrompt: string;
        messages: Array<{
            role: string;
            content: string;
        }>;
        responseContent: string;
    };
}
/**
 * Union of all event types
 */
type AgentEvent = AgentStartEvent | AgentEndEvent | AgentErrorEvent | IterationStartEvent | IterationEndEvent | LLMStartEvent | LLMChunkEvent | LLMStreamEvent | ThinkingStartEvent | ThinkingChunkEvent | ThinkingEndEvent | LLMEndEvent | ToolStartEvent | ToolEndEvent | ToolErrorEvent | SubtaskStartEvent | SubtaskEndEvent | SynthesisForcedEvent | SynthesisStartEvent | SynthesisCompleteEvent | MemoryReadEvent | MemoryWriteEvent | VerificationStartEvent | VerificationCompleteEvent | ProgressUpdateEvent | StatusChangeEvent | MiddlewareDecisionEvent | LLMDebugEvent;
/**
 * Event callback type
 */
type AgentEventCallback = (event: AgentEvent) => void;
/**
 * Event emitter interface
 */
interface AgentEventEmitter {
    /**
     * Emit an event to all listeners
     */
    emit(event: AgentEvent): void;
    /**
     * Subscribe to events
     */
    on(callback: AgentEventCallback): () => void;
    /**
     * Subscribe to specific event type
     */
    onType<T extends AgentEventType>(type: T, callback: (event: Extract<AgentEvent, {
        type: T;
    }>) => void): () => void;
}

/**
 * Core types and interfaces for agents
 */
/**
 * Agent execution modes - extensible for future modes
 */
type AgentMode = 'execute' | 'plan' | 'edit' | 'debug';
declare const AGENT_MODES: ["execute", "plan", "edit", "debug"];
/**
 * Mode-specific configuration
 */
interface ModeConfig {
    mode: AgentMode;
    context?: ModeContext;
}
/**
 * Context for different modes (discriminated union)
 */
type ModeContext = ExecuteContext | PlanContext | EditContext | DebugContext;
/**
 * Execute mode - standard task execution
 */
interface ExecuteContext {
    mode: 'execute';
    task: string;
}
/**
 * Plan mode - generate execution plan without running
 */
interface PlanContext {
    mode: 'plan';
    task: string;
    complexity?: 'simple' | 'medium' | 'complex';
}
/**
 * Edit mode - modify existing code/files
 */
interface EditContext {
    mode: 'edit';
    task: string;
    targetFiles?: string[];
    dryRun?: boolean;
}
/**
 * Debug mode - analyze errors with trace context
 */
interface DebugContext {
    mode: 'debug';
    task: string;
    errorTrace?: string;
    relevantFiles?: string[];
    traceFile?: string;
}
/**
 * LLM tier for model selection
 */
type LLMTier = 'small' | 'medium' | 'large';
interface AgentSmartTieringConfig {
    enabled?: boolean;
    nodes?: {
        intentInference?: boolean;
        searchAssessment?: boolean;
        taskValidation?: boolean;
    };
    auditTasksPreferMedium?: boolean;
    minEvidenceDensityForSmallValidation?: number;
    maxIterationsWithoutProgressForMediumSearch?: number;
    intentInferenceMinTaskCharsForMedium?: number;
}
/**
 * Token budget policy for long-running agent tasks.
 * All fields are optional and should be resolved with defaults by agent-core.
 */
interface AgentTokenBudgetConfig {
    /** Enables token-budget policy. When false, current behavior is preserved. */
    enabled?: boolean;
    /** Absolute token cap per run. Default: 1,000,000. Token budget is the primary execution control. */
    maxTokens?: number;
    /** Soft-limit ratio for convergence nudges (default: 0.8). */
    softLimitRatio?: number;
    /** Hard-limit ratio for stop/synthesis (default: 1.0). */
    hardLimitRatio?: number;
    /** Enforce hard limit when reached (default: false). */
    hardStop?: boolean;
    /** On hard limit, synthesize from collected evidence (default: true). */
    forceSynthesisOnHardLimit?: boolean;
    /** Disable broad exploration at soft limit (default: true). */
    restrictBroadExplorationAtSoftLimit?: boolean;
    /** Allow dynamic iteration-budget extension near limits (default: true). */
    allowIterationBudgetExtension?: boolean;
    /** Spec-generation specific budget strategy. */
    spec?: AgentSpecBudgetConfig;
}
/**
 * Budget strategy for spec generation.
 * Spec budget is derived from plan size, then clamped by floor/ceiling.
 */
interface AgentSpecBudgetConfig {
    /** Enable dynamic spec budget strategy (default: true). */
    enabled?: boolean;
    /** Target spec budget multiplier from plan tokens (default: 4.0). */
    multiplier?: number;
    /** Minimum token budget for spec generation (default: 100000). */
    floorTokens?: number;
    /** Maximum token budget for spec generation (default: 250000). */
    ceilingTokens?: number;
    /** Reserve this share of total budget for final synthesis/verification (default: 0.2). */
    synthesisReserveRatio?: number;
    /** Save partial spec instead of hard-failing when quality gate is not passed (default: true). */
    partialOnFailure?: boolean;
}
/**
 * Response verbosity/rigor mode for final answers.
 * - auto: adapt format by question complexity (default)
 * - brief: concise output for simple questions
 * - deep: thorough structured output for complex questions
 */
type AgentResponseMode = 'auto' | 'brief' | 'deep';
/**
 * Task type for decomposition decision (Phase 0: Smart Decomposition)
 *
 * - research: Parallel exploration of different aspects (easy to parallelize)
 * - implementation-single-domain: Implementation in one domain (prefer single agent - high coupling)
 * - implementation-cross-domain: Implementation across domains (parallelize by domain - backend/frontend/CLI)
 * - simple: Trivial task (single agent - overhead dominates)
 */
type DecompositionTaskType = 'research' | 'implementation-single-domain' | 'implementation-cross-domain' | 'simple' | 'single-agent';
/**
 * Decomposition decision result
 */
interface DecompositionDecision {
    taskType: DecompositionTaskType;
    shouldDecompose: boolean;
    reason: string;
    estimatedIterations?: number;
    subtasks?: Array<{
        description: string;
        domain?: string;
        estimatedMinutes?: number;
    }>;
}
/**
 * Execution mode for plan
 */
type ExecutionMode = 'single-agent' | 'sequential' | 'parallel' | 'mixed';
/**
 * Task execution status
 */
type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
declare const TASK_STATUSES: ["pending", "in_progress", "completed", "failed", "skipped"];
/**
 * Plan update action (Phase 3: Orchestrator Observation)
 */
type PlanUpdateAction = 'add' | 'remove' | 'reorder' | 'modify';
/**
 * Plan update event (Phase 3: Orchestrator Observation)
 */
interface PlanUpdate {
    /** Type of update */
    action: PlanUpdateAction;
    /** Reason for the update */
    reason: string;
    /** Subtask being modified (for add/remove/modify) */
    subtaskId?: string;
    /** New subtask to add */
    newSubtask?: {
        id: string;
        description: string;
        status: TaskStatus;
    };
    /** New order of subtask IDs (for reorder) */
    newOrder?: string[];
    /** Timestamp when update was made */
    timestamp: string;
}

/**
 * Fact categories for the FactSheet (Tier 1: Hot Memory)
 * Ordered by render/eviction priority (corrections first, environment last)
 */
type FactCategory = 'correction' | 'blocker' | 'decision' | 'finding' | 'file_content' | 'architecture' | 'tool_result' | 'environment';
/**
 * Single fact entry in the FactSheet
 */
interface FactSheetEntry {
    /** Unique fact ID (auto-generated) */
    id: string;
    /** Iteration when this fact was created/updated */
    iteration: number;
    /** Fact category */
    category: FactCategory;
    /** The fact text */
    fact: string;
    /** Confidence level 0.0-1.0 */
    confidence: number;
    /** Source of the fact (tool name or 'llm_extraction') */
    source: string;
    /** When this fact was last updated */
    updatedAt: string;
    /** Number of times this fact was confirmed/merged */
    confirmations: number;
    /** ID of fact this supersedes (if any) */
    supersedes?: string;
}
/**
 * Single entry in the ArchiveMemory (Tier 2: Cold Storage)
 */
interface ArchiveEntry {
    /** Unique archive entry ID */
    id: string;
    /** Iteration when this was stored */
    iteration: number;
    /** Tool that produced this output */
    toolName: string;
    /** Tool input parameters */
    toolInput: Record<string, unknown>;
    /** Full untruncated tool output */
    fullOutput: string;
    /** Length of fullOutput in chars */
    outputLength: number;
    /** Estimated tokens (chars / 4) */
    estimatedTokens: number;
    /** ISO timestamp */
    timestamp: string;
    /** File path if this was a file read */
    filePath?: string;
    /** Key facts extracted from this output */
    keyFacts?: string[];
}
/**
 * Configuration for the two-tier memory system
 * All fields optional — defaults from AGENT_MEMORY constants
 */
interface TwoTierMemoryConfig {
    /** Max estimated tokens for FactSheet render (default: 5000) */
    factSheetMaxTokens?: number;
    /** Max number of facts in FactSheet (default: 60) */
    factSheetMaxEntries?: number;
    /** Max entries in ArchiveMemory (default: 200) */
    archiveMaxEntries?: number;
    /** Min confidence for auto-extracted facts (default: 0.5) */
    autoFactMinConfidence?: number;
}
/**
 * Agent configuration
 */
interface AgentConfig {
    workingDir: string;
    maxIterations: number;
    temperature: number;
    sessionId?: string;
    tier?: LLMTier;
    /** Optional analytics adapter from CLI host context. */
    analytics?: {
        track(event: string, payload: unknown): Promise<void>;
    } | null;
    /** Token budget policy (usually loaded from kb.config.json -> agents.tokenBudget). */
    tokenBudget?: AgentTokenBudgetConfig;
    /** Mode configuration (execute/plan/edit/debug) */
    mode?: ModeConfig;
    /** Event callback for streaming agent execution events to UI (optional) */
    onEvent?: AgentEventCallback;
    /** Enable debug tracing: full prompts and responses in llm:debug events */
    debug?: boolean;
    /** Unique ID for this agent instance (auto-generated if not provided) */
    agentId?: string;
    /** Parent agent ID (for child agents spawned by orchestrator) */
    parentAgentId?: string;
    /** Abort signal from parent — when aborted, this agent stops between iterations */
    abortSignal?: AbortSignal;
    /** Tool filter for sub-agents: only these tools will be registered in child's ToolContext. */
    allowedTools?: string[];
}
/**
 * Task result from agent execution
 */
interface TaskResult {
    success: boolean;
    summary: string;
    filesCreated: string[];
    filesModified: string[];
    filesRead: string[];
    iterations: number;
    tokensUsed: number;
    error?: string;
    trace?: TraceEntry[];
    /** Enhanced summary from SummaryEnhancerProcessor */
    enhancedSummary?: string;
    /** Metrics from MetricsCollectorProcessor */
    metrics?: Record<string, unknown>;
    /** Trace file path from TraceSaverProcessor */
    traceFile?: string;
    /** Session ID for this execution */
    sessionId?: string;
    /** Generated plan (only in plan mode) */
    plan?: TaskPlan;
    /** Generated spec (only in spec stage of plan flow) */
    spec?: TaskSpec;
    /** Plan ID (if executing from plan) */
    planId?: string;
    /** File change summaries captured by ChangeTrackingMiddleware */
    fileChanges?: FileChangeSummary[];
    /** Verification result from cross-tier verifier */
    verification?: VerificationResult;
    /** Quality metrics from verification */
    qualityMetrics?: QualityMetrics;
}
/**
 * Trace entry for debugging and analytics
 */
interface TraceEntry {
    iteration: number;
    timestamp: string;
    type: 'llm_call' | 'llm_response' | 'tool_call' | 'tool_result' | 'tool_cache_hit' | 'task_start' | 'task_end' | 'subtask_start' | 'subtask_end' | 'plan_generated' | 'phase_start' | 'phase_end' | 'step_start' | 'step_end';
    data: Record<string, unknown>;
    durationMs?: number;
}
/**
 * Tracer interface for recording execution traces
 */
interface Tracer {
    /**
     * Record a trace entry. seq and timestamp are assigned by the writer.
     */
    trace(entry: Omit<DetailedTraceEntry, 'seq' | 'timestamp'>): void;
    /**
     * Get all trace entries
     */
    getEntries(): TraceEntry[];
    /**
     * Save trace to file (backward compat - alias for flush)
     */
    save(filePath: string): Promise<void>;
    /**
     * Clear all entries
     */
    clear(): void;
    /**
     * Finalize trace (flush, generate index, cleanup old traces)
     * Call this when agent execution completes
     */
    finalize?(): Promise<void>;
    /**
     * Create index file for fast CLI queries
     * Called automatically by finalize()
     */
    createIndex?(): Promise<void>;
}
/**
 * Tool call from LLM
 */
interface ToolCall {
    id: string;
    name: string;
    input: Record<string, unknown>;
}
/**
 * Tool definition for LLM (OpenAI Function Calling format)
 */
interface ToolDefinition {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: {
            type: 'object';
            properties: Record<string, any>;
            required?: string[];
        };
    };
}
/**
 * Tool execution result
 */
interface ToolResult {
    success: boolean;
    output?: string;
    error?: string;
    errorDetails?: {
        code: string;
        message: string;
        retryable?: boolean;
        hint?: string;
        details?: Record<string, unknown>;
    };
    metadata?: Record<string, unknown>;
}
/**
 * Memory category
 */
type MemoryCategory = 'architecture' | 'decision' | 'learning' | 'pattern' | 'config' | 'user_input' | 'project_rules' | 'agent_state';
/**
 * Reflection result from agent self-analysis
 */
interface ReflectionResult {
    /** What the agent has found so far */
    findingsSummary: string;
    /** Confidence in current answer (0.0-1.0) */
    confidence: number;
    /** Questions that remain unanswered */
    questionsRemaining: string[];
    /** Whether agent should continue searching */
    shouldContinue: boolean;
    /** Reason for continue/stop decision */
    reason: string;
}
/**
 * Memory entry (extended for agent memory system)
 */
interface MemoryEntry {
    /** Unique identifier */
    id?: string;
    /** The actual content */
    content: string;
    /** Category of memory */
    category?: MemoryCategory;
    /** Timestamp when this memory was created */
    timestamp: string;
    /** Type of memory entry */
    type?: 'task' | 'observation' | 'action' | 'result' | 'reflection' | 'user_feedback' | 'user_correction' | 'user_preference' | 'constraint' | 'finding' | 'blocker';
    /** Additional metadata */
    metadata?: {
        /** Session this memory belongs to */
        sessionId?: string;
        /** Task this memory is related to */
        taskId?: string;
        /** Importance score (0-1) for summarization priority */
        importance?: number;
        /** Tags for categorization */
        tags?: string[];
        /** Related memory IDs */
        relatedTo?: string[];
        /** Who created this entry */
        source?: 'agent' | 'user' | 'system';
        /** Confidence level 0-1 (for findings) */
        confidence?: number;
        /** ID of memory entry this supersedes (for corrections) */
        supersedes?: string;
        /** Scope of this memory */
        scope?: 'session' | 'project' | 'global';
        /** When this memory expires */
        expiresAt?: string;
        /** Flag indicating this is the original user task (from orchestrator) */
        isOriginalUserTask?: boolean;
        /** Global context extracted by orchestrator from original task */
        globalContext?: {
            /** Target directory where files should be created */
            targetDirectory?: string;
            /** Constraints extracted from task (NEVER, MUST NOT, etc.) */
            constraints: string[];
            /** Requirements extracted from task (numbered lists, bullets) */
            requirements: string[];
        };
    };
}
/**
 * Session entry in memory
 */
interface SessionEntry {
    sessionId: string;
    timestamp: string;
    tasks: string[];
    learnings: string;
}
/**
 * Project context
 */
interface ProjectContext {
    name: string;
    description: string;
    technologies: string[];
    structure: string;
}
/**
 * Persistent memory
 */
interface PersistentMemory {
    facts: MemoryEntry[];
    sessions: SessionEntry[];
    projectContext: ProjectContext;
}
/**
 * TODO item status
 */
type TodoStatus = 'pending' | 'in-progress' | 'completed' | 'blocked';
declare const TODO_STATUSES: ["pending", "in-progress", "completed", "blocked"];
/**
 * TODO item priority
 */
type TodoPriority = 'low' | 'medium' | 'high';
declare const TODO_PRIORITIES: ["low", "medium", "high"];
/**
 * TODO item
 */
interface TodoItem {
    id: string;
    description: string;
    status: TodoStatus;
    priority: TodoPriority;
    createdAt: string;
    updatedAt?: string;
    completedAt?: string;
    notes?: string;
}
/**
 * TODO list
 */
interface TodoList {
    sessionId: string;
    items: TodoItem[];
    createdAt: string;
    updatedAt: string;
}
/**
 * Execution plan subtask
 */
interface Subtask {
    id: string;
    description: string;
    status: TaskStatus;
    result?: TaskResult;
    isAlternative?: boolean;
    originalTaskId?: string;
}
/**
 * Execution plan
 */
interface ExecutionPlan {
    originalTask: string;
    subtasks: Subtask[];
    createdAt: string;
    /** Execution mode (Phase 0: Smart Decomposition) */
    executionMode?: ExecutionMode;
    /** Reason for decomposition decision (Phase 0) */
    decompositionReason?: string;
    /** Task type classification (Phase 0) */
    taskType?: DecompositionTaskType;
    /** LLM-estimated max iterations needed (Phase 0) */
    estimatedIterations?: number;
}
/**
 * Result processor interface for post-processing task results
 */
interface ResultProcessor {
    /**
     * Process task result (e.g., add summary, collect metrics, save artifacts)
     */
    process(result: TaskResult): Promise<TaskResult>;
}
/**
 * Memory summary - condensed version of multiple memories
 */
interface MemorySummary {
    /** Unique identifier */
    id: string;
    /** Timestamp when this summary was created */
    timestamp: string;
    /** Number of memories that were summarized */
    memoryCount: number;
    /** Time range covered by this summary */
    timeRange: {
        start: string;
        end: string;
    };
    /** The summarized content */
    content: string;
    /** Original memory IDs that were summarized */
    originalMemoryIds: string[];
}
/**
 * Agent memory interface - manages short-term and long-term memory
 */
interface AgentMemory {
    /**
     * Add a new memory entry
     */
    add(entry: Omit<MemoryEntry, 'id' | 'timestamp'>): Promise<MemoryEntry>;
    /**
     * Get recent memories (short-term memory)
     * @param limit - Maximum number of entries to return
     */
    getRecent(limit?: number): Promise<MemoryEntry[]>;
    /**
     * Search memories by query
     * @param query - Search query
     * @param limit - Maximum number of results
     */
    search(query: string, limit?: number): Promise<MemoryEntry[]>;
    /**
     * Get memories by session ID
     */
    getBySession(sessionId: string): Promise<MemoryEntry[]>;
    /**
     * Get memories by task ID
     */
    getByTask(taskId: string): Promise<MemoryEntry[]>;
    /**
     * Get current context (for LLM prompt)
     * Returns formatted string with recent memories + summaries
     */
    getContext(maxTokens?: number): Promise<string>;
    /**
     * Summarize old memories to save space
     * Returns the created summary
     */
    summarize(): Promise<MemorySummary>;
    /**
     * Clear all memories (use with caution!)
     */
    clear(): Promise<void>;
    /**
     * Get memory statistics
     */
    getStats(): Promise<{
        totalMemories: number;
        totalSummaries: number;
        oldestMemory: string | null;
        newestMemory: string | null;
        estimatedTokens: number;
    }>;
    /**
     * Add a user correction (highest priority)
     * @param content - The correction content
     * @param supersedes - Optional ID of memory entry this corrects
     */
    addUserCorrection?(content: string, supersedes?: string): Promise<MemoryEntry>;
    /**
     * Add a user preference
     * @param content - The preference content
     * @param scope - Scope of the preference (session or project)
     */
    addUserPreference?(content: string, scope?: 'session' | 'project'): Promise<MemoryEntry>;
    /**
     * Add a constraint (rule that must be followed)
     * @param content - The constraint content
     */
    addConstraint?(content: string): Promise<MemoryEntry>;
    /**
     * Add a finding (agent discovery)
     * @param content - What was found
     * @param confidence - Confidence level 0-1
     * @param sources - Source file paths
     */
    addFinding?(content: string, confidence: number, sources: string[]): Promise<MemoryEntry>;
    /**
     * Add a blocker (something preventing progress)
     * @param content - What's blocking
     * @param taskId - Optional task ID this blocks
     */
    addBlocker?(content: string, taskId?: string): Promise<MemoryEntry>;
    /**
     * Get all user corrections
     */
    getUserCorrections?(): Promise<MemoryEntry[]>;
    /**
     * Get active constraints
     */
    getActiveConstraints?(): Promise<MemoryEntry[]>;
    /**
     * Get current blockers
     */
    getBlockers?(): Promise<MemoryEntry[]>;
    /**
     * Get user preferences
     */
    getUserPreferences?(): Promise<MemoryEntry[]>;
    /**
     * Get structured context with sections for corrections, constraints, etc.
     * @param maxTokens - Maximum tokens for context
     */
    getStructuredContext?(maxTokens?: number): Promise<string>;
    /**
     * Save the orchestrator's last answer (NEVER summarized)
     * This is stored separately and always returned in full for follow-up questions.
     *
     * @param answer - The full answer text
     * @param task - The original task/question
     * @param metadata - Optional metadata (confidence, completeness, sources)
     */
    saveLastAnswer?(answer: string, task: string, metadata?: {
        confidence?: number;
        completeness?: number;
        sources?: string[];
        filesCreated?: string[];
        filesModified?: string[];
    }): Promise<void>;
    /**
     * Get the last orchestrator answer (full, unsummarized)
     * Returns null if no previous answer exists.
     */
    getLastAnswer?(): Promise<{
        answer: string;
        task: string;
        timestamp: string;
        metadata?: {
            confidence?: number;
            completeness?: number;
            sources?: string[];
            filesCreated?: string[];
            filesModified?: string[];
        };
    } | null>;
    /**
     * Clear the last answer (e.g., when starting a completely new topic)
     */
    clearLastAnswer?(): Promise<void>;
}
/**
 * Memory configuration
 */
interface MemoryConfig {
    /** Session ID for this memory instance */
    sessionId?: string;
    /** Maximum number of memories to keep in short-term (before summarization) */
    maxShortTermMemories?: number;
    /** Maximum tokens for context (when to trigger summarization) */
    maxContextTokens?: number;
    /** Storage key prefix for cache */
    keyPrefix?: string;
    /** TTL for memories in milliseconds (optional, for auto-cleanup) */
    ttl?: number;
}
/**
 * Task execution plan
 */
interface TaskPlan {
    /** Unique plan identifier */
    id: string;
    /** Session this plan belongs to */
    sessionId: string;
    /** Original task description */
    task: string;
    /** Mode this plan was generated for */
    mode: AgentMode;
    /** Execution phases */
    phases: Phase[];
    /** Estimated duration (human-readable, e.g. "30 minutes") */
    estimatedDuration?: string;
    /** Complexity assessment */
    complexity: 'simple' | 'medium' | 'complex';
    /** When plan was created */
    createdAt: string;
    /** Last update time */
    updatedAt: string;
    /** Plan status */
    status: 'draft' | 'approved' | 'spec_ready' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
    /** Human-readable plan markdown (optional canonical draft body) */
    markdown?: string;
    /** Optional timestamp when plan was approved */
    approvedAt?: string;
    /** Optional approval comment */
    approvalComment?: string;
}
/**
 * Detailed specification generated from an approved plan.
 * Contains exact before/after diffs for each plan step.
 */
interface TaskSpec {
    /** Unique spec identifier */
    id: string;
    /** Plan this spec was generated from */
    planId: string;
    /** Session this spec belongs to */
    sessionId: string;
    /** Original task description */
    task: string;
    /** Spec sections (one per plan phase/step) */
    sections: SpecSection[];
    /** Spec status */
    status: 'generating' | 'draft' | 'partial' | 'approved' | 'failed';
    /** Full markdown text of the spec */
    markdown?: string;
    /** When spec was created */
    createdAt: string;
    /** Last update time */
    updatedAt: string;
}
/**
 * One section of the spec — corresponds to a plan phase/step
 */
interface SpecSection {
    /** Reference to phase.id from the plan */
    planPhaseId: string;
    /** Reference to step.id (if granular) */
    planStepId?: string;
    /** Section title */
    title: string;
    /** What we're doing and why (from plan) */
    description: string;
    /** Exact code changes */
    changes: SpecChange[];
}
/**
 * A concrete change in one file — exact before/after diff
 */
interface SpecChange {
    /** Full file path from project root */
    file: string;
    /** Line range, e.g. "3510-3514" */
    lineRange: string;
    /** Current code (verified — read by the agent) */
    before: string;
    /** New code after the change */
    after: string;
    /** Explanation of why this change is needed */
    explanation: string;
}
/**
 * Execution phase (group of related steps)
 */
interface Phase {
    /** Unique phase identifier */
    id: string;
    /** Phase name (e.g., "Setup", "Implementation", "Testing") */
    name: string;
    /** Phase description */
    description: string;
    /** Steps in this phase */
    steps: Step[];
    /** Phase IDs that must complete before this one */
    dependencies: string[];
    /** Phase status */
    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
    /** When phase started */
    startedAt?: string;
    /** When phase completed */
    completedAt?: string;
    /** Error if failed */
    error?: string;
    /** Stable anchor for cross-document referencing (e.g. plan-abc:phase-1) */
    anchor?: string;
}
/**
 * Execution step (atomic action)
 */
interface Step {
    /** Unique step identifier */
    id: string;
    /** Step description */
    action: string;
    /** Tool to use (if applicable) */
    tool?: string;
    /** Tool arguments */
    args?: Record<string, unknown>;
    /** Expected outcome */
    expectedOutcome: string;
    /** Step status */
    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
    /** Result (if completed) */
    result?: string;
    /** Error (if failed) */
    error?: string;
    /** Stable anchor for cross-document referencing (e.g. plan-abc:phase-1:step-2) */
    anchor?: string;
}
/**
 * Agent session metadata
 */
interface AgentSession {
    /** Unique session identifier */
    id: string;
    /** Mode for this session */
    mode: AgentMode;
    /** Task description */
    task: string;
    /** Associated plan ID (if any) */
    planId?: string;
    /** Working directory */
    workingDir: string;
    /** Session creation time */
    createdAt: string;
    /** Last update time */
    updatedAt: string;
    /** Session status */
    status: 'active' | 'completed' | 'failed' | 'cancelled';
}
/**
 * Session progress tracking
 */
interface SessionProgress {
    /** Session ID */
    sessionId: string;
    /** Plan ID (if executing from plan) */
    planId?: string;
    /** Current phase being executed */
    currentPhaseId?: string;
    /** Current step being executed */
    currentStepId?: string;
    /** Number of completed phases */
    completedPhases: number;
    /** Total number of phases */
    totalPhases: number;
    /** Number of completed steps */
    completedSteps: number;
    /** Total number of steps */
    totalSteps: number;
    /** Progress percentage (0-100) */
    percentage: number;
    /** When execution started */
    startedAt: string;
    /** Last update time */
    updatedAt: string;
}
/**
 * Extended session for Studio UI (includes run count, last message, etc.)
 */
interface AgentSessionInfo extends AgentSession {
    /** Agent ID this session belongs to */
    agentId: string;
    /** Human-readable session name (auto-generated or user-provided) */
    name?: string;
    /** Number of runs in this session */
    runCount: number;
    /** Last message preview (truncated) */
    lastMessage?: string;
    /** Last activity timestamp */
    lastActivityAt: string;
}
/**
 * Request to list sessions
 */
interface ListSessionsRequest {
    /** Filter by agent ID */
    agentId?: string;
    /** Maximum number of sessions to return */
    limit?: number;
    /** Offset for pagination */
    offset?: number;
    /** Filter by status */
    status?: 'active' | 'completed' | 'failed' | 'cancelled';
}
/**
 * Response with sessions list
 */
interface ListSessionsResponse {
    /** List of sessions */
    sessions: AgentSessionInfo[];
    /** Total count for pagination */
    total: number;
}
/**
 * Request to get session details
 */
interface GetSessionRequest {
    /** Session ID */
    sessionId: string;
}
/**
 * Response with session details
 */
interface GetSessionResponse {
    /** Session details */
    session: AgentSessionInfo;
}
/**
 * Request to create a new session
 */
interface CreateSessionRequest {
    /** Agent ID for this session */
    agentId: string;
    /** Optional session name */
    name?: string;
    /** Initial task (optional, can start empty) */
    task?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Response after creating a session
 */
interface CreateSessionResponse {
    /** Created session */
    session: AgentSessionInfo;
}
/**
 * Response with session plan details
 */
interface GetSessionPlanResponse {
    /** Session ID */
    sessionId: string;
    /** Current plan (if generated) */
    plan: TaskPlan | null;
    /** Canonical markdown plan path (if exists) */
    planPath?: string;
}
/**
 * Request to approve current session plan
 */
interface ApproveSessionPlanRequest {
    /** Optional approval comment */
    comment?: string;
}
/**
 * Response after approving session plan
 */
interface ApproveSessionPlanResponse {
    /** Session ID */
    sessionId: string;
    /** Approved plan */
    plan: TaskPlan;
    /** Timestamp when plan was approved */
    approvedAt: string;
}
/**
 * Request to execute an approved session plan
 */
interface ExecuteSessionPlanRequest {
    /** Optional LLM tier override */
    tier?: 'small' | 'medium' | 'large';
    /** Optional response mode override */
    responseMode?: AgentResponseMode;
    /** Optional verbosity flag */
    verbose?: boolean;
    /** Optional escalation toggle */
    enableEscalation?: boolean;
}
/**
 * Response after scheduling execution of approved plan
 */
interface ExecuteSessionPlanResponse {
    /** Session ID */
    sessionId: string;
    /** Plan ID */
    planId: string;
    /** Run ID */
    runId: string;
    /** Relative WebSocket path for event streaming */
    eventsPath: string;
    /** Run status */
    status: 'started' | 'queued';
    /** Start timestamp */
    startedAt: string;
}
/**
 * Request to generate a detailed spec from an approved plan
 */
interface GenerateSpecRequest {
    /** Optional LLM tier override */
    tier?: 'small' | 'medium' | 'large';
    /** Optional verbosity flag */
    verbose?: boolean;
}
/**
 * Response after starting spec generation
 */
interface GenerateSpecResponse {
    /** Session ID */
    sessionId: string;
    /** Plan ID */
    planId: string;
    /** Spec ID */
    specId: string;
    /** Run ID for tracking background execution */
    runId?: string;
    /** Spec status */
    status: 'generating' | 'draft' | 'failed';
    /** Spec (if synchronous completion) */
    spec?: TaskSpec;
    /** Start timestamp */
    startedAt: string;
    /** Relative WebSocket path for event streaming */
    eventsPath?: string;
}
/**
 * Response for getting a spec
 */
interface GetSpecResponse {
    /** Session ID */
    sessionId: string;
    /** Spec, or null if not yet generated */
    spec: TaskSpec | null;
}
/** Status of an async task */
type AsyncTaskStatus = 'pending' | 'running' | 'completed' | 'failed';
/**
 * An asynchronous task spawned by the agent.
 * Tasks run concurrently via sub-agents and can be polled or awaited.
 */
interface AsyncTask {
    /** Unique task ID */
    id: string;
    /** Human-readable task description */
    description: string;
    /** Current status */
    status: AsyncTaskStatus;
    /** When the task was submitted */
    submittedAt: string;
    /** When the task started running */
    startedAt?: string;
    /** When the task completed or failed */
    completedAt?: string;
    /** Result summary (available when completed) */
    result?: string;
    /** Error message (available when failed) */
    error?: string;
    /** Sub-agent preset used */
    preset?: string;
    /** Token usage */
    tokensUsed?: number;
    /** Files read by the sub-agent */
    filesRead?: string[];
    /** Files modified by the sub-agent */
    filesModified?: string[];
}

/**
 * WebSocket message types for agent event streaming
 */

/**
 * Connection ready message (server → client)
 * Sent when WS connection is established and ready
 */
interface ConnectionReadyMessage {
    type: 'connection:ready';
    payload: {
        runId: string;
        connectedAt: string;
    };
    timestamp: number;
}
/**
 * Run completed message (server → client)
 * Sent when the agent run finishes
 */
interface RunCompletedMessage {
    type: 'run:completed';
    payload: {
        runId: string;
        success: boolean;
        summary: string;
        durationMs: number;
    };
    timestamp: number;
}
/**
 * Error message (server → client)
 */
interface ErrorMessage {
    type: 'error';
    payload: {
        code: string;
        message: string;
        details?: unknown;
    };
    timestamp: number;
}
/**
 * Correction acknowledged message (server → client)
 */
interface CorrectionAckMessage {
    type: 'correction:ack';
    payload: {
        correctionId: string;
        routedTo: string[];
        reason: string;
    };
    timestamp: number;
}
/**
 * Turn snapshot message (server → client)
 * Sent whenever a turn is created or updated (incremental updates)
 */
interface TurnSnapshotMessage {
    type: 'turn:snapshot';
    payload: {
        sessionId: string;
        turn: Turn;
        sequenceNumber: number;
    };
    timestamp: number;
}
/**
 * Conversation snapshot message (server → client)
 * Sent on initial WebSocket connection to provide recent history
 */
interface ConversationSnapshotMessage {
    type: 'conversation:snapshot';
    payload: {
        sessionId: string;
        /** Recent completed turns (last 20) */
        completedTurns: Turn[];
        /** Currently streaming turns */
        activeTurns: Turn[];
        /** Total turns in session */
        totalTurns: number;
        /** Snapshot timestamp */
        timestamp: string;
    };
    timestamp: number;
}
/**
 * Union of all server → client messages
 */
type ServerMessage = ConnectionReadyMessage | RunCompletedMessage | ErrorMessage | CorrectionAckMessage | TurnSnapshotMessage | ConversationSnapshotMessage;
/**
 * User correction message (client → server)
 * User sends a correction/feedback to the orchestrator
 */
interface UserCorrectionMessage {
    type: 'user:correction';
    payload: {
        /** The correction message from user */
        message: string;
        /** Optional: target specific agent (otherwise orchestrator decides) */
        targetAgentId?: string;
        /** Optional: reference to specific event being corrected */
        refEventId?: string;
    };
    timestamp: number;
}
/**
 * Stop request message (client → server)
 */
interface StopRequestMessage {
    type: 'user:stop';
    payload: {
        reason?: string;
    };
    timestamp: number;
}
/**
 * Ping message (client → server) for keepalive
 */
interface PingMessage {
    type: 'ping';
    payload: Record<string, never>;
    timestamp: number;
}
/**
 * Union of all client → server messages
 */
type ClientMessage = UserCorrectionMessage | StopRequestMessage | PingMessage;
/**
 * Request body for POST /run
 */
interface RunRequest {
    /** Task description */
    task: string;
    /** Agent ID to use (optional, defaults to orchestrator) */
    agentId?: string;
    /** Session ID to continue (optional, creates new session if not provided) */
    sessionId?: string;
    /** Working directory (optional) */
    workingDir?: string;
    /** Verbose output */
    verbose?: boolean;
    /** LLM tier (small/medium/large) */
    tier?: 'small' | 'medium' | 'large';
    /** Auto escalate to higher tier when agent is stuck */
    enableEscalation?: boolean;
    /** Adaptive elevation of helper LLM nodes (small -> medium on risk signals) */
    smartTiering?: AgentSmartTieringConfig;
    /** Answer style depth (auto/brief/deep) */
    responseMode?: AgentResponseMode;
}
/**
 * Response for POST /run
 */
interface RunResponse {
    /** Unique run ID */
    runId: string;
    /** Session ID (existing or newly created) */
    sessionId: string;
    /**
     * Relative WebSocket path for event streaming (e.g. "/v1/ws/plugins/agents/session/:id").
     * Clients construct the full WS URL from their own base URL + this path.
     */
    eventsPath: string;
    /** Run status */
    status: 'started' | 'queued';
    /** Timestamp */
    startedAt: string;
}
/**
 * Request body for POST /run/:runId/correct
 */
interface CorrectionRequest {
    /** The correction message */
    message: string;
    /** Optional: target specific agent */
    targetAgentId?: string;
}
/**
 * Response for POST /run/:runId/correct
 */
interface CorrectionResponse {
    /** Unique correction ID */
    correctionId: string;
    /** Agents that received the correction */
    routedTo: string[];
    /** Routing reason from LLM */
    reason: string;
    /** Whether correction was applied */
    applied: boolean;
}
/**
 * Request body for POST /run/:runId/stop
 */
interface StopRequest {
    /** Reason for stopping (optional) */
    reason?: string;
}
/**
 * Response for POST /run/:runId/stop
 */
interface StopResponse {
    /** Whether stop was successful */
    stopped: boolean;
    /** Run ID */
    runId: string;
    /** Final status */
    finalStatus: 'stopped' | 'already_completed' | 'not_found';
}
/**
 * Response for GET /run/:runId
 */
interface RunStatusResponse {
    /** Run ID */
    runId: string;
    /** Current status */
    status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped';
    /** Task description */
    task: string;
    /** Start time */
    startedAt: string;
    /** End time (if completed) */
    completedAt?: string;
    /** Duration in ms (if completed) */
    durationMs?: number;
    /** Result summary (if completed) */
    summary?: string;
    /** Error message (if failed) */
    error?: string;
    /** Active agents (if running) */
    activeAgents?: Array<{
        id: string;
        task: string;
        status: 'running' | 'waiting';
    }>;
}
/**
 * Agent specification (for listing available agents)
 */
interface AgentSpecification {
    /** Unique agent identifier */
    id: string;
    /** Human-readable name */
    name: string;
    /** Description of agent capabilities */
    description: string;
    /** List of tools available to this agent */
    tools: string[];
    /** Agent tier/capability level */
    tier?: 'small' | 'medium' | 'large';
}
/**
 * Response for GET /agents
 */
interface ListAgentsResponse {
    /** Available agents */
    agents: AgentSpecification[];
    /** Total count */
    total: number;
}

/**
 * Zod schemas for validation (future use)
 */
declare const schemas: {};

/**
 * REST API & WebSocket route constants for agents plugin
 */
/**
 * Base path for agents REST API routes
 */
declare const AGENTS_BASE_PATH: "/v1/plugins/agents";
/**
 * Base path for agents WebSocket channels
 */
declare const AGENTS_WS_BASE_PATH: "/v1/ws/plugins/agents";
/**
 * REST API route paths (relative to basePath)
 */
declare const AGENTS_ROUTES: {
    /** GET - List all available agents */
    readonly LIST: "";
    /** POST /run - Start a new agent run */
    readonly RUN: "/run";
    /** GET /run/:runId - Get run status */
    readonly RUN_STATUS: "/run/:runId";
    /** POST /run/:runId/correct - Send user correction to running agent */
    readonly CORRECT: "/run/:runId/correct";
    /** POST /run/:runId/stop - Stop running agent */
    readonly STOP: "/run/:runId/stop";
    /** GET /sessions - List all sessions */
    readonly SESSIONS_LIST: "/sessions";
    /** GET /sessions/:sessionId - Get session details */
    readonly SESSION_GET: "/sessions/:sessionId";
    /** POST /sessions - Create new session */
    readonly SESSION_CREATE: "/sessions";
    /** GET /sessions/:sessionId/turns - Get session turns (turn-based UI) */
    readonly SESSION_TURNS: "/sessions/:sessionId/turns";
    /** GET /sessions/:sessionId/changes - List file changes for session */
    readonly SESSION_CHANGES: "/sessions/:sessionId/changes";
    /** GET /sessions/:sessionId/changes/:changeId/diff - Get unified diff for a specific file change */
    readonly SESSION_CHANGE_DIFF: "/sessions/:sessionId/changes/:changeId/diff";
    /** POST /sessions/:sessionId/rollback - Rollback file changes */
    readonly SESSION_ROLLBACK: "/sessions/:sessionId/rollback";
    /** POST /sessions/:sessionId/approve - Approve file changes */
    readonly SESSION_APPROVE: "/sessions/:sessionId/approve";
    /** GET /sessions/:sessionId/plan - Get current session plan */
    readonly SESSION_PLAN_GET: "/sessions/:sessionId/plan";
    /** POST /sessions/:sessionId/plan/approve - Approve current session plan */
    readonly SESSION_PLAN_APPROVE: "/sessions/:sessionId/plan/approve";
    /** POST /sessions/:sessionId/plan/execute - Execute approved session plan */
    readonly SESSION_PLAN_EXECUTE: "/sessions/:sessionId/plan/execute";
    /** POST /sessions/:sessionId/plan/spec - Generate detailed spec from approved plan */
    readonly SESSION_PLAN_SPEC: "/sessions/:sessionId/plan/spec";
    /** GET /sessions/:sessionId/plan/spec - Get generated spec */
    readonly SESSION_PLAN_SPEC_GET: "/sessions/:sessionId/spec";
};
/**
 * WebSocket channel paths (relative to wsBasePath)
 */
declare const AGENTS_WS_CHANNELS: {
    /** WS /session/:sessionId - Persistent session stream (all runs in session) */
    readonly SESSION_STREAM: "/session/:sessionId";
};
/**
 * Build full REST route path
 */
declare function buildRestRoute(route: keyof typeof AGENTS_ROUTES, params?: Record<string, string>): string;
/**
 * Build full WebSocket channel path
 */
declare function buildWsChannel(channel: keyof typeof AGENTS_WS_CHANNELS, params?: Record<string, string>): string;

/**
 * Analytics event constants for agent system
 */
/**
 * Analytics event IDs
 */
declare const AGENT_ANALYTICS_EVENTS: {
    readonly RUN_STARTED: "agent.run.started";
    readonly RUN_COMPLETED: "agent.run.completed";
    readonly RUN_FAILED: "agent.run.failed";
    readonly RUN_STOPPED: "agent.run.stopped";
    readonly CORRECTION_SENT: "agent.correction.sent";
    readonly CORRECTION_APPLIED: "agent.correction.applied";
    readonly CORRECTION_REJECTED: "agent.correction.rejected";
    readonly WS_CONNECTED: "agent.ws.connected";
    readonly WS_DISCONNECTED: "agent.ws.disconnected";
    readonly AGENT_SPAWNED: "agent.spawned";
    readonly AGENT_COMPLETED: "agent.completed";
    readonly TOOL_CALLED: "agent.tool.called";
    readonly TIER_ESCALATED: "agent.tier.escalated";
};
type AgentAnalyticsEvent = typeof AGENT_ANALYTICS_EVENTS[keyof typeof AGENT_ANALYTICS_EVENTS];

/**
 * AI-friendly response types for trace CLI commands
 *
 * All trace commands support --json flag and return structured responses
 * with this format for agent-to-agent debugging.
 */

/**
 * Base response for all trace commands (AI-friendly)
 */
interface TraceCommandResponse<T = unknown> {
    /** Whether command succeeded */
    success: boolean;
    /** Command name (e.g., "trace:stats") */
    command: string;
    /** Task ID that was analyzed */
    taskId: string;
    /** Command-specific data */
    data?: T;
    /** Error details (if success = false) */
    error?: {
        code: string;
        message: string;
        details?: unknown;
    };
    /** Summary for quick reading */
    summary: {
        /** One-liner summary */
        message: string;
        /** Severity level */
        severity: 'info' | 'warning' | 'error' | 'critical';
        /** Whether user should take action */
        actionable: boolean;
    };
}
/**
 * trace:stats response
 */
interface StatsResponse {
    taskId: string;
    status: 'success' | 'failed' | 'incomplete';
    iterations: {
        total: number;
        completed: number;
    };
    llm: {
        calls: number;
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
    };
    tools: {
        totalCalls: number;
        byTool: Record<string, number>;
        successful: number;
        failed: number;
    };
    timing: {
        startedAt: string;
        completedAt: string;
        totalDurationMs: number;
        durationFormatted: string;
    };
    cost: {
        total: number;
        currency: 'USD';
    };
    errors: number;
}
/**
 * trace:filter response
 */
interface FilterResponse {
    taskId: string;
    eventType: string;
    events: DetailedTraceEntry[];
    count: number;
}
/**
 * trace:tail response
 */
interface TailResponse {
    taskId: string;
    lines: number;
    events: DetailedTraceEntry[];
}
/**
 * trace:iteration response
 */
interface IterationResponse {
    taskId: string;
    iteration: number;
    events: DetailedTraceEntry[];
    summary: {
        eventCount: number;
        llmCalls: number;
        toolCalls: number;
        errors: number;
        durationMs: number;
    };
}
/**
 * trace:analyze response (pattern detection)
 */
interface AnalyzeResponse {
    taskId: string;
    issues: Array<{
        type: 'retry_loop' | 'tool_filtering_issue' | 'context_loss' | 'premature_stop';
        severity: 'low' | 'medium' | 'high' | 'critical';
        occurrences: number;
        iterations: number[];
        pattern: string;
        cause: string;
        fix: string;
        examples: unknown[];
    }>;
    recommendations: Array<{
        priority: 'low' | 'medium' | 'high' | 'critical';
        action: string;
        rationale: string;
    }>;
    metrics: {
        efficiencyScore: number;
        retryRate: number;
        contextRetention: number;
        toolUtilization: number;
    };
}
/**
 * trace:compare response
 */
interface CompareResponse {
    taskId1: string;
    taskId2: string;
    differences: {
        iterations: {
            task1: number;
            task2: number;
            delta: number;
        };
        llmCalls: {
            task1: number;
            task2: number;
            delta: number;
        };
        toolCalls: {
            task1: number;
            task2: number;
            delta: number;
        };
        cost: {
            task1: number;
            task2: number;
            delta: number;
            deltaPercent: number;
        };
        duration: {
            task1: number;
            task2: number;
            delta: number;
            deltaPercent: number;
        };
    };
    divergencePoints: Array<{
        iteration: number;
        reason: string;
        task1Event: unknown;
        task2Event: unknown;
    }>;
    summary: {
        similar: boolean;
        majorDifferences: string[];
    };
}
/**
 * trace:snapshot response
 */
interface SnapshotResponse {
    taskId: string;
    iteration: number;
    timestamp: string;
    snapshot: {
        messages: Array<{
            role: 'system' | 'user' | 'assistant';
            content: string;
        }>;
        memory: {
            facts: string[];
            findings: string[];
            filesRead: string[];
            toolsUsed: Record<string, number>;
        };
        config: {
            maxIterations: number;
            mode: string;
            temperature: number;
        };
        availableTools: string[];
    };
    restoration: {
        canRestore: boolean;
        requiredData: string[];
    };
}
/**
 * trace:export response
 */
interface ExportResponse {
    taskId: string;
    format: 'json' | 'markdown' | 'html';
    outputFile: string;
    size: number;
    eventCount: number;
}
/**
 * trace:replay response (for programmatic replay)
 */
interface ReplayResponse {
    taskId: string;
    iterations: Array<{
        iteration: number;
        timestamp: string;
        events: DetailedTraceEntry[];
        summary: string;
    }>;
    totalDurationMs: number;
}
/**
 * Standard error codes for trace commands
 */
declare const TraceErrorCodes: {
    readonly TRACE_NOT_FOUND: "TRACE_NOT_FOUND";
    readonly INVALID_TASK_ID: "INVALID_TASK_ID";
    readonly INVALID_EVENT_TYPE: "INVALID_EVENT_TYPE";
    readonly INVALID_ITERATION: "INVALID_ITERATION";
    readonly CORRUPTED_TRACE: "CORRUPTED_TRACE";
    readonly IO_ERROR: "IO_ERROR";
    readonly PARSE_ERROR: "PARSE_ERROR";
    readonly MISSING_INDEX: "MISSING_INDEX";
    readonly FILE_TOO_LARGE: "FILE_TOO_LARGE";
};
type TraceErrorCode = (typeof TraceErrorCodes)[keyof typeof TraceErrorCodes];

/**
 * Control flow types for Agent v2 middleware pipeline and execution loop.
 *
 * ControlAction is the unified return type for middleware hooks and execution decisions.
 * StopPriority defines deterministic ordering when multiple stop conditions fire simultaneously.
 */
/**
 * Unified control action for middleware pipeline and execution loop.
 *
 * - 'continue' — proceed with current iteration
 * - 'stop'     — stop the execution loop gracefully
 * - 'escalate' — request tier escalation (small → medium → large)
 * - 'handoff'  — hand off to a different agent (sub-agent orchestration)
 */
type ControlAction = 'continue' | 'stop' | 'escalate' | 'handoff';
/**
 * Stop condition priorities (lower number = higher priority).
 *
 * When multiple conditions fire in the same iteration, the evaluator checks ALL
 * and returns the one with the highest priority (lowest numeric value).
 * Tie-break is impossible because enum values are unique.
 *
 * Example collision: report + hard_budget → REPORT_COMPLETE (1 < 2).
 */
declare enum StopPriority {
    /** User cancelled via AbortController */
    ABORT_SIGNAL = 0,
    /** Agent called the `report` tool — task is done */
    REPORT_COMPLETE = 1,
    /** Token hard limit reached */
    HARD_BUDGET = 2,
    /** Maximum iterations reached */
    MAX_ITERATIONS = 3,
    /** Same tool calls repeated 3+ times in a row */
    LOOP_DETECTED = 4,
    /** Agent produced no tool calls — implicit completion */
    NO_TOOL_CALLS = 5
}
/**
 * A fired stop condition with its priority and metadata.
 */
interface StopConditionResult {
    /** Which condition fired */
    priority: StopPriority;
    /** Human-readable reason */
    reason: string;
    /** Machine-readable code for analytics */
    reasonCode: string;
    /** Additional metadata (e.g., report answer, loop count) */
    metadata?: Record<string, unknown>;
}
/**
 * Failure policy for a middleware.
 *
 * - 'fail-open'   — if the middleware throws, log and continue the pipeline
 * - 'fail-closed' — if the middleware throws, stop the entire execution
 */
type MiddlewareFailPolicy = 'fail-open' | 'fail-closed';
/**
 * Per-middleware configuration for pipeline behavior.
 */
interface MiddlewareConfig {
    /** What happens when this middleware throws (default: 'fail-open') */
    failPolicy: MiddlewareFailPolicy;
    /** Maximum time for any single hook invocation in ms (default: 5000) */
    timeoutMs?: number;
    /** Whether the middleware is safe to retry on failure */
    idempotent?: boolean;
}
/**
 * Feature flags controlling which experimental middlewares are active.
 * All default to false unless explicitly enabled.
 */
interface FeatureFlags {
    /** Two-tier memory: FactSheet (hot) + ArchiveMemory (cold) */
    twoTierMemory: boolean;
    /** TODO sync coordinator — nudges agent toward todo discipline */
    todoSync: boolean;
    /** Search signal tracker — discovery vs action classification */
    searchSignal: boolean;
    /** Reflection engine — adaptive LLM-driven behavior */
    reflection: boolean;
    /** Task classifier — intent inference (action/discovery/analysis) */
    taskClassifier: boolean;
    /** Smart summarizer — progressive conversation compression */
    smartSummarizer: boolean;
    /** Tier escalation — auto-escalate small → medium → large */
    tierEscalation: boolean;
}
/**
 * Default feature flags — conservative, all experimental features off.
 */
declare const DEFAULT_FEATURE_FLAGS: FeatureFlags;
/**
 * Result of a single ExecutionLoop run.
 * Uses discriminated union on `outcome` instead of thrown exceptions.
 */
type LoopResult<T = unknown> = {
    outcome: 'complete';
    result: T;
} | {
    outcome: 'escalate';
    reason: string;
} | {
    outcome: 'handoff';
    targetAgentId: string;
    context: Record<string, unknown>;
};

/**
 * Agent configuration types for kb.config.json
 */

/**
 * Storage configuration for file history snapshots
 */
interface FileHistoryStorageConfig {
    /** Base path for session storage (default: .kb/agents/sessions) */
    basePath?: string;
    /** Maximum number of sessions to keep (default: 30) */
    maxSessions?: number;
    /** Maximum age of sessions in days (default: 30) */
    maxAgeDays?: number;
    /** Maximum total storage size in MB (default: 500) */
    maxTotalSizeMb?: number;
    /** Enable compression for old snapshots (default: true) */
    compressOldSnapshots?: boolean;
}
/**
 * Escalation level configuration
 */
interface EscalationLevelConfig {
    /** Enable this escalation level */
    enabled: boolean;
    /** Confidence threshold for this level (0-1) */
    confidenceThreshold: number;
    /** Maximum duration in milliseconds */
    maxDurationMs: number;
}
/**
 * Human escalation configuration
 */
interface HumanEscalationConfig {
    /** Enable human escalation */
    enabled: boolean;
    /** Auto-escalate to human after this many milliseconds */
    autoEscalateAfterMs?: number;
}
/**
 * Escalation policy for adaptive conflict resolution
 */
interface EscalationPolicy {
    /** Level 1: Auto-resolve (disjoint changes, 60%, <10ms) */
    level1AutoResolve: EscalationLevelConfig;
    /** Level 2: LLM-merge (overlapping changes, 30%, 2-5s) */
    level2LLMMerge: EscalationLevelConfig;
    /** Level 3: Agent coordination (conflicting intent, 8%, 10-30s) */
    level3AgentCoordination: EscalationLevelConfig;
    /** Level 4: Human escalation (unresolvable, 2%) */
    level4HumanEscalation: HumanEscalationConfig;
}
/**
 * Conflict resolution configuration
 */
interface ConflictResolutionConfig {
    /** Default strategy: 'adaptive' | 'skip-conflicts' | 'force-overwrite' */
    defaultStrategy: 'adaptive' | 'skip-conflicts' | 'force-overwrite';
    /** Escalation policy for adaptive resolution */
    escalationPolicy: EscalationPolicy;
}
/**
 * File history configuration
 */
interface FileHistoryConfig {
    /** Enable file history tracking */
    enabled: boolean;
    /** Storage configuration */
    storage: FileHistoryStorageConfig;
    /** Conflict resolution configuration */
    conflictResolution: ConflictResolutionConfig;
}
/**
 * Agents plugin configuration
 */
interface AgentsPluginConfig {
    /** Enable agents plugin */
    enabled: boolean;
    /** Adaptive helper-node elevation policy (small -> medium on risk) */
    smartTiering?: AgentSmartTieringConfig;
    /** Token budget policy for long-running tasks */
    tokenBudget?: AgentTokenBudgetConfig;
    /** File history tracking configuration */
    fileHistory: FileHistoryConfig;
}
/**
 * Default configuration values
 */
declare const DEFAULT_FILE_HISTORY_CONFIG: Required<FileHistoryConfig>;
declare const DEFAULT_AGENT_TOKEN_BUDGET_CONFIG: Required<Omit<AgentTokenBudgetConfig, 'maxTokens'>>;

/**
 * ToolPack contract types for Agent v2 extensible tool system.
 *
 * ToolPack groups tools with namespace, priority, conflict resolution,
 * and permissions. ToolManager registers packs and enforces permissions
 * at a single point.
 */

/**
 * A packaged group of tools with namespace isolation and permissions.
 *
 * Examples:
 *   { id: 'core', namespace: 'core', priority: 100 }
 *   { id: 'kb-labs', namespace: 'kb', priority: 50 }
 *   { id: 'mcp:github', namespace: 'mcp.github', priority: 30 }
 */
interface ToolPack {
    /** Unique pack identifier */
    readonly id: string;
    /** Namespace prefix for tool resolution (e.g., 'core', 'kb', 'mcp.github') */
    readonly namespace: string;
    /** Semver version */
    readonly version: string;
    /** Higher number = higher priority when overriding conflicting tool names */
    readonly priority: number;
    /** What to do when tool names conflict with another pack */
    readonly conflictPolicy: ToolConflictPolicy;
    /** Tools in this pack */
    readonly tools: PackedTool[];
    /** Declared capabilities (e.g., ['filesystem', 'search', 'shell']) */
    readonly capabilities?: string[];
    /** Permission constraints for this pack's tools */
    readonly permissions?: ToolPermissions;
    /** Whether this pack should be active (checked at registration time) */
    enabled?(): boolean;
    /** Called once after registration */
    initialize?(): Promise<void>;
    /** Called on shutdown */
    dispose?(): Promise<void>;
}
/**
 * A single tool within a ToolPack.
 */
interface PackedTool {
    /** The OpenAI-compatible function definition */
    readonly definition: ToolDefinition;
    /** Whether this tool only reads state (no side effects) */
    readonly readOnly?: boolean;
    /**
     * Whether this tool is safe to execute concurrently with other concurrent-safe tools.
     * When true, multiple calls can run via Promise.all() in the same iteration.
     * When false (default), tool executes sequentially.
     * Read-only tools are typically concurrent-safe.
     */
    readonly concurrencySafe?: boolean;
    /** Capability category */
    readonly capability?: string;
    /** Execute the tool */
    execute(input: Record<string, unknown>): Promise<ToolResult>;
}
/**
 * How to resolve tool name conflicts between packs.
 *
 * - 'error': Throw at registration time (strict mode)
 * - 'override': Higher-priority pack's tool wins, lower is shadowed
 * - 'namespace-prefix': Both tools available as `namespace.toolName`
 */
type ToolConflictPolicy = 'error' | 'override' | 'namespace-prefix';
/**
 * Permission constraints enforced by ToolManager (not by individual tools).
 */
interface ToolPermissions {
    /** Allowed filesystem paths (glob patterns). Empty = no fs access. */
    allowedPaths?: string[];
    /** Denied shell commands (exact match or prefix). */
    deniedCommands?: string[];
    /** Whether network access is allowed (default: true for core, false for MCP) */
    networkAllowed?: boolean;
    /** Whether all tool calls should be logged to audit trail */
    auditTrail?: boolean;
}
/**
 * Filter options for ToolManager.getTools().
 */
interface ToolFilter {
    /** Only return read-only tools */
    readOnly?: boolean;
    /** Only return tools with this capability */
    capability?: string;
    /** Only return tools from this namespace */
    namespace?: string;
}
/**
 * A tool after namespace resolution, ready for execution.
 * Produced by ToolManager.register() and used by ToolManager.execute().
 */
interface ResolvedTool {
    /** Fully qualified name (may include namespace prefix) */
    readonly qualifiedName: string;
    /** Original short name from definition */
    readonly shortName: string;
    /** Pack this tool belongs to */
    readonly packId: string;
    /** Pack namespace */
    readonly namespace: string;
    /** The tool definition (with possibly updated name) */
    readonly definition: ToolDefinition;
    /** Whether this tool only reads state */
    readonly readOnly: boolean;
    /** Whether this tool is safe to execute concurrently with other concurrent-safe tools */
    readonly concurrencySafe: boolean;
    /** Capability category */
    readonly capability?: string;
    /** Execute the tool */
    execute(input: Record<string, unknown>): Promise<ToolResult>;
}

/**
 * Runtime-centric contracts for the new SDK kernel/store architecture.
 *
 * These contracts intentionally model continuity state explicitly instead of
 * relying on transcript replay or middleware-local memory.
 */

type RepositoryTopology = 'single-package' | 'monorepo' | 'polyrepo' | 'workspace' | 'unknown';
type ToolCapability = 'filesystem' | 'search' | 'code-navigation' | 'shell' | 'memory' | 'planning' | 'todo' | 'interaction' | 'reporting' | 'delegation';
interface RepositoryStack {
    languages: string[];
    frameworks: string[];
    runtimes: string[];
    packageManagers: string[];
    buildTools: string[];
    testTools: string[];
}
interface RepositorySignal {
    name: string;
    confidence: number;
    sources: string[];
}
interface RepositoryFingerprints {
    ecosystems: RepositorySignal[];
    languages: RepositorySignal[];
    frameworks: RepositorySignal[];
    runtimes: RepositorySignal[];
    packageManagers: RepositorySignal[];
    buildTools: RepositorySignal[];
    testTools: RepositorySignal[];
}
interface RepositoryWorkspaceLayout {
    rootPath: string;
    packageRoots: string[];
    appRoots: string[];
    libraryRoots: string[];
    infraRoots: string[];
    docsRoots: string[];
}
interface RepositoryConventions {
    hasAdr: boolean;
    hasOpenApi: boolean;
    hasCi: boolean;
    hasLinting: boolean;
    hasFormatting: boolean;
}
interface RepositoryModel {
    topology: RepositoryTopology;
    stack: RepositoryStack;
    fingerprints: RepositoryFingerprints;
    workspace: RepositoryWorkspaceLayout;
    conventions: RepositoryConventions;
    riskSignals: string[];
    detectedAt: string;
    sources: string[];
}
type TurnKind = 'new_task' | 'follow_up' | 'correction' | 'constraint' | 'mixed';
interface TurnInterpretation {
    kind: TurnKind;
    shouldPersist: boolean;
    persistenceKind?: 'correction' | 'constraint';
    persistStrategy?: 'record_directly' | 'explicit_commit';
    content?: string;
    invalidates?: string[];
    confidence: number;
    suggestedMode?: AgentMode | 'assistant' | 'autonomous' | 'spec' | 'debug';
    suggestedSkills?: string[];
    suggestedPromptProfile?: string;
    suggestedToolCapabilities?: string[];
    rationale?: string;
}
interface RoutingHints {
    suggestedMode?: AgentMode | 'assistant' | 'autonomous' | 'spec' | 'debug';
    suggestedSkills: string[];
    suggestedPromptProfile?: string;
    suggestedToolCapabilities: string[];
    source: 'turn_interpretation';
    confidence: number;
    updatedAt: string;
}
interface MemoryRollup {
    generatedAt: string;
    turnCount?: number;
    toolCallCount?: number;
    completedActionCount: number;
    prunedEvidenceCount: number;
    summary: string;
}
interface EvidenceRequirements {
    allowsMemoryOnlyRecall: boolean;
    needsDirectToolEvidence: boolean;
    needsFileBackedClaims: boolean;
    allowsInference: boolean;
    maxUnsupportedClaims: number;
}
interface ClaimVerificationResult {
    verdict: 'allow' | 'warn' | 'block';
    rationale: string;
    requirements: EvidenceRequirements;
    supportedClaims: string[];
    unsupportedClaims: string[];
}
type RunEvaluationRecommendation = 'continue' | 'narrow' | 'synthesize';
interface IterationSnapshot {
    iteration: number;
    maxIterations: number;
    toolNames: string[];
    toolSignature: string;
    totalTokens?: number;
    evidenceCount: number;
    evidenceDelta: number;
    filesReadCount: number;
    filesModifiedCount: number;
    filesCreatedCount: number;
    newEvidence: boolean;
    repeatsWithoutEvidence: number;
    repeatNoEvidenceCount: number;
    lastIterationSummary?: string;
}
interface RunEvaluation {
    evidenceGain: number;
    readinessScore: number;
    repeatedStrategy: boolean;
    recommendation: RunEvaluationRecommendation;
    rationale: string;
}
interface PromptContextSelection {
    includeObjective: boolean;
    includeSessionRollup: boolean;
    includeConstraints: boolean;
    includeRoutingHints: boolean;
    includeCorrections: boolean;
    includeDecisions: boolean;
    includeEvidence: boolean;
    includePreviousRunToolUsage: boolean;
    includePreviousRunHandoff: boolean;
    includeWorkingSummary: boolean;
    includePendingActions: boolean;
    correctionWindow: number;
    decisionWindow: number;
    evidenceWindow: number;
    toolUsageWindow: number;
    pendingActionWindow: number;
    rationale?: string;
}
type KernelEntryKind = 'objective' | 'constraint' | 'correction' | 'assumption' | 'decision' | 'evidence' | 'question' | 'todo' | 'handoff' | 'child-result' | 'summary';
interface CorrectionRecord {
    id: string;
    content: string;
    timestamp: string;
    invalidates?: string[];
    source: 'user' | 'system';
}
interface AssumptionRecord {
    id: string;
    content: string;
    status: 'active' | 'invalidated' | 'accepted';
    createdAt: string;
    invalidatedAt?: string;
    invalidatedBy?: string;
}
interface DecisionRecord {
    id: string;
    content: string;
    createdAt: string;
    source: 'agent' | 'user' | 'tool';
    pinned?: boolean;
}
interface EvidenceRecord {
    id: string;
    summary: string;
    source: string;
    createdAt: string;
    toolName?: string;
    toolInputSummary?: string;
    artifact?: Record<string, unknown>;
    filePaths?: string[];
    pinned?: boolean;
}
interface OpenQuestionRecord {
    id: string;
    content: string;
    createdAt: string;
    status: 'open' | 'resolved';
}
interface PendingActionRecord {
    id: string;
    content: string;
    createdAt: string;
    status: 'pending' | 'in_progress' | 'done' | 'blocked';
}
interface RunHandoff {
    runId: string;
    mode: AgentMode | 'assistant' | 'autonomous';
    createdAt: string;
    summary: string;
    filesRead?: string[];
    filesModified?: string[];
    filesCreated?: string[];
    importantEvidenceIds?: string[];
}
interface KernelMemoryState {
    corrections: CorrectionRecord[];
    assumptions: AssumptionRecord[];
    decisions: DecisionRecord[];
    evidence: EvidenceRecord[];
    openQuestions: OpenQuestionRecord[];
    pendingActions: PendingActionRecord[];
    latestSummary?: string;
}
interface KernelState {
    version: number;
    sessionId: string;
    workingDir: string;
    mode: AgentMode | 'assistant' | 'autonomous';
    currentTask: string;
    objective?: string;
    constraints: string[];
    routingHints?: RoutingHints;
    rollup?: MemoryRollup;
    memory: KernelMemoryState;
    handoff?: RunHandoff;
    childResults: RunHandoff[];
    updatedAt: string;
}
interface ToolResultArtifact {
    status: 'success' | 'error';
    summary: string;
    artifact?: Record<string, unknown>;
    evidence: EvidenceRecord[];
    mutations?: {
        filesRead?: string[];
        filesModified?: string[];
        filesCreated?: string[];
    };
    followUpHints?: string[];
}
interface ToolCallRecord {
    id: string;
    sessionId: string;
    runId?: string;
    timestamp: string;
    toolName: string;
    input: Record<string, unknown>;
    artifact: ToolResultArtifact;
}
interface SessionSnapshot {
    sessionId: string;
    mode: AgentMode | 'assistant' | 'autonomous';
    updatedAt: string;
    kernel: KernelState;
}
interface RuntimeTurnRecord {
    id: string;
    sessionId: string;
    runId?: string;
    role: 'user' | 'assistant' | 'system';
    content: string;
    timestamp: string;
    metadata?: Record<string, unknown>;
}

/**
 * Sub-agent spawn types — shared between agent-core and agent-tools.
 *
 * These types flow as plain data across the package boundary:
 * - agent-tools resolves preset → allowedTools (knows tool names)
 * - agent-core uses allowedTools to configure child runner (knows budget/lifecycle)
 */
/**
 * Built-in sub-agent capability presets.
 * - 'research' — read-only: search, read files, memory. No writes.
 * - 'execute'  — full tool set: read + write + shell. For implementation tasks.
 * - 'review'   — read + shell: for code review, running linters/tests.
 */
type SubAgentPreset = 'research' | 'execute' | 'review';
/**
 * Request to spawn a sub-agent.
 * Flows: tool layer (resolves preset) → core layer (enforces budget, creates child).
 *
 * All fields except `task` are optional for backward compatibility:
 * `{ task: "..." }` works as before (preset='research', budgetFraction=0.5).
 */
interface SpawnAgentRequest {
    /** Clear task description — the sub-agent has no context about parent's work. */
    task: string;
    /** Preset determines which tools the child gets. Default: 'research'. */
    preset?: SubAgentPreset;
    /**
     * Explicit tool allowlist — resolved from preset by the tool layer.
     * Core layer passes this to child's ToolContext.allowedTools.
     */
    allowedTools?: string[];
    /** Max iterations for the child. Default: from preset. */
    maxIterations?: number;
    /** Working directory relative to project root. */
    workingDir?: string;
    /**
     * Budget cap: fraction (0.0–1.0) of parent's REMAINING token budget.
     * Default: 0.5 (50%). 0 = unlimited (legacy behavior).
     */
    budgetFraction?: number;
}
/**
 * Structured result returned from sub-agent to parent.
 * Preserves all useful data from TaskResult — no stripping.
 */
interface SpawnAgentResult {
    success: boolean;
    /** 1-3 sentence summary for parent context and Status Block. */
    summary: string;
    /** Files the sub-agent read. */
    filesRead: string[];
    /** Files the sub-agent modified. */
    filesModified: string[];
    /** Files the sub-agent created. */
    filesCreated: string[];
    iterations: number;
    tokensUsed: number;
    /** Wall-clock duration in milliseconds. */
    durationMs: number;
    /** Error message if success=false. */
    error?: string;
    /** Preset that was used. */
    preset: SubAgentPreset;
}

export { AGENTS_BASE_PATH, AGENTS_ROUTES, AGENTS_WS_BASE_PATH, AGENTS_WS_CHANNELS, AGENT_ANALYTICS_EVENTS, AGENT_MODES, type AgentAnalyticsEvent, type AgentConfig, type AgentEndEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventCallback, type AgentEventEmitter, type AgentEventType, type AgentMemory, type AgentMode, type AgentResponseMode, type AgentSession, type AgentSessionInfo, type AgentSmartTieringConfig, type AgentSpecBudgetConfig, type AgentSpecification, type AgentStartEvent, type AgentTokenBudgetConfig, type AgentsPluginConfig, type AnalyzeResponse, type ApproveSessionPlanRequest, type ApproveSessionPlanResponse, type ArchiveEntry, type ArchiveStoreEvent, type AssumptionRecord, type AsyncTask, type AsyncTaskStatus, type BaseTraceEntry, type ClaimVerificationResult, type ClientMessage, type CompareResponse, type ConflictInfo, type ConflictResolutionConfig, type ConnectionReadyMessage, type ContextSnapshotEvent, type ContextTrimEvent, type ControlAction, type ConversationSnapshotMessage, type CorrectionAckMessage, type CorrectionRecord, type CorrectionRequest, type CorrectionResponse, type CreateSessionRequest, type CreateSessionResponse, DEFAULT_AGENT_TOKEN_BUDGET_CONFIG, DEFAULT_FEATURE_FLAGS, DEFAULT_FILE_HISTORY_CONFIG, DEFAULT_VERIFICATION_THRESHOLDS, type DebugContext, type DecisionPointEvent, type DecisionRecord, type DecompositionDecision, type DecompositionTaskType, type DetailedTraceEntry, type EditContext, type ErrorCapturedEvent, type ErrorMessage, type ErrorStep, type EscalationLevelConfig, type EscalationPolicy, type EvidenceRecord, type EvidenceRequirements, type ExecuteContext, type ExecuteSessionPlanRequest, type ExecuteSessionPlanResponse, type ExecutionMode, type ExecutionPlan, type ExportResponse, type FactAddedEvent, type FactCategory, type FactSheetEntry, type FeatureFlags, type FileChangeSummary, type FileHistoryConfig, type FileHistoryStorageConfig, type FilterResponse, type GenerateSpecRequest, type GenerateSpecResponse, type GetSessionPlanResponse, type GetSessionRequest, type GetSessionResponse, type GetSpecResponse, type HumanEscalationConfig, type IterationDetailEvent, type IterationEndEvent, type IterationResponse, type IterationSnapshot, type IterationStartEvent, type KernelEntryKind, type KernelMemoryState, type KernelState, type LLMCallEvent, type LLMChunkEvent, type LLMDebugEvent, type LLMEndEvent, type LLMStartEvent, type LLMStreamEvent, type LLMTier, type LLMValidationEvent, type ListAgentsResponse, type ListSessionsRequest, type ListSessionsResponse, type LoopResult, type MemoryCategory, type MemoryConfig, type MemoryEntry, type MemoryReadEvent, type MemoryRollup, type MemorySnapshotEvent, type MemorySummary, type MemoryWriteEvent, type MiddlewareConfig, type MiddlewareDecisionEvent, type MiddlewareFailPolicy, type ModeConfig, type ModeContext, type OpenQuestionRecord, type PackedTool, type PendingActionRecord, type PersistentMemory, type Phase, type PingMessage, type PlanContext, type PlanUpdate, type PlanUpdateAction, type ProgressUpdateEvent, type ProjectContext, type PromptContextSelection, type PromptDiffEvent, type QualityMetrics, type ReflectionResult, type ReplayResponse, type RepositoryConventions, type RepositoryFingerprints, type RepositoryModel, type RepositorySignal, type RepositoryStack, type RepositoryTopology, type RepositoryWorkspaceLayout, type ResolvedTool, type ResultProcessor, type RollbackResult, type RoutingHints, type RunCompletedMessage, type RunEvaluation, type RunEvaluationRecommendation, type RunHandoff, type RunRequest, type RunResponse, type RunStatusResponse, type RuntimeTurnRecord, type ServerMessage, type SessionEntry, type SessionProgress, type SessionSnapshot, type SnapshotResponse, type SpawnAgentRequest, type SpawnAgentResult, type SpecChange, type SpecSection, type StatsResponse, type StatusChangeEvent, type Step, type StopConditionResult, StopPriority, type StopRequest, type StopRequestMessage, type StopResponse, type StoppingAnalysisEvent, type SubAgentPreset, type SubAgentStep, type Subtask, type SubtaskEndEvent, type SubtaskStartEvent, type SummarizationLLMCallEvent, type SummarizationResultEvent, type SynthesisCompleteEvent, type SynthesisForcedEvent, type SynthesisForcedTraceEvent, type SynthesisStartEvent, TASK_STATUSES, TODO_PRIORITIES, TODO_STATUSES, type TailResponse, type TaskEndEvent, type TaskPlan, type TaskResult, type TaskSpec, type TaskStartEvent, type TaskStatus, type TextStep, type ThinkingChunkEvent, type ThinkingEndEvent, type ThinkingStartEvent, type ThinkingStep, type TodoItem, type TodoList, type TodoPriority, type TodoStatus, type ToolCall, type ToolCallRecord, type ToolCapability, type ToolConflictPolicy, type ToolDefinition, type ToolEndEvent, type ToolErrorEvent, type ToolEventMetadata, type ToolExecutionEvent, type ToolFilter, type ToolFilterEvent, type ToolPack, type ToolPermissions, type ToolResult, type ToolResultArtifact, type ToolResultRecord, type ToolResultStep, type ToolResultsSummary, type ToolStartEvent, type ToolUseStep, type TraceCommandResponse, type TraceEntry, type TraceErrorCode, TraceErrorCodes, type TraceEventType, type Tracer, type Turn, type TurnInterpretation, type TurnKind, type TurnSnapshotMessage, type TurnStep, type TwoTierMemoryConfig, type UserCorrectionMessage, type VerificationCompleteEvent, type VerificationEventData, type VerificationInput, type VerificationOutput, type VerificationResult, type VerificationStartEvent, type VerificationThresholds, type VerificationWarning, type VerificationWarningCode, buildRestRoute, buildWsChannel, schemas };