observability
Classes
CompactDashboardRenderer
Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:287
Compact single-line renderer for logging.
Implements
Constructors
Constructor
new CompactDashboardRenderer(): CompactDashboardRenderer;Returns
Methods
render()
render(snapshot): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:288
Render the dashboard snapshot to the configured format.
Parameters
snapshot
Returns
string
Implementation of
renderActivity()
renderActivity(activity): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:313
Render the activity feed.
Parameters
activity
Returns
string
Implementation of
IDashboardRenderer.renderActivity
renderAgents()
renderAgents(agents): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:305
Render the agent status table.
Parameters
agents
Returns
string
Implementation of
IDashboardRenderer.renderAgents
renderBottlenecks()
renderBottlenecks(bottlenecks): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:317
Render bottleneck warnings.
Parameters
bottlenecks
Returns
string
Implementation of
IDashboardRenderer.renderBottlenecks
renderClusters()
renderClusters(clusters): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:321
Render cluster analysis.
Parameters
clusters
Returns
string
Implementation of
IDashboardRenderer.renderClusters
renderGraph()
renderGraph(graph): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:309
Render the interaction graph.
Parameters
graph
Returns
string
Implementation of
IDashboardRenderer.renderGraph
renderHealth()
renderHealth(health): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:301
Render just the health section.
Parameters
health
Returns
string
Implementation of
IDashboardRenderer.renderHealth
Dashboard
Defined in: packages/nexus-agents/src/observability/dashboard.ts:62
Dashboard implementation that consumes SwarmObserver data.
Implements
Constructors
Constructor
new Dashboard(observer, config?): Dashboard;Defined in: packages/nexus-agents/src/observability/dashboard.ts:68
Parameters
observer
config?
Partial<DashboardConfig>
Returns
Methods
getConfig()
getConfig(): DashboardConfig;Defined in: packages/nexus-agents/src/observability/dashboard.ts:98
Get dashboard configuration.
Returns
Implementation of
getSnapshot()
getSnapshot(options?): DashboardSnapshot;Defined in: packages/nexus-agents/src/observability/dashboard.ts:74
Get current dashboard snapshot.
Parameters
options?
Returns
Implementation of
notifySubscribers()
notifySubscribers(): void;Defined in: packages/nexus-agents/src/observability/dashboard.ts:117
Notify all subscribers of an update.
Returns
void
render()
render(options?): string;Defined in: packages/nexus-agents/src/observability/dashboard.ts:93
Render dashboard to string in configured format.
Parameters
options?
Returns
string
Implementation of
subscribe()
subscribe(callback): () => void;Defined in: packages/nexus-agents/src/observability/dashboard.ts:107
Subscribe to dashboard updates.
Parameters
callback
(snapshot) => void
Returns
() => void
Implementation of
updateConfig()
updateConfig(config): void;Defined in: packages/nexus-agents/src/observability/dashboard.ts:102
Update dashboard configuration.
Parameters
config
Partial<DashboardConfig>
Returns
void
Implementation of
DirectedInteractionGraph
Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:27
Directed graph implementation for agent interactions.
Implements
Constructors
Constructor
new DirectedInteractionGraph(): DirectedInteractionGraph;Returns
Methods
addEdge()
addEdge(edge): void;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:45
Add an edge (interaction) to the graph.
Parameters
edge
Returns
void
Implementation of
addNode()
addNode(agentId): void;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:35
Add a node (agent) to the graph.
Parameters
agentId
string
Returns
void
Implementation of
clear()
clear(): void;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:256
Clear the graph.
Returns
void
Implementation of
getClusteringCoefficient()
getClusteringCoefficient(agentId): number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:203
Calculate clustering coefficient for a node. Measures how interconnected a node’s neighbors are.
Parameters
agentId
string
Returns
number
getDegreeCentrality()
getDegreeCentrality(): Map<string, number>;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:96
Calculate degree centrality for all nodes. Returns normalized centrality (0-1).
Returns
Map<string, number>
Implementation of
InteractionGraph.getDegreeCentrality
getEdgeCount()
getEdgeCount(from, to): number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:178
Get edge count between two agents.
Parameters
from
string
to
string
Returns
number
Implementation of
getEdges()
getEdges(): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:70
Get all edges in the graph.
Returns
Implementation of
getIncomingEdges()
getIncomingEdges(agentId): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:88
Get edges to a specific agent.
Parameters
agentId
string
Returns
Implementation of
InteractionGraph.getIncomingEdges
getNeighbors()
getNeighbors(agentId): string[];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:186
Get unique interaction partners for an agent.
Parameters
agentId
string
Returns
string[]
getNodes()
getNodes(): string[];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:63
Get all nodes in the graph.
Returns
string[]
Implementation of
getOutgoingEdges()
getOutgoingEdges(agentId): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:81
Get edges from a specific agent.
Parameters
agentId
string
Returns
Implementation of
InteractionGraph.getOutgoingEdges
getStats()
getStats(): GraphStats;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:225
Get statistics about the graph.
Returns
getStronglyConnectedComponents()
getStronglyConnectedComponents(): string[][];Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:128
Find strongly connected components using Kosaraju’s algorithm.
Returns
string[][]
Implementation of
InteractionGraph.getStronglyConnectedComponents
InteractionSwarmObserver
Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:53
SwarmObserver implementation.
Implements
Constructors
Constructor
new InteractionSwarmObserver(config?): InteractionSwarmObserver;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:61
Parameters
config?
Partial<InteractionObserverConfig>
Returns
Methods
attributeSuccess()
attributeSuccess(taskId): Map<string, ContributionScore>;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:180
Attribute success of a task to contributing agents.
Parameters
taskId
string
Returns
Map<string, ContributionScore>
Implementation of
IInteractionObserver.attributeSuccess
clear()
clear(): void;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:262
Clear all recorded data.
Returns
void
Implementation of
getBottlenecks()
getBottlenecks(): BottleneckInfo[];Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:125
Identify bottleneck agents.
Returns
Implementation of
IInteractionObserver.getBottlenecks
getCollaborationGraph()
getCollaborationGraph(): InteractionGraph;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:118
Get the collaboration graph.
Returns
Implementation of
IInteractionObserver.getCollaborationGraph
getEmergentClusters()
getEmergentClusters(): AgentCluster[];Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:152
Detect emergent clusters of collaborating agents. Uses strongly connected components + cohesion analysis.
Returns
Implementation of
IInteractionObserver.getEmergentClusters
getEventsByAgent()
getEventsByAgent(agentId): AgentEvent[];Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:243
Get events for a specific agent.
Parameters
agentId
string
Returns
Implementation of
IInteractionObserver.getEventsByAgent
getEventsByTrace()
getEventsByTrace(traceId): AgentEvent[];Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:236
Get events for a specific trace.
Parameters
traceId
string
Returns
Implementation of
IInteractionObserver.getEventsByTrace
getHealthMetrics()
getHealthMetrics(): SwarmHealthMetrics;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:201
Get swarm health metrics.
Returns
Implementation of
IInteractionObserver.getHealthMetrics
recordEvent()
recordEvent(event): void;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:86
Record an agent event.
Parameters
event
Returns
void
Implementation of
IInteractionObserver.recordEvent
recordInteraction()
recordInteraction(options): void;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:97
Record an interaction between two agents.
Parameters
options
Returns
void
Implementation of
IInteractionObserver.recordInteraction
registerAgentForTask()
registerAgentForTask(taskId, agentId): void;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:250
Associate an agent with a task for attribution.
Parameters
taskId
string
agentId
string
Returns
void
generateSpanId()
static generateSpanId(): string;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:79
Generate OpenTelemetry-compatible span ID (16 hex chars).
Returns
string
generateTraceId()
static generateTraceId(): string;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:72
Generate OpenTelemetry-compatible trace ID (32 hex chars).
Returns
string
JsonDashboardRenderer
Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:254
JSON dashboard renderer for programmatic consumption.
Implements
Constructors
Constructor
new JsonDashboardRenderer(): JsonDashboardRenderer;Returns
Methods
render()
render(snapshot): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:255
Render the dashboard snapshot to the configured format.
Parameters
snapshot
Returns
string
Implementation of
renderActivity()
renderActivity(activity): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:271
Render the activity feed.
Parameters
activity
Returns
string
Implementation of
IDashboardRenderer.renderActivity
renderAgents()
renderAgents(agents): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:263
Render the agent status table.
Parameters
agents
Returns
string
Implementation of
IDashboardRenderer.renderAgents
renderBottlenecks()
renderBottlenecks(bottlenecks): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:275
Render bottleneck warnings.
Parameters
bottlenecks
Returns
string
Implementation of
IDashboardRenderer.renderBottlenecks
renderClusters()
renderClusters(clusters): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:279
Render cluster analysis.
Parameters
clusters
Returns
string
Implementation of
IDashboardRenderer.renderClusters
renderGraph()
renderGraph(graph): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:267
Render the interaction graph.
Parameters
graph
Returns
string
Implementation of
IDashboardRenderer.renderGraph
renderHealth()
renderHealth(health): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:259
Render just the health section.
Parameters
health
Returns
string
Implementation of
IDashboardRenderer.renderHealth
RoutingMetricsCollector
Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:60
Collects routing decisions and outcomes to compute effectiveness metrics.
Constructors
Constructor
new RoutingMetricsCollector(config?): RoutingMetricsCollector;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:65
Parameters
config?
Partial<RoutingMetricsConfig>
Returns
Methods
getMetrics()
getMetrics(periodHours?): RoutingMetrics;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:104
Get routing metrics for a time period.
Parameters
periodHours?
number = 24
Returns
recordDecision()
recordDecision(record): void;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:76
Record a routing decision.
Parameters
record
Returns
void
recordOutcome()
recordOutcome(record): void;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:90
Record an outcome for a routing decision.
Parameters
record
Returns
void
renderDashboard()
renderDashboard(config?): string;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:152
Generate ASCII dashboard output.
Parameters
config?
Partial<RoutingDashboardConfig>
Returns
string
reset()
reset(): void;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:182
Clear all collected data.
Returns
void
toJSON()
toJSON(periodHours?): string;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:175
Get metrics as JSON for machine-readable output.
Parameters
periodHours?
number = 24
Returns
string
TextDashboardRenderer
Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:24
Text-based dashboard renderer for terminal output.
Implements
Constructors
Constructor
new TextDashboardRenderer(config): TextDashboardRenderer;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:27
Parameters
config
Returns
Methods
render()
render(snapshot): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:31
Render the dashboard snapshot to the configured format.
Parameters
snapshot
Returns
string
Implementation of
renderActivity()
renderActivity(activity): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:146
Render the activity feed.
Parameters
activity
Returns
string
Implementation of
IDashboardRenderer.renderActivity
renderAgents()
renderAgents(agents): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:79
Render the agent status table.
Parameters
agents
Returns
string
Implementation of
IDashboardRenderer.renderAgents
renderBottlenecks()
renderBottlenecks(bottlenecks): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:172
Render bottleneck warnings.
Parameters
bottlenecks
Returns
string
Implementation of
IDashboardRenderer.renderBottlenecks
renderClusters()
renderClusters(clusters): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:189
Render cluster analysis.
Parameters
clusters
Returns
string
Implementation of
IDashboardRenderer.renderClusters
renderGraph()
renderGraph(graph): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:112
Render the interaction graph.
Parameters
graph
Returns
string
Implementation of
IDashboardRenderer.renderGraph
renderHealth()
renderHealth(health): string;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:61
Render just the health section.
Parameters
health
Returns
string
Implementation of
IDashboardRenderer.renderHealth
ValidationDashboard
Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:75
Validation Dashboard implementation.
Constructors
Constructor
new ValidationDashboard(): ValidationDashboard;Returns
Methods
clear()
clear(): void;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:190
Clear all recorded data.
Returns
void
getSummary()
getSummary(filter?): DashboardSummary;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:112
Get dashboard summary with all metrics.
Parameters
filter?
DashboardFilter = {}
Returns
recordExplorationRate()
recordExplorationRate(rate): void;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:89
Record exploration rate snapshot.
Parameters
rate
number
Returns
void
recordFeatureWeights()
recordFeatureWeights(weights): void;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:97
Record feature weights for importance tracking.
Parameters
weights
Record<string, number>
Returns
void
recordOutcome()
recordOutcome(outcome): void;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:81
Record an outcome for dashboard aggregation. Evicts oldest when cap reached.
Parameters
outcome
Returns
void
renderDashboard()
renderDashboard(filter?, options?): string;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:162
Render dashboard as ASCII text.
Parameters
filter?
DashboardFilter = {}
options?
Returns
string
Interfaces
ActivityItem
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:118
Activity feed item.
Properties
agentId
readonly agentId: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:120
eventType
readonly eventType: EventType;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:121
severity
readonly severity: "error" | "info" | "warning";Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:123
summary
readonly summary: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:122
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:119
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:124
AgentCluster
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:156
Cluster of agents that work together frequently.
Properties
agents
readonly agents: string[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:160
Agents in this cluster
clusterId
readonly clusterId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:158
Cluster identifier
cohesion
readonly cohesion: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:162
Cohesion score (0-1, higher = tighter cluster)
dominantPattern?
readonly optional dominantPattern?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:168
Dominant interaction pattern
externalInteractions
readonly externalInteractions: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:166
Number of interactions with external agents
internalInteractions
readonly internalInteractions: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:164
Number of interactions within cluster
AgentEvent
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:58
Core event emitted by agents for observation.
Properties
agentId
readonly agentId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:64
Agent that emitted the event
durationMs?
readonly optional durationMs?: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:76
Duration in milliseconds (for completed events)
eventId
readonly eventId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:60
Event ID for deduplication
eventType
readonly eventType: EventType;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:66
Type of event
parentSpanId?
readonly optional parentSpanId?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:72
Parent span ID for hierarchical tracing
payload
readonly payload: EventPayload;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:74
Event-specific payload
spanId
readonly spanId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:70
OpenTelemetry span ID
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:62
ISO timestamp when event occurred
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:68
OpenTelemetry trace ID for correlation
AgentStatus
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:81
Agent status for dashboard display.
Properties
agentId
readonly agentId: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:82
errorCount
readonly errorCount: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:88
isBottleneck
readonly isBottleneck: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:89
lastActivity
readonly lastActivity: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:84
messagesReceived
readonly messagesReceived: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:86
messagesSent
readonly messagesSent: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:85
state
readonly state: SwarmAgentState;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:83
toolsInvoked
readonly toolsInvoked: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:87
BottleneckInfo
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:141
Bottleneck information for an agent.
Properties
agentId
readonly agentId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:142
avgWaitTimeMs
readonly avgWaitTimeMs: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:146
Average time messages wait
blockedAgents
readonly blockedAgents: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:148
Number of agents blocked waiting
queuedMessages
readonly queuedMessages: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:144
Messages waiting to be processed
severity
readonly severity: "critical" | "high" | "low" | "medium";Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:150
Severity level
ConsensusStats
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:156
Consensus voting statistics tracked by observer. (Source: Issue #552 - Wire up consensus event handlers)
Properties
consensusReached
consensusReached: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:162
Consensus decisions reached
decisions
decisions: {
abstained: number;
approved: number;
rejected: number;
};Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:164
Approvals vs rejections
abstained
abstained: number;approved
approved: number;rejected
rejected: number;unanimityRate
unanimityRate: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:170
Unanimity rate (0-1)
votesCast
votesCast: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:160
Total votes cast
votesRequested
votesRequested: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:158
Total votes requested
ContributionScore
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:122
Contribution score for a single agent to a task.
Properties
activeTimeMs
readonly activeTimeMs: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:131
Time spent actively working (ms)
agentId
readonly agentId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:123
errorCount
readonly errorCount: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:135
Number of errors encountered
messagesReceived
readonly messagesReceived: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:129
Number of messages received
messagesSent
readonly messagesSent: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:127
Number of messages sent
score
readonly score: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:125
Overall contribution score (0-1)
successfulTools
readonly successfulTools: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:133
Number of successful tool invocations
DashboardConfig
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:31
Dashboard configuration options.
Properties
format
readonly format: DashboardFormat;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:33
Output format
maxAgentsShown
readonly maxAgentsShown: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:35
Maximum agents to show in summary
maxEventsShown
readonly maxEventsShown: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:37
Maximum events to show in activity feed
showBottlenecks
readonly showBottlenecks: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:41
Whether to show bottleneck warnings
showClusters
readonly showClusters: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:43
Whether to show cluster analysis
showContributions
readonly showContributions: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:45
Whether to show contribution scores
showGraph
readonly showGraph: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:39
Whether to show interaction graph
timeWindowMs
readonly timeWindowMs: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:47
Time window for recent activity (ms)
DashboardFilter
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:167
Dashboard filter options.
Properties
minSampleSize?
readonly optional minSampleSize?: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:175
Minimum sample size for inclusion
models?
readonly optional models?: readonly string[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:171
Filter to specific models
period?
readonly optional period?: TimePeriod;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:169
Time period
taskTypes?
readonly optional taskTypes?: readonly string[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:173
Filter to specific task types
DashboardHealthIndicators
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:125
Dashboard health indicators.
Properties
hasMinimumData
readonly hasMinimumData: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:127
Whether we have enough data for statistical inference
healthScore
readonly healthScore: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:159
Overall health, or null when there is not enough data to score (#4714).
null is not zero and not a bad score — it means the indicators would be
defaults rather than measurements. Render it as “unmeasured”; do not
coerce it to a number.
healthyExploration
readonly healthyExploration: boolean | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:148
Whether exploration is in the healthy 10-20% range, or null when nothing
was recorded (#5255).
Previously rendered ✗ Healthy Exploration over ZERO samples — asserting a
health failure from absence — while the warning that would have explained
it was gated behind explorationHistory.length > 10, so the one disclosing
line was exactly the suppressed one.
isLearning
readonly isLearning: boolean | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:138
Whether learning is progressing, or null when unmeasured (#5255).
This was boolean and computed from avgRegret/optimalRate, whose empty
case returned 0/1 — so it answered “yes” on the strength of no data.
#4714 spotted that and guarded only the aggregate healthScore; the guard
keys on total outcomes, which is a DIFFERENT collection from the one these
metrics read, so on a live system it passed and the fabricated verdict
flowed through anyway.
noUnderperformers
readonly noUnderperformers: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:150
Whether any model is significantly underperforming
warnings
readonly warnings: readonly string[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:161
Warning messages
DashboardOutcome
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:208
Outcome record for dashboard aggregation.
Properties
allModelRewards?
readonly optional allModelRewards?: Record<string, number>;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:216
latencyMs
readonly latencyMs: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:213
model
readonly model: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:209
reward
readonly reward: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:212
success
readonly success: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:211
taskType
readonly taskType: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:210
timestamp
readonly timestamp: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:215
tokensUsed
readonly tokensUsed: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:214
DashboardRenderOptions
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:181
ASCII dashboard render options.
Properties
maxWidth?
readonly optional maxWidth?: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:191
Maximum width in characters
showConfidenceIntervals?
readonly optional showConfidenceIntervals?: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:183
Show confidence intervals
showFeatureImportance?
readonly optional showFeatureImportance?: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:189
Show feature importance
showLearningProgress?
readonly optional showLearningProgress?: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:187
Show learning progress
showTaskTypes?
readonly optional showTaskTypes?: boolean;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:185
Show task type breakdown
DashboardSnapshot
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:130
Complete dashboard snapshot.
Properties
activeTraces
readonly activeTraces: string[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:148
Active traces
activity
readonly activity: ActivityItem[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:140
Recent activity feed
agents
readonly agents: AgentStatus[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:136
Individual agent statuses
bottlenecks
readonly bottlenecks: BottleneckInfo[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:142
Current bottlenecks
clusters
readonly clusters: AgentCluster[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:144
Detected clusters
contributions
readonly contributions: ContributionScore[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:146
Top contributors (if task context)
graph
readonly graph: GraphSummary;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:138
Interaction graph summary
health
readonly health: SwarmHealthMetrics;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:134
Swarm health summary
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:132
Snapshot timestamp
DashboardSummary
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:98
Dashboard summary.
Properties
healthIndicators
readonly healthIndicators: DashboardHealthIndicators;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:119
Health indicators
learningProgress
readonly learningProgress: LearningProgress;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:117
Learning progress metrics
modelPerformance
readonly modelPerformance: readonly ModelPerformanceSummary[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:113
Model performance summaries
overallAvgReward
readonly overallAvgReward: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:111
Overall average reward
overallSuccessRate
readonly overallSuccessRate: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:108
Overall success rate
overallSuccessRateCI
readonly overallSuccessRateCI: ConfidenceInterval;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:109
period
readonly period: TimePeriod;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:100
Period covered
periodEnd
readonly periodEnd: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:102
periodStart
readonly periodStart: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:101
taskTypePerformance
readonly taskTypePerformance: readonly TaskTypePerformance[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:115
Task type breakdown
totalDecisions
readonly totalDecisions: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:104
Total decisions in period
totalOutcomes
readonly totalOutcomes: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:106
Total outcomes recorded
DashboardUpdateOptions
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:154
Partial dashboard options for selective updates.
Properties
includeActivity?
readonly optional includeActivity?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:158
includeAgents?
readonly optional includeAgents?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:156
includeBottlenecks?
readonly optional includeBottlenecks?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:159
includeClusters?
readonly optional includeClusters?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:160
includeContributions?
readonly optional includeContributions?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:161
includeGraph?
readonly optional includeGraph?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:157
includeHealth?
readonly optional includeHealth?: boolean;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:155
ErrorPayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:83
Payload for error events.
Properties
errorCode
readonly errorCode: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:85
errorMessage
readonly errorMessage: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:86
recoverable
readonly recoverable: boolean;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:88
stack?
readonly optional stack?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:87
type
readonly type: "error";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:84
GraphEdgeDisplay
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:95
Simplified edge for graph display.
Properties
avgLatencyMs
readonly avgLatencyMs: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:100
count
readonly count: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:98
from
readonly from: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:96
successRate
readonly successRate: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:99
to
readonly to: string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:97
GraphStats
Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:266
Graph statistics.
Properties
avgLatencyMs
readonly avgLatencyMs: number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:269
density
readonly density: number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:271
edgeCount
readonly edgeCount: number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:268
nodeCount
readonly nodeCount: number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:267
successRate
readonly successRate: number;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:270
GraphSummary
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:106
Graph summary for dashboard display.
Properties
centralAgents
readonly centralAgents: {
agentId: string;
centrality: number;
}[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:112
agentId
agentId: string;centrality
centrality: number;density
readonly density: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:109
edgeCount
readonly edgeCount: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:108
nodeCount
readonly nodeCount: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:107
stronglyConnectedComponents
readonly stronglyConnectedComponents: number;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:110
topEdges
readonly topEdges: GraphEdgeDisplay[];Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:111
IDashboard
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:207
Dashboard service interface.
Methods
getConfig()
getConfig(): DashboardConfig;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:221
Get dashboard configuration.
Returns
getSnapshot()
getSnapshot(options?): DashboardSnapshot;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:211
Get current dashboard snapshot.
Parameters
options?
Returns
render()
render(options?): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:216
Render dashboard to string in configured format.
Parameters
options?
Returns
string
subscribe()
subscribe(callback): () => void;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:231
Subscribe to dashboard updates.
Parameters
callback
(snapshot) => void
Returns
() => void
updateConfig()
updateConfig(config): void;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:226
Update dashboard configuration.
Parameters
config
Partial<DashboardConfig>
Returns
void
IDashboardRenderer
Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:167
Dashboard renderer interface.
Methods
render()
render(snapshot): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:171
Render the dashboard snapshot to the configured format.
Parameters
snapshot
Returns
string
renderActivity()
renderActivity(activity): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:191
Render the activity feed.
Parameters
activity
Returns
string
renderAgents()
renderAgents(agents): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:181
Render the agent status table.
Parameters
agents
Returns
string
renderBottlenecks()
renderBottlenecks(bottlenecks): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:196
Render bottleneck warnings.
Parameters
bottlenecks
Returns
string
renderClusters()
renderClusters(clusters): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:201
Render cluster analysis.
Parameters
clusters
Returns
string
renderGraph()
renderGraph(graph): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:186
Render the interaction graph.
Parameters
graph
Returns
string
renderHealth()
renderHealth(health): string;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:176
Render just the health section.
Parameters
health
Returns
string
IInteractionObserver
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:215
Interface for the SwarmObserver.
Methods
attributeSuccess()
attributeSuccess(taskId): Map<string, ContributionScore>;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:244
Attribute success of a task to contributing agents.
Parameters
taskId
string
Returns
Map<string, ContributionScore>
clear()
clear(): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:264
Clear all recorded data.
Returns
void
getBottlenecks()
getBottlenecks(): BottleneckInfo[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:234
Identify bottleneck agents.
Returns
getCollaborationGraph()
getCollaborationGraph(): InteractionGraph;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:229
Get the collaboration graph.
Returns
getEmergentClusters()
getEmergentClusters(): AgentCluster[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:239
Detect emergent clusters of collaborating agents.
Returns
getEventsByAgent()
getEventsByAgent(agentId): AgentEvent[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:259
Get events for a specific agent.
Parameters
agentId
string
Returns
getEventsByTrace()
getEventsByTrace(traceId): AgentEvent[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:254
Get events for a specific trace.
Parameters
traceId
string
Returns
getHealthMetrics()
getHealthMetrics(): SwarmHealthMetrics;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:249
Get swarm health metrics.
Returns
recordEvent()
recordEvent(event): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:219
Record an agent event.
Parameters
event
Returns
void
recordInteraction()
recordInteraction(options): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:224
Record an interaction between two agents.
Parameters
options
Returns
void
InteractionEdge
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:82
Edge in the interaction graph representing a message/interaction.
Properties
durationMs?
readonly optional durationMs?: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:94
Duration if applicable
from
readonly from: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:84
Source agent
interactionType
readonly interactionType: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:88
Type of interaction
outcome
readonly outcome: InteractionOutcome;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:92
Outcome of interaction
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:90
When interaction occurred
to
readonly to: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:86
Target agent
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:96
Trace ID for correlation
weight
readonly weight: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:98
Weight for graph algorithms (default 1)
InteractionGraph
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:270
Interface for the interaction graph.
Methods
addEdge()
addEdge(edge): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:279
Add an edge (interaction) to the graph.
Parameters
edge
Returns
void
addNode()
addNode(agentId): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:274
Add a node (agent) to the graph.
Parameters
agentId
string
Returns
void
clear()
clear(): void;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:319
Clear the graph.
Returns
void
getDegreeCentrality()
getDegreeCentrality(): Map<string, number>;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:304
Calculate degree centrality for all nodes.
Returns
Map<string, number>
getEdgeCount()
getEdgeCount(from, to): number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:314
Get edge count between two agents.
Parameters
from
string
to
string
Returns
number
getEdges()
getEdges(): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:289
Get all edges in the graph.
Returns
getIncomingEdges()
getIncomingEdges(agentId): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:299
Get edges to a specific agent.
Parameters
agentId
string
Returns
getNodes()
getNodes(): string[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:284
Get all nodes in the graph.
Returns
string[]
getOutgoingEdges()
getOutgoingEdges(agentId): InteractionEdge[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:294
Get edges from a specific agent.
Parameters
agentId
string
Returns
getStronglyConnectedComponents()
getStronglyConnectedComponents(): string[][];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:309
Find strongly connected components.
Returns
string[][]
InteractionObserverConfig
Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:62
Configuration for the SwarmObserver.
Properties
bottleneckThreshold
readonly bottleneckThreshold: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:70
Bottleneck threshold (queued messages)
cohesionThreshold
readonly cohesionThreshold: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:74
Cohesion threshold for cluster detection
logPayloads
readonly logPayloads: boolean;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:68
Enable detailed payload logging
maxEvents
readonly maxEvents: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:64
Maximum events to keep in memory
metricsWindowMs
readonly metricsWindowMs: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:66
Time window for metrics calculation (ms)
minClusterSize
readonly minClusterSize: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:72
Minimum cluster size to detect
IOrchestrationObserver
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:250
OrchestrationObserver interface for dependency injection.
Methods
addEventListener()
addEventListener(listener): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:270
Add event listener for visualization
Parameters
listener
Returns
void
getAgentStates()
getAgentStates(): readonly ObserverTrackedAgent[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:258
Get current agent states
Returns
readonly ObserverTrackedAgent[]
getRoutingHistory()
getRoutingHistory(limit?): readonly ObserverRoutingDecision[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:261
Get routing decision history
Parameters
limit?
number
Returns
readonly ObserverRoutingDecision[]
getSessionMetrics()
getSessionMetrics(sessionId?): readonly ObserverSessionMetrics[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:264
Get session metrics
Parameters
sessionId?
string
Returns
readonly ObserverSessionMetrics[]
getStats()
getStats(): OrchestrationStats;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:267
Get aggregate orchestration statistics
Returns
isActive()
isActive(): boolean;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:290
Check if observer is active
Returns
boolean
recordArmTokenUsage()
recordArmTokenUsage(
sessionId,
arm,
tokens
): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:287
Record token usage for a session on any observed ARM (#6399): a CLI
slot, a vendor arm, or a gateway arm. A gateway must come through here,
not as its display slot — recordTokenUsage('opencode', …) would price
it as that slot’s default model.
Parameters
sessionId
string
arm
ObservedArmId
tokens
Returns
void
recordRoutingDecision()
recordRoutingDecision(decision): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:276
Record a routing decision manually (for non-event-bus integrations)
Parameters
decision
Returns
void
recordTokenUsage()
recordTokenUsage(
sessionId,
model,
tokens
): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:279
Record token usage for a session on a CLI slot.
Parameters
sessionId
string
model
"claude" | "gemini" | "codex" | "opencode"
tokens
Returns
void
removeEventListener()
removeEventListener(listener): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:273
Remove event listener
Parameters
listener
Returns
void
start()
start(): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:252
Start observing the event bus
Returns
void
stop()
stop(): void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:255
Stop observing and cleanup
Returns
void
ITaskTracker
Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:48
Task tracker interface — create, update, comment.
Methods
createTask()
createTask(title, body): Promise<TrackedTask>;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:49
Parameters
title
string
body
string
Returns
Promise<TrackedTask>
postComment()
postComment(taskId, comment): Promise<void>;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:51
Parameters
taskId
string
comment
string
Returns
Promise<void>
updateStatus()
updateStatus(taskId, status): Promise<void>;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:50
Parameters
taskId
string
status
"open" | "closed" | "in_progress"
Returns
Promise<void>
LearningProgress
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:63
Learning progress metrics.
Properties
avgRegret
readonly avgRegret: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:76
Average regret per decision, or null when unmeasured.
convergenceScore
readonly convergenceScore: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:92
Convergence score, or null when no feature weights were recorded (#5255).
The empty case returned 0, which reads as WORST-possible convergence —
Math.exp(-variance) only approaches 0 and never reaches it, so a literal
0% could not have been a real reading.
cumulativeRegret
readonly cumulativeRegret: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:74
Cumulative regret, or null when no decision was comparable.
explorationRate
readonly explorationRate: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:71
LinUCB exploration rate, or null when nothing was recorded (#5255).
0 was the empty-case value and rendered as “0.0%” — indistinguishable
from a real fully-greedy policy, which is a legitimate 0.0%. null means
UNMEASURED; 0 means measured-and-zero.
explorationRateTrend
readonly explorationRateTrend: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:72
featureImportance
readonly featureImportance: readonly {
feature: string;
importance: number;
}[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:80
Feature importance ranking
optimalRate
readonly optimalRate: number | null;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:78
Optimal decision rate, or null when unmeasured.
MemoryPayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:61
Payload for memory operation events.
Properties
key?
readonly optional key?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:65
memoryType
readonly memoryType: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:64
operation
readonly operation: "write" | "read";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:63
sizeBytes?
readonly optional sizeBytes?: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:66
type
readonly type: "memory";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:62
MessagePayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:37
Payload for message events.
Properties
contentPreview?
readonly optional contentPreview?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:44
Truncated preview of message content
direction
readonly direction: "received" | "sent";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:39
messageType
readonly messageType: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:42
sourceAgentId?
readonly optional sourceAgentId?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:41
targetAgentId?
readonly optional targetAgentId?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:40
type
readonly type: "message";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:38
ModelMetrics
Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:48
Aggregated metrics for a single model.
Properties
avgLatencyMs
readonly avgLatencyMs: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:54
avgQuality
readonly avgQuality: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:53
avgReward
readonly avgReward: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:52
explorationCount
readonly explorationCount: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:56
model
readonly model: "claude" | "gemini" | "codex" | "opencode";Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:49
selectionCount
readonly selectionCount: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:50
selectionPercent
readonly selectionPercent: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:51
successRate
readonly successRate: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:55
ModelPerformanceSummary
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:20
Model performance summary with confidence intervals.
Properties
avgLatencyMs
readonly avgLatencyMs: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:32
Average latency in milliseconds
avgReward
readonly avgReward: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:29
Average reward with distribution stats
comparableN
readonly comparableN: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:41
Number of outcomes the win rate was computed over; 0 means unmeasured (#5650).
costEfficiency
readonly costEfficiency: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:43
Cost efficiency (reward per token)
model
readonly model: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:22
Model/CLI name
n
readonly n: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:24
Number of routing decisions
rewardStats
readonly rewardStats: DistributionStats;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:30
successRate
readonly successRate: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:26
Success rate with confidence interval
successRateCI
readonly successRateCI: ConfidenceInterval;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:27
winRate
readonly winRate: number;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:38
Win rate vs other models, over the comparableN outcomes that carried
counterfactual rewards. Unmeasured — comparableN === 0 — reads 0 here
for compatibility; check comparableN before treating it as a defeat (#5650).
winRateCI
readonly winRateCI: ConfidenceInterval;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:39
ObserverCostMetrics
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:93
Cost tracking per session.
totalCostUsd sums only MEASURED calls. A call whose arm cannot be priced
— a gateway arm with no usable NEXUS_GATEWAY_COST declaration (#6399) —
adds nothing to it and increments unpricedCalls instead, so a total over
unmeasured traffic reads as partial rather than as $0. costPerModel keeps
its published CLI-slot key; costPerArm is keyed by the observed ARM, so a
gateway’s cost is never folded into its display slot.
Properties
costPerArm
costPerArm: Map<ObservedArmId, number>;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:98
Per observed arm (#6399): CLI slots, vendor arms and gateway arms.
costPerModel
costPerModel: Map<"claude" | "gemini" | "codex" | "opencode", number>;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:96
Per CLI slot, as published. A gateway arm never lands here.
totalCostUsd
totalCostUsd: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:94
unpricedCalls
unpricedCalls: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:100
Calls totalCostUsd does NOT cover. Zero means every call was priced.
ObserverRoutingDecision
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:47
Captured routing decision for audit and analysis.
Properties
alternatives
readonly alternatives: readonly ("claude" | "gemini" | "codex" | "opencode")[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:54
confidence
readonly confidence: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:52
decisionTimeMs
readonly decisionTimeMs: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:56
reason
readonly reason: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:53
selectedCli
readonly selectedCli: "claude" | "gemini" | "codex" | "opencode";Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:51
stagesExecuted
readonly stagesExecuted: readonly string[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:55
taskDescription
readonly taskDescription: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:50
taskId
readonly taskId: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:49
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:48
topsisScore?
readonly optional topsisScore?: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:58
ucbScore?
readonly optional ucbScore?: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:59
withinBudget?
readonly optional withinBudget?: boolean;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:57
ObserverSessionMetrics
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:106
Session-level metrics.
Properties
completedAt?
optional completedAt?: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:109
costMetrics
costMetrics: ObserverCostMetrics;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:115
durationMs
durationMs: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:110
eventsProcessed
eventsProcessed: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:117
failureCount
failureCount: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:113
routingDecisions
routingDecisions: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:116
sessionId
readonly sessionId: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:107
startedAt
startedAt: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:108
successCount
successCount: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:112
taskCount
taskCount: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:111
tokenUsage
tokenUsage: ObserverTokenUsage;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:114
ObserverTokenUsage
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:77
Running token totals for an observability SESSION, aggregated across calls.
Named to distinguish it from the per-call TokenUsage in
core/types/model.ts (#4440). The two shared a name and a shape while
modelling different things — session aggregate vs. one call’s usage — and
exports/observability.ts already had to alias this one as
ObserverTokenUsage to avoid the clash. That collision is not harmless: it
led me to file #4439 claiming three duplicate per-call types when there were
two, and the third was this.
Properties
inputTokens
inputTokens: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:78
outputTokens
outputTokens: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:79
totalTokens
totalTokens: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:80
ObserverTrackedAgent
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:30
Tracked agent information.
Properties
currentTask?
optional currentTask?: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:34
errorCount
errorCount: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:37
id
readonly id: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:31
lastUpdated
lastUpdated: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:35
role
readonly role: string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:32
state
state: "error" | "thinking" | "idle" | "waiting" | "executing";Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:33
taskCount
taskCount: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:36
OrchestrationStats
Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:127
Aggregate orchestration statistics.
Properties
activeSessions
activeSessions: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:131
Currently active sessions
avgTaskDurationMs
avgTaskDurationMs: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:137
Average task duration in ms
consensus
consensus: ConsensusStats;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:149
Consensus voting statistics (Issue #552)
eventsProcessed
eventsProcessed: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:145
Events processed
routingDistribution
routingDistribution: Record<CliName, number>;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:139
Routing decisions per CLI
successRate
successRate: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:135
Success rate (0-1)
totalCostUsd
totalCostUsd: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:143
Total cost (estimated)
totalSessions
totalSessions: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:129
Total sessions observed
totalTasks
totalTasks: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:133
Total tasks processed
totalTokens
totalTokens: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:141
Total tokens used
uptimeMs
uptimeMs: number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:147
Observer uptime in ms
OutcomeRecord
Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:33
Outcome record for a routing decision.
Properties
latencyMs?
readonly optional latencyMs?: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:40
model
readonly model: "claude" | "gemini" | "codex" | "opencode";Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:36
qualityScore?
readonly optional qualityScore?: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:39
reward
readonly reward: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:38
success
readonly success: boolean;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:37
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:34
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:35
RecordInteractionOptions
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:104
Options for recording an interaction.
Properties
durationMs?
readonly optional durationMs?: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:116
Duration in milliseconds
from
readonly from: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:106
Source agent
interactionType
readonly interactionType: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:110
Type of interaction
outcome
readonly outcome: InteractionOutcome;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:112
Outcome of interaction
to
readonly to: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:108
Target agent
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:114
Trace ID for correlation
RoutingDashboardConfig
Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:77
Dashboard rendering configuration.
Properties
periodHours
readonly periodHours: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:80
showTrends
readonly showTrends: boolean;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:79
width
readonly width: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:78
RoutingMetrics
Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:60
Overall routing metrics.
Properties
avgReward
readonly avgReward: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:67
avgRewardTrend
readonly avgRewardTrend: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:68
avgRoutingLatencyMs
readonly avgRoutingLatencyMs: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:69
explorationRate
readonly explorationRate: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:66
modelMetrics
readonly modelMetrics: readonly ModelMetrics[];Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:65
periodEnd
readonly periodEnd: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:62
periodStart
readonly periodStart: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:61
totalDecisions
readonly totalDecisions: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:63
totalOutcomes
readonly totalOutcomes: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:64
RoutingMetricsConfig
Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:47
Configuration for the metrics collector.
Properties
maxRecords
readonly maxRecords: number;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:48
retentionHours
readonly retentionHours: number;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:49
RoutingRecord
Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:20
Individual routing decision record.
Properties
alternativeModels
readonly alternativeModels: readonly ("claude" | "gemini" | "codex" | "opencode")[];Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:24
contextTokens?
readonly optional contextTokens?: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:27
isExploration
readonly isExploration: boolean;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:25
routingLatencyMs?
readonly optional routingLatencyMs?: number;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:29
Time taken to make the routing decision (ms).
selectedModel
readonly selectedModel: "claude" | "gemini" | "codex" | "opencode";Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:23
taskType?
readonly optional taskType?: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:26
timestamp
readonly timestamp: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:21
traceId
readonly traceId: string;Defined in: packages/nexus-agents/src/observability/routing-metrics-types.ts:22
StateChangePayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:27
Payload for state change events.
Properties
newState
readonly newState: SwarmAgentState;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:30
previousState
readonly previousState: SwarmAgentState;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:29
reason?
readonly optional reason?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:31
type
readonly type: "state_change";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:28
SwarmHealthMetrics
Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:174
Swarm-level health metrics.
Properties
activeAgents
readonly activeAgents: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:178
Currently active agents
avgLatencyMs
readonly avgLatencyMs: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:192
Mean latency over the interactions that CARRIED a duration (#5782).
durationMs is optional on a recorded interaction and the server-wide
producer (mcp/eventbus-bridge.ts) does not set it, so this is a mean over
a subset. Read it with timedInteractions, not with totalInteractions.
bottlenecks
readonly bottlenecks: BottleneckInfo[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:205
Current bottlenecks
calculatedAt
readonly calculatedAt: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:209
Timestamp of metrics calculation
clusters
readonly clusters: AgentCluster[];Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:207
Detected clusters
errorAgents
readonly errorAgents: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:180
Agents in error state
successRate
readonly successRate: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:184
Successful interaction rate (0-1)
timedInteractions?
readonly optional timedInteractions?: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:203
How many of totalInteractions carried a durationMs (#5782).
Without it the mean cannot be read: 100ms over one timed edge and 100ms over fifty are the same number with very different weight, and 0 means “nothing was timed” rather than “instant”.
Optional so adding it does not break an external constructor of this published type; every in-tree producer sets it.
totalAgents
readonly totalAgents: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:176
Total agents in swarm
totalInteractions
readonly totalInteractions: number;Defined in: packages/nexus-agents/src/observability/swarm-observer-types.ts:182
Total interactions in time window
TaskPayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:72
Payload for task lifecycle events.
Properties
phase
readonly phase: "completed" | "started";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:74
success?
readonly optional success?: boolean;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:77
taskDescription?
readonly optional taskDescription?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:76
taskId
readonly taskId: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:75
type
readonly type: "task";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:73
TaskTypePerformance
Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:49
Task type performance breakdown.
Properties
bestModel
readonly bestModel: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:55
Best performing model
modelPerformance
readonly modelPerformance: readonly ModelPerformanceSummary[];Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:53
Performance per model for this task type
taskType
readonly taskType: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:51
Task type
worstModel
readonly worstModel: string;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:57
Worst performing model
ToolPayload
Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:50
Payload for tool invocation events.
Properties
errorMessage?
readonly optional errorMessage?: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:55
phase
readonly phase: "completed" | "invoked";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:52
success?
readonly optional success?: boolean;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:54
toolName
readonly toolName: string;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:53
type
readonly type: "tool";Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:51
TrackedTask
Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:26
A tracked task/issue.
Properties
id
readonly id: string;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:28
Backend-specific ID (issue number or local ID).
status
readonly status: "open" | "closed" | "in_progress";Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:30
title
readonly title: string;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:29
url?
readonly optional url?: string;Defined in: packages/nexus-agents/src/pipeline/task-tracker.ts:31
Type Aliases
AgentId
type AgentId = string;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:15
Unique identifier for agents in the swarm.
DashboardFormat
type DashboardFormat = "json" | "text" | "markdown" | "compact";Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:26
Output format for dashboard rendering.
EventPayload
type EventPayload =
| StateChangePayload
| MessagePayload
| ToolPayload
| MemoryPayload
| TaskPayload
| ErrorPayload;Defined in: packages/nexus-agents/src/observability/swarm-observer-payloads.ts:16
Discriminated union of event payloads.
EventType
type EventType =
| "state_change"
| "message_sent"
| "message_received"
| "tool_invoked"
| "tool_completed"
| "memory_read"
| "memory_write"
| "task_started"
| "task_completed"
| "error";Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:37
Types of events the observer can track.
InteractionOutcome
type InteractionOutcome = "success" | "failure" | "timeout" | "pending";Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:57
Outcome of an interaction.
ObserverAgentState
type ObserverAgentState = z.infer<typeof AgentStateSchema>;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:25
OrchestrationObserverEvent
type OrchestrationObserverEvent =
| {
agentId: string;
previousState: ObserverAgentState;
state: ObserverAgentState;
type: "agent_state_changed";
}
| {
decision: ObserverRoutingDecision;
type: "routing_decision";
}
| {
pattern: string;
sessionId: string;
type: "session_started";
}
| {
durationMs: number;
sessionId: string;
success: boolean;
type: "session_completed";
}
| {
metrics: OrchestrationStats;
type: "metrics_updated";
}
| {
error: string;
source: string;
type: "error";
};Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:180
OrchestrationObserver event types for visualization hooks.
OrchestrationObserverListener
type OrchestrationObserverListener = (event) => void;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-types.ts:191
Observer event listener function.
Parameters
event
Returns
void
SpanId
type SpanId = string;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:32
OpenTelemetry-compatible span identifier. Format: 16-character hex string (64-bit).
SwarmAgentState
type SwarmAgentState = "idle" | "thinking" | "executing" | "waiting" | "error";Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:52
Agent state for tracking state transitions.
TaskId
type TaskId = string;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:20
Unique identifier for tasks.
TimePeriod
type TimePeriod = "1h" | "24h" | "7d" | "30d" | "all";Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:15
Time period for aggregation.
TraceId
type TraceId = string;Defined in: packages/nexus-agents/src/observability/swarm-observer-core-types.ts:26
OpenTelemetry-compatible trace identifier. Format: 32-character hex string (128-bit).
Variables
AgentEventSchema
const AgentEventSchema: ZodObject<{
agentId: ZodString;
durationMs: ZodOptional<ZodNumber>;
eventId: ZodString;
eventType: ZodEnum<{
error: "error";
memory_read: "memory_read";
memory_write: "memory_write";
message_received: "message_received";
message_sent: "message_sent";
state_change: "state_change";
task_completed: "task_completed";
task_started: "task_started";
tool_completed: "tool_completed";
tool_invoked: "tool_invoked";
}>;
parentSpanId: ZodOptional<ZodString>;
payload: ZodRecord<ZodString, ZodUnknown>;
spanId: ZodString;
timestamp: ZodISODateTime;
traceId: ZodString;
}, $strip>;Defined in: packages/nexus-agents/src/observability/swarm-observer-schemas.ts:41
Zod schema for AgentEvent validation.
DashboardConfigSchema
const DashboardConfigSchema: ZodObject<{
format: ZodDefault<ZodEnum<{
compact: "compact";
json: "json";
markdown: "markdown";
text: "text";
}>>;
maxAgentsShown: ZodDefault<ZodNumber>;
maxEventsShown: ZodDefault<ZodNumber>;
showBottlenecks: ZodDefault<ZodBoolean>;
showClusters: ZodDefault<ZodBoolean>;
showContributions: ZodDefault<ZodBoolean>;
showGraph: ZodDefault<ZodBoolean>;
timeWindowMs: ZodDefault<ZodNumber>;
}, $strip>;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:67
Zod schema for dashboard configuration.
DEFAULT_DASHBOARD_CONFIG
const DEFAULT_DASHBOARD_CONFIG: DashboardConfig;Defined in: packages/nexus-agents/src/observability/dashboard-types.ts:53
Default dashboard configuration.
DEFAULT_DASHBOARD_RENDER_OPTIONS
const DEFAULT_DASHBOARD_RENDER_OPTIONS: Required<DashboardRenderOptions>;Defined in: packages/nexus-agents/src/observability/validation-dashboard-types.ts:197
Default dashboard render options.
DEFAULT_SWARM_OBSERVER_CONFIG
const DEFAULT_SWARM_OBSERVER_CONFIG: InteractionObserverConfig;Defined in: packages/nexus-agents/src/observability/swarm-observer-schemas.ts:17
Default configuration for SwarmObserver.
InteractionObserverConfigSchema
const InteractionObserverConfigSchema: ZodObject<{
bottleneckThreshold: ZodDefault<ZodNumber>;
cohesionThreshold: ZodDefault<ZodNumber>;
logPayloads: ZodDefault<ZodBoolean>;
maxEvents: ZodDefault<ZodNumber>;
metricsWindowMs: ZodDefault<ZodNumber>;
minClusterSize: ZodDefault<ZodNumber>;
}, $strip>;Defined in: packages/nexus-agents/src/observability/swarm-observer-schemas.ts:29
Zod schema for SwarmObserverConfig validation.
Functions
calculateMetricsTotals()
function calculateMetricsTotals(sessionMetrics): {
totalCost: number;
totalTokens: number;
};Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:204
Aggregates token and cost totals from session metrics.
Parameters
sessionMetrics
Iterable<ObserverSessionMetrics>
Iterable of session metrics
Returns
{
totalCost: number;
totalTokens: number;
}Object containing total tokens and total cost
totalCost
totalCost: number;totalTokens
totalTokens: number;calculateRoutingDistribution()
function calculateRoutingDistribution(routingHistory): Record<CliName, number>;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:188
Calculates routing distribution from routing history.
Parameters
routingHistory
readonly ObserverRoutingDecision[]
The routing decision history
Returns
Record<CliName, number>
A record mapping CLI names to counts
calculateTokenCost()
function calculateTokenCost(tokens, ratePerThousand): number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:286
Calculates the cost for token usage based on rate.
Parameters
tokens
Token usage to calculate cost for
ratePerThousand
number
Cost rate per 1000 tokens
Returns
number
The calculated cost in USD
countActiveSessions()
function countActiveSessions(sessionMetrics): number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:223
Counts active sessions (sessions without a completedAt timestamp).
Parameters
sessionMetrics
Iterable<ObserverSessionMetrics>
Iterable of session metrics
Returns
number
The count of active sessions
createDashboard()
function createDashboard(observer, config?): Dashboard;Defined in: packages/nexus-agents/src/observability/dashboard.ts:270
Create a new dashboard instance.
Parameters
observer
config?
Partial<DashboardConfig>
Returns
createDashboardRenderer()
function createDashboardRenderer(config): IDashboardRenderer;Defined in: packages/nexus-agents/src/observability/dashboard-renderer.ts:329
Create a dashboard renderer for the specified format.
Parameters
config
Returns
createInitialCostMetrics()
function createInitialCostMetrics(): ObserverCostMetrics;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:143
Creates initial cost metrics with zero values.
Returns
A new CostMetrics object with zero values
createInitialSessionMetrics()
function createInitialSessionMetrics(sessionId): ObserverSessionMetrics;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:110
Creates initial session metrics with default values.
Parameters
sessionId
string
The session ID
Returns
A new SessionMetrics object with initial values
createInitialTokenUsage()
function createInitialTokenUsage(): ObserverTokenUsage;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:130
Creates initial token usage with zero values.
Returns
A new SessionTokenTotals object with zero values
createInteractionGraph()
function createInteractionGraph(): InteractionGraph;Defined in: packages/nexus-agents/src/observability/interaction-graph.ts:277
Create a new interaction graph.
Returns
createInteractionSwarmObserver()
function createInteractionSwarmObserver(config?): IInteractionObserver;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:364
Create a new SwarmObserver instance.
Parameters
config?
Partial<InteractionObserverConfig>
Returns
createRoutingMetricsCollector()
function createRoutingMetricsCollector(config?): RoutingMetricsCollector;Defined in: packages/nexus-agents/src/observability/routing-metrics.ts:303
Create a RoutingMetricsCollector instance.
Parameters
config?
Partial<RoutingMetricsConfig>
Returns
createTrackedAgent()
function createTrackedAgent(
agentId,
state,
role?,
currentTask?
): ObserverTrackedAgent;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:161
Creates a new TrackedAgent object with initial values.
Parameters
agentId
string
The agent ID
state
"error" | "thinking" | "idle" | "waiting" | "executing"
The initial agent state
role?
string = 'unknown'
The agent role (defaults to ‘unknown’)
currentTask?
string
Optional current task description
Returns
A new TrackedAgent object
createValidationDashboard()
function createValidationDashboard(): ValidationDashboard;Defined in: packages/nexus-agents/src/observability/validation-dashboard.ts:306
Create a validation dashboard instance.
Returns
extractBooleanField()
function extractBooleanField(payload, field): boolean;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:69
Extracts a boolean field from a payload object safely.
Parameters
payload
Record<string, unknown>
The payload object to extract from
field
string
The field name to extract
Returns
boolean
The boolean value (defaults to false if not found/invalid)
extractNumberField()
function extractNumberField(
payload,
field,
defaultValue?
): number;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:53
Extracts a number field from a payload object safely.
Parameters
payload
Record<string, unknown>
The payload object to extract from
field
string
The field name to extract
defaultValue?
number = 0
Default value if not found
Returns
number
The number value or default if not found/invalid
extractSessionId()
function extractSessionId(event, payload): string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:92
Extracts session ID from event object or payload.
Parameters
event
DomainEvent
The domain event
payload
Record<string, unknown>
The event payload
Returns
string
The session ID or empty string if not found
extractStringArrayField()
function extractStringArrayField(payload, field): string[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:80
Extracts a string array field from a payload object safely.
Parameters
payload
Record<string, unknown>
The payload object to extract from
field
string
The field name to extract
Returns
string[]
The string array or empty array if not found/invalid
extractStringField()
function extractStringField(payload, field): string;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:40
Extracts a string field from a payload object safely.
Parameters
payload
Record<string, unknown>
The payload object to extract from
field
string
The field name to extract
Returns
string
The string value or empty string if not found/invalid
findActiveSession()
function findActiveSession(sessionMetrics): ObserverSessionMetrics | undefined;Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:239
Finds the first active session (no completedAt) from metrics.
Parameters
sessionMetrics
Iterable<ObserverSessionMetrics>
Iterable of session metrics
Returns
ObserverSessionMetrics | undefined
The first active session or undefined
getSwarmObserver()
function getSwarmObserver(config?): InteractionSwarmObserver;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:376
Get or create the global SwarmObserver.
Parameters
config?
Partial<InteractionObserverConfig>
Returns
identifySessionsToRemove()
function identifySessionsToRemove(sessions, maxSessions): string[];Defined in: packages/nexus-agents/src/agents/observability/orchestration-observer-helpers.ts:262
Identifies session IDs to remove based on max history limit. Returns oldest sessions first.
Parameters
sessions
[string, ObserverSessionMetrics][]
Array of [sessionId, metrics] entries
maxSessions
number
Maximum sessions to keep
Returns
string[]
Array of session IDs to remove
setSwarmObserver()
function setSwarmObserver(observer): void;Defined in: packages/nexus-agents/src/observability/swarm-observer.ts:384
Set the global SwarmObserver.
Parameters
observer
Returns
void