@sensu-ai/shared

Shared Zod schemas and TypeScript types for the Sensu event model.

Used internally by the Sensu API, web dashboard, and @sensu-ai/sdk. Published separately so external consumers can validate and type Sensu events without taking a dependency on the full SDK.

Installation

npm install @sensu-ai/shared

Usage

Validate an incoming event

import { TelemetryEventSchema } from '@sensu-ai/shared';

const result = TelemetryEventSchema.safeParse(rawEvent);
if (!result.success) {
  console.error(result.error.issues);
}

Validate a batch

import { BatchEventsSchema } from '@sensu-ai/shared';

const result = BatchEventsSchema.safeParse({ events: [...] });

Use the types

import type {
  TelemetryEvent,
  LlmRequestStarted,
  LlmRequestCompleted,
  RunStarted,
  ToolCallCompleted,
  // Quality & analytics
  AgentQualityScorecard,
  RunDag,
  RunDagNode,
  RunDagEdge,
  // Guardrails
  GuardrailDashboard,
  // Prompt history
  PromptDeployment,
  PromptDeploymentImpact,
  // Cost attribution
  CostByTag,
  TagCostRow,
  // Session replay
  RunMessageSnapshot,
} from '@sensu-ai/shared';

Event model

All events share a common base and are discriminated by event_type:

| event_type | Description | |---|---| | agent.run.started | An agent run began | | agent.run.completed | An agent run completed successfully | | agent.run.failed | An agent run failed | | agent.step.started | A step within a run began | | agent.step.completed | A step completed | | llm.request.started | An LLM call was initiated | | llm.request.completed | An LLM call returned (includes token counts, latency, cost) | | tool.call.started | A tool call was initiated | | tool.call.completed | A tool call returned (includes latency, status, sizes) | | retrieval.completed | A vector store retrieval returned (includes chunk count, latency) | | embedding.created | An embedding was generated | | guardrail.check.completed | A guardrail check ran and returned a result |

agent.run.started fields

The tags field on agent.run.started is a free-form Record<string, string> that lets you slice cost and usage by arbitrary dimensions (team, customer, environment, etc.) in the Cost by Tag dashboard.

Base fields (all events)

| Field | Type | Description | |---|---|---| | event_id | string (uuid) | Unique event identifier | | event_type | EventType | Discriminant | | timestamp | string (datetime) | ISO 8601 | | agent_id | string | Agent identifier | | session_id | string | Session identifier | | run_id | string | Run identifier | | trace_id | string | Distributed trace identifier | | span_id | string | Span identifier | | parent_span_id | string? | Parent span for nested operations | | org_id | string? | Organisation identifier |

Exports

• Schemas — TelemetryEventSchema, BatchEventsSchema, and individual event schemas (LlmRequestStartedSchema, RunStartedSchema, etc.)
• Types — TypeScript types inferred from all schemas
• Auth schemas — SignupSchema, LoginSchema, CreateApiKeySchema
• API response schemas — AgentSummarySchema, LiveDashboardSchema, RunDetailSchema, and more
• Socket.io interfaces — ServerToClientEvents, ClientToServerEvents
• Quality & analytics — AgentQualityScorecard, QualityDailyPoint, EvalMetricSummary
• Multi-agent DAG — RunDag, RunDagNode, RunDagEdge
• Guardrails — GuardrailDashboard, GuardrailTimePoint, GuardrailTypeBreakdown, GuardrailTopReason, GuardrailAgentBreakdown
• Prompt history — PromptDeployment, PromptDeploymentImpact, PromptPeriodMetrics
• Cost attribution — CostByTag, TagCostRow
• Session replay — RunMessageSnapshot, MessageSnapshotEntry
• Alert types — AlertRule, AlertSeverity, AlertCondition ('gt' | 'lt' | 'spike' | 'deviation'), AlertMetric