Upgrading

Changes that can affect existing code, newest first. The full history is in the changelog.

0.5 → 0.6

Progress is unknown until reported; the default metric is 'auto'

Before, every agent had a progress line starting at 0%, and the chart plotted progress by default. Now progress is unknown until an agent reports it, and metric defaults to 'auto': progress once every visible agent reports it, token rate otherwise.

• Agents that never send progress plot their token rate instead of a flat 0% line. createAgent's 0 doesn't count as reported; a starting value above 0 in agents does.
• With an explicit metric="progress" or "both", an agent without progress has no progress line and reads "–".
• getLiveMetrics(id) adds progressKnown.

To keep the old chart, set the metric explicitly:

// Before (0.5): progress was the default
const before = <AgentStat agents={agents} />;

// After (0.6): say which series you want
const after = <AgentStat agents={agents} metric="progress" />;

ChartMetric has a new member

An exhaustive switch over ChartMetric needs an 'auto' case.

0.4 → 0.5

spikeZScore is replaced

Spikes are now judged against the agent's usual peak. spikeZScore is gone; use spikeRatio (default 1.5) and spikeMinIncrease (default 3 tokens/s).

// Before (0.4)
// anomalyConfig={{ spikeZScore: 4 }}

// After (0.5)
<AgentStat
  agents={agents}
  anomalyDetection
  anomalyConfig={{ spikeRatio: 2, spikeMinIncrease: 5 }}
/>

A new status: waiting

• AgentStatus gains 'waiting', so exhaustive switches need a case.
• If you copied the thrashBenignStatuses default, add 'waiting' to it.
• AnomalyConfig gains waitingStallMs; complete objects of that type need it (a Partial<AnomalyConfig> for anomalyConfig doesn't).

import type { AgentStatus } from '@dan-build/agentstat';

function label(status: AgentStatus): string {
  switch (status) {
    case 'active': return 'Working';
    case 'thinking': return 'Thinking';
    case 'waiting': return 'Waiting'; // new in 0.5
    case 'stuck': return 'Stuck';
    case 'complete': return 'Done';
    case 'hallucinating': return 'Hallucinating';
  }
}

AgentStatRef has new methods

Mocks typed as AgentStatRef need push and getStats.

Anomaly detection behaves differently

The detectors were rebuilt to stop false alarms (how it's measured). Expect fewer alerts: the stall limit while active is now 10 s, while thinking 30 s, and moving between working states isn't thrash. Each alert is one episode, with onAnomalyEnd when it ends.

0.3 → 0.4

hallucinationRisk and latencyTrend can be null

hallucinationRisk is null unless you pass confidenceScore or report 'hallucinating'; it used to default to an unmeasured 10%. latencyTrend is null until four latencyMs reports.

import type { HealthMetrics } from '@dan-build/agentstat';

function riskText(health: HealthMetrics): string {
  // Before (0.3): `${health.hallucinationRisk}%` was always a number
  return health.hallucinationRisk === null ? 'no signal' : `${health.hallucinationRisk}%`;
}

Other changes

• tokenEfficiency falls off relative to the band's upper edge instead of a fixed 4 points per token/s.
• No backfilled history: each agent starts with one real sample instead of 80 invented ones.
• Colors: createAgent and demoAgents no longer set a color; agents use the theme palette.
• onSpikeClick is renamed onPointClick. The old name still works.
• updateAgent takes a partial sample: updateAgent(id, { tokensRate }). The positional form still works.