/**
 * Live Agent Topology — Real-time agent graph and event tracking
 *
 * Maintains a live directed graph of agents (nodes) and their interactions
 * (edges). Emits events for every state change so dashboards can render
 * the topology in real time.
 *
 * @module Topology
 * @version 1.0.0
 */
import { EventEmitter } from 'events';
/** Operational status of an agent node */
export type AgentNodeStatus = 'idle' | 'running' | 'completed' | 'failed' | 'waiting' | 'spawning';
/** Visual group / role for clustering in the UI */
export type AgentRole = 'orchestrator' | 'worker' | 'validator' | 'planner' | 'aggregator' | 'custom';
/** A single agent node in the topology graph */
export interface AgentNode {
    /** Unique agent identifier */
    id: string;
    /** Display label (defaults to id) */
    label: string;
    /** Current operational status */
    status: AgentNodeStatus;
    /** Adapter framework (e.g. 'langchain', 'crewai', 'custom') */
    adapter?: string;
    /** Visual grouping role */
    role: AgentRole;
    /** Current task description */
    currentTask?: string;
    /** Tokens consumed so far */
    tokensUsed: number;
    /** Budget cap for this agent (if any) */
    tokenBudget?: number;
    /** ISO 8601 timestamp when the agent was registered */
    registeredAt: string;
    /** ISO 8601 timestamp of last activity */
    lastActivityAt: string;
    /** Arbitrary metadata */
    metadata: Record<string, unknown>;
}
/** Type of edge between agents */
export type EdgeType = 'blackboard_write' | 'blackboard_read' | 'delegation' | 'result' | 'dependency' | 'message';
/** A directed edge representing an interaction between agents */
export interface TopologyEdge {
    /** Unique edge identifier */
    id: string;
    /** Source agent id */
    from: string;
    /** Target agent id (or '_blackboard' for board interactions) */
    to: string;
    /** Type of interaction */
    type: EdgeType;
    /** Edge label (e.g. blackboard key, task id) */
    label?: string;
    /** ISO 8601 timestamp */
    timestamp: string;
    /** Optional payload metadata */
    metadata?: Record<string, unknown>;
}
/** A timestamped event in the topology stream */
export interface TopologyEvent {
    /** Monotonic event counter */
    seq: number;
    /** ISO 8601 timestamp */
    timestamp: string;
    /** Event type */
    type: TopologyEventType;
    /** Event payload */
    data: Record<string, unknown>;
}
/** All topology event types */
export type TopologyEventType = 'agent:added' | 'agent:removed' | 'agent:status' | 'agent:task' | 'agent:tokens' | 'edge:added' | 'edge:removed' | 'snapshot' | 'clear';
/** Full snapshot of the topology graph */
export interface TopologySnapshot {
    /** All agent nodes */
    nodes: AgentNode[];
    /** All edges */
    edges: TopologyEdge[];
    /** Event log since last clear */
    events: TopologyEvent[];
    /** Snapshot timestamp */
    timestamp: string;
    /** Live narrative summary */
    narrative: string;
    /** Phase progress */
    phase: PhaseProgress;
    /** Attention-based status panel */
    attention: AttentionPanel;
    /** Agent activity timeline spans */
    timeline: TimelineSpan[];
    /** Agent clusters for scaled views (optional, populated by server) */
    clusters?: AgentCluster[];
}
/** Events emitted by TopologyTracker */
export interface TopologyTrackerEvents {
    'agent:added': (node: AgentNode) => void;
    'agent:removed': (id: string) => void;
    'agent:status': (id: string, status: AgentNodeStatus, prev: AgentNodeStatus) => void;
    'agent:task': (id: string, task: string | undefined) => void;
    'agent:tokens': (id: string, tokens: number) => void;
    'edge:added': (edge: TopologyEdge) => void;
    'edge:removed': (edgeId: string) => void;
    'snapshot': (snapshot: TopologySnapshot) => void;
    'event': (event: TopologyEvent) => void;
    'clear': () => void;
}
/** Options for creating a TopologyTracker */
export interface TopologyTrackerOptions {
    /** Maximum number of events to retain (default: 2000) */
    maxEvents?: number;
    /** Maximum number of edges to retain (default: 5000) */
    maxEdges?: number;
    /** Auto-prune edges older than this (ms). 0 = no pruning (default: 0) */
    edgeTtlMs?: number;
    /** Maximum timeline spans to retain (default: 50000) */
    maxTimelineSpans?: number;
}
/** A phase milestone in the workflow */
export interface PhaseMilestone {
    /** Phase name */
    name: string;
    /** Status */
    status: 'pending' | 'active' | 'completed';
}
/** Phase progress for the progress bar */
export interface PhaseProgress {
    /** Ordered milestones */
    milestones: PhaseMilestone[];
    /** 0-1 overall progress */
    progress: number;
    /** Current phase label */
    currentPhase: string;
}
/** Attention-based panel items */
export interface AttentionItem {
    /** Agent id */
    agentId: string;
    /** Agent label */
    label: string;
    /** Summary text */
    summary: string;
    /** Severity */
    severity: 'critical' | 'active' | 'done';
    /** Elapsed time in ms (for active items) */
    elapsedMs?: number;
    /** ISO timestamp */
    timestamp: string;
}
/** Attention panel with categorized items */
export interface AttentionPanel {
    /** Items needing attention (failures, budget overruns, stuck) */
    needsAttention: AttentionItem[];
    /** Currently active agents */
    activeNow: AttentionItem[];
    /** Recently finished */
    recentlyCompleted: AttentionItem[];
}
/** A timeline span for Gantt chart visualization */
export interface TimelineSpan {
    /** Agent id */
    agentId: string;
    /** Agent label */
    label: string;
    /** Status during this span */
    status: AgentNodeStatus;
    /** Start time in ms (epoch) */
    startMs: number;
    /** End time in ms (epoch), undefined if still active */
    endMs?: number;
}
/** A cluster of agents for zoomed-out views */
export interface AgentCluster {
    /** Cluster identifier */
    id: string;
    /** Role shared by agents in this cluster */
    role: AgentRole;
    /** Number of agents in this cluster */
    count: number;
    /** Status breakdown */
    statusCounts: Record<AgentNodeStatus, number>;
    /** Aggregate tokens used */
    totalTokensUsed: number;
    /** Aggregate token budget */
    totalTokenBudget: number;
    /** Representative agent ids (first few) */
    sampleIds: string[];
}
/** Delta patch for incremental updates */
export interface TopologyDelta {
    /** Sequence number this delta starts from */
    sinceSeq: number;
    /** Current sequence number */
    currentSeq: number;
    /** New or changed agent nodes */
    nodesChanged: AgentNode[];
    /** Removed agent ids */
    nodesRemoved: string[];
    /** New edges */
    edgesAdded: TopologyEdge[];
    /** Removed edge ids */
    edgesRemoved: string[];
    /** Updated summary fields */
    narrative: string;
    phase: PhaseProgress;
    attention: AttentionPanel;
    /** Only new timeline spans since sinceSeq */
    timelineAdded: TimelineSpan[];
    /** Aggregated clusters (sent with every delta for up-to-date cluster view) */
    clusters?: AgentCluster[];
}
/**
 * Tracks the live agent topology graph and emits real-time events.
 *
 * Usage:
 * ```typescript
 * const topo = new TopologyTracker();
 *
 * topo.addAgent({ id: 'planner', role: 'planner' });
 * topo.addAgent({ id: 'worker-1', role: 'worker', adapter: 'langchain' });
 *
 * topo.setStatus('planner', 'running');
 * topo.addEdge('planner', 'worker-1', 'delegation', 'analyze code');
 *
 * topo.on('agent:status', (id, status) => {
 *   console.log(`${id} → ${status}`);
 * });
 * ```
 */
export declare class TopologyTracker extends EventEmitter {
    private nodes;
    private edges;
    private eventLog;
    private seq;
    private readonly maxEvents;
    private readonly maxEdges;
    private readonly edgeTtlMs;
    private readonly maxTimelineSpans;
    private timelineSpans;
    private deltaNodesChanged;
    private deltaNodesRemoved;
    private deltaEdgesAdded;
    private deltaEdgesRemoved;
    private deltaTimelineStart;
    constructor(options?: TopologyTrackerOptions);
    /**
     * Add or update an agent node.
     */
    addAgent(opts: {
        id: string;
        label?: string;
        role?: AgentRole;
        adapter?: string;
        status?: AgentNodeStatus;
        tokenBudget?: number;
        metadata?: Record<string, unknown>;
    }): AgentNode;
    /**
     * Remove an agent node and all its edges.
     */
    removeAgent(id: string): boolean;
    /**
     * Update an agent's operational status.
     */
    setStatus(id: string, status: AgentNodeStatus): void;
    /**
     * Update or clear the agent's current task.
     */
    setTask(id: string, task?: string): void;
    /**
     * Add tokens consumed by an agent.
     */
    addTokens(id: string, tokens: number): void;
    /**
     * Get a single agent node.
     */
    getAgent(id: string): AgentNode | undefined;
    /**
     * Get all agent nodes.
     */
    getAgents(): AgentNode[];
    /**
     * Add a directed edge between agents.
     */
    addEdge(from: string, to: string, type: EdgeType, label?: string, metadata?: Record<string, unknown>): TopologyEdge;
    /**
     * Remove an edge by id.
     */
    removeEdge(edgeId: string): boolean;
    /**
     * Get all edges, optionally filtered by agent id.
     */
    getEdges(agentId?: string): TopologyEdge[];
    /**
     * Get edges between two specific agents.
     */
    getEdgesBetween(from: string, to: string): TopologyEdge[];
    /**
     * Generate a one-line narrative summary of the current topology state.
     */
    generateNarrative(): string;
    /**
     * Compute phase progress from agent roles and statuses.
     */
    computePhase(): PhaseProgress;
    /**
     * Compute the attention-based status panel.
     */
    computeAttention(): AttentionPanel;
    /**
     * Get all timeline spans for the Gantt chart.
     */
    getTimelineSpans(): TimelineSpan[];
    /**
     * Compute clusters by grouping agents by role.
     * Returns an array of clusters with aggregate statistics.
     */
    computeClusters(): AgentCluster[];
    /**
     * Get a delta patch of changes since the last call to resetDelta().
     * Use this for incremental WebSocket updates instead of full snapshots.
     */
    delta(sinceSeq: number): TopologyDelta;
    /**
     * Reset delta tracking. Call after sending a delta to a client.
     */
    resetDelta(): void;
    /**
     * Current sequence number for delta protocol.
     */
    currentSeq(): number;
    /**
     * Get a full snapshot of the current topology.
     */
    snapshot(): TopologySnapshot;
    /**
     * Return snapshot data without emitting events or logging.
     * Used by the dashboard server's broadcast loop to avoid
     * re-entrant event emission (snapshot → event → broadcast → snapshot).
     */
    snapshotQuiet(): TopologySnapshot;
    /**
     * Get the event log.
     */
    getEvents(since?: number): TopologyEvent[];
    /**
     * Number of agent nodes.
     */
    nodeCount(): number;
    /**
     * Number of edges.
     */
    edgeCount(): number;
    /**
     * Clear all nodes, edges, and events.
     */
    clear(): void;
    private pushEvent;
    private pruneExpiredEdges;
    private trimTimeline;
}
//# sourceMappingURL=topology.d.ts.map