API reference

interface AgentStatRef {
  /** Report a partial sample; omitted fields keep their previous value. */
  updateAgent(id: string, sample: AgentSample): void;
  /** Positional form, kept for compatibility. */
  updateAgent(
    id: string,
    tokensRate: number,
    progress: number,
    status: AgentStatus,
  ): void;
  /** Forward a raw stream event; use this or updateAgent's tokensRate, not both. */
  push(id: string, event: AgentEvent): void;
  /** Token count, TTFT, inter-token latency and open tool, from push events. */
  getStats: (id: string) => AgentStreamStats | undefined;
  getHealth: (id: string) => HealthMetrics | undefined;
  /** Anomalies active now (empty with detection off). */
  getAnomalies: (id: string) => Anomaly[];
  /** Values drawn at the live tip; progressKnown is false until progress is reported. */
  getLiveMetrics: (id: string) => {
    tokensRate: number;
    progress: number;
    status: AgentStatus;
    progressKnown: boolean;
  } | undefined;
}

createAgent(id: string, name: string, color?: string): Agent
demoAgents: Agent[]
createAgentStream(): AgentStream
useAgentStream(): AgentStream
detectAnomalies(tokens, changes, currentStatus, now, cfg?): Anomaly[]
DEFAULT_ANOMALY_CONFIG: AnomalyConfig

type AgentStatus = 'active' | 'stuck' | 'thinking' | 'waiting' | 'complete' | 'hallucinating';

type ChartMetric = 'auto' | 'progress' | 'tokens' | 'both';

type Agent = {
  id: string;
  name: string;
  /** Any CSS color. Omit to use the theme palette. */
  color?: string;
  /** @deprecated Not read. */
  data?: AgentDataPoint[];
  current: {
    tokensRate: number;
    progress: number;
    status: AgentStatus;
    latencyMs?: number;
    confidenceScore?: number;
    errorCount?: number;
  };
  config?: {
    expectedTokensPerSec?: [number, number];
    /** @deprecated Not read. */
    maxHallucinationThreshold?: number;
  };
  /** Initial visibility (default true). */
  visible?: boolean;
};

type AgentSample = {
  tokensRate?: number;
  progress?: number;          // 0–100
  status?: AgentStatus;
  latencyMs?: number;         // enables latencyTrend
  confidenceScore?: number;   // 0–1, enables hallucinationRisk
  errorCount?: number;
};

type AgentDataPoint = {
  time: number;               // performance.now() clock
  tokensRate: number;
  progress: number;
  status: AgentStatus;
  latencyMs?: number;
  confidenceScore?: number;
  errorCount?: number;
};

type AgentEvent =
  | { type: 'start'; time?: number }
  | {
      type: 'tokens';
      count?: number;
      total?: number;
      since?: number;
      time?: number;
    }
  | { type: 'tool-start'; name?: string; time?: number }
  | { type: 'tool-end'; name?: string; error?: boolean; time?: number }
  | { type: 'error'; time?: number }
  | { type: 'finish'; time?: number };

type AgentStreamStats = {
  totalTokens: number;
  ttftMs: number | null;
  interTokenMs: number | null;
  tool: string | null;        // innermost open tool call ('' if unnamed)
  statusMs: number;           // time in the current status
};

type AgentStreamMessage = { seq: number } & (
  | { type: 'event'; id: string; event: AgentEvent }
  | {
      type: 'agent';
      id: string;
      name?: string;
      color?: string;
      config?: Agent['config'];
    }
  | { type: 'remove'; id: string }
);

interface AgentSource {
  subscribe(
    listener: (m: AgentStreamMessage) => void,
    after?: number,
  ): () => void;
}

interface AgentStream extends AgentSource {
  push(agentId: string, event: AgentEvent): void;
  describe(
    agentId: string,
    info: { name?: string; color?: string; config?: Agent['config'] },
  ): void;
  remove(agentId: string): void;
}

type HealthMetrics = {
  score: number;
  tokenEfficiency: number;
  stability: number;
  hallucinationRisk: number | null;
  latencyTrend: 'improving' | 'stable' | 'degrading' | null;
};

type AnomalyKind = 'stall' | 'spike' | 'thrash';
type AnomalySeverity = 'warning' | 'critical';

interface Anomaly {
  kind: AnomalyKind;
  severity: AnomalySeverity;
  t: number;                  // performance.now() clock
  message: string;            // e.g. "stalled 8s while active"
  value: number;              // rate for stall/spike, count for thrash
  baseline?: number;          // spikes: the usual level compared with
}

interface AnomalyConfig {
  stallRateThreshold: number;
  stallDurationMs: number;
  thinkingStallMs: number;
  waitingStallMs: number;
  spikeRatio: number;
  spikeMinIncrease: number;
  spikeMinSamples: number;
  spikeBaselineMs: number;
  spikeMinBaselineRate: number;
  spikeMaxEpisodeMs: number;
  thrashChangeCount: number;
  thrashWindowMs: number;
  thrashBenignStatuses: AgentStatus[];
}

type AgentTelemetry = {
  id: string;
  name: string;
  status: AgentStatus;
  statusMs: number;
  tool: string | null;
  tokensRate: number;
  totalTokens: number;
  ttftMs: number | null;
  health: number | null;
  anomalies: Anomaly[];
  history: { status: AgentStatus; fromMs: number; toMs: number }[];
};

interface TelemetryOptions {
  agents?: Agent[];
  anomalyDetection?: boolean;    // default true
  anomalyConfig?: Partial<AnomalyConfig>;
  historySeconds?: number;       // default 300
  onAnomaly?: (agentId: string, anomaly: Anomaly) => void;
  onAnomalyEnd?: (agentId: string, anomaly: Anomaly) => void;
  onHealthChange?: (agentId: string, health: HealthMetrics) => void;
}

type TelemetryComponentProps = {
  theme?: 'light' | 'dark' | 'system';   // default 'system'
  className?: string;
  style?: React.CSSProperties;
};

import {
  AgentStat, createAgent, demoAgents,
  createAgentStream, useAgentStream,
  useAgentTelemetry, AgentStatusBadge, AnomalyBanner, AgentRoster, AgentTimeline,
  useAnomalyAnnouncer, timelineBars,
  detectAnomalies, DEFAULT_ANOMALY_CONFIG,
  type AgentStatProps, type AgentStatRef,
  type Agent, type AgentDataPoint, type AgentSample, type AgentStatus, type ChartMetric,
  type AgentEvent, type AgentStreamStats,
  type AgentSource, type AgentStream, type AgentStreamMessage,
  type HealthMetrics, type Anomaly, type AnomalyKind, type AnomalySeverity, type AnomalyConfig,
  type AgentTelemetry, type TelemetryOptions, type TelemetryComponentProps,
} from '@dan-build/agentstat';

import {
  createChatTracker, createAiSdkTap, tapAiSdkStream,
  type ChatTrackerOptions, type ChatMessage, type AiSdkPart,
  type AdapterOptions, type EventSink, type AgentEvent,
} from '@dan-build/agentstat/ai-sdk';

import {
  createLangChainCallbacks, createLangChainTap, tapLangChainStream, bySubgraph,
  type LangChainOptions, type AgentIdFor, type LangChainRun,
  type LangChainCallbackHandler, type LangChainStreamEvent, type LangChainTap,
  type AdapterOptions, type EventSink,
} from '@dan-build/agentstat/langchain';

import {
  createOtelProcessor,
  type OtelOptions, type OtelSpan, type OtelSpanInfo, type AgentStatSpanProcessor,
  type AdapterOptions, type EventSink, type AgentEvent,
} from '@dan-build/agentstat/otel';

import {
  createAgUiTap,
  type AgUiEvent, type AdapterOptions, type EventSink,
} from '@dan-build/agentstat/ag-ui';

import {
  createSseHandler, connectSse, createAgentStream,
  type SseHandlerOptions, type SseSourceOptions,
  type AgentSource, type AgentStream, type AgentStreamMessage,
  type Agent, type AgentEvent,
} from '@dan-build/agentstat/sse';