Skip to content
reaatechREAATECH
Book a conversation

@reaatech/agent-replay-shared

npm v0.1.0

Provides the canonical TypeScript types, interfaces, and error classes for the Agent Replay ecosystem. It serves as the shared schema definition for trace models, LLM abstractions, and storage contracts used across all related packages.

agentreplayllmtypes
npm →source →

@reaatech/agent-replay-shared

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Shared types, interfaces, error classes, and configuration for the Agent Replay ecosystem. This package is the canonical source of truth for all trace model shapes, LLM provider abstractions, and storage contracts used by every other @reaatech/agent-replay-* package.

Installation

terminal
npm install @reaatech/agent-replay-shared
# or
pnpm add @reaatech/agent-replay-shared

Feature Overview

  • 100+ exported types and interfaces — complete trace model, LLM abstractions, storage contracts, and configuration shapes
  • 7 typed error classes — RecordingFailedError, ReplayFailedError, StateCaptureError, and more — all extending a serializable AgentReplayError base
  • Zero runtime dependencies — pure TypeScript types and abstract interfaces, fully tree-shakeable
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  type Trace,
  type Span,
  type LLMRequest,
  type LLMResponse,
  type RecordingConfig,
  type ReplayConfig,
  TraceNotFoundError,
  AgentReplayError,
} from "@reaatech/agent-replay-shared";

This package is a dependency of every other Agent Replay package. Most consumers will get these types transitively through @reaatech/agent-replay-core or the convenience @reaatech/agent-replay package.

Exports

Trace Data Model

The trace is the fundamental unit — a complete record of an agent interaction.

ExportDescription
TraceTop-level container: version, metadata, spans, checkpoints, indexes
TraceMetadataTrace identity: id, name, createdAt, agentVersion, environment, tags, summary
TraceSummaryLightweight header for list/search operations
TraceHeaderSerialization header with schema version and format info
TraceIndexesFast lookup indexes: byId (span id → array index) and byKind
SpanA single unit of work: id, parentId, name, kind, timestamps, status, events, attributes, links
SpanLinkCross-trace reference: traceId, spanId, optional attributes
EventA timestamped data point within a span: timestamp, type, name, attributes, data
CheckpointSerialized agent state at a point in time: id, spanId, timestamp, state, context, metadata
CheckpointMetadataName and optional description for a checkpoint
SerializedStateFull state snapshot: variables, memory, conversation, toolRegistry
MemorySnapshot / MemoryEntryKey-value memory entries with timestamps
ConversationStateArray of Message objects representing chat history
MessageA chat message: role (system | user | assistant | tool), content, toolCalls?, toolCallId?
ToolCallA tool invocation: id, name, arguments
ToolDefinitionA declared tool: name, description, parameters
ToolRegistrySnapshotArray of ToolDefinition available at capture time
AgentContextSession-scoped context for checkpoints: sessionId, variables
CaptureContextOptions for captureEvent: spanId?, timestamp?

Enumerated Types

TypeValues
SpanKindllm_call | tool_call | agent_step | routing_decision | state_change | error
SpanStatusok | error | in_progress
EventTyperequest | response | error | state_snapshot | checkpoint | annotation

LLM Provider Abstractions

Provider-agnostic types that all interceptors normalize into.

ExportDescription
LLMRequestNormalized request: provider, model, messages, tools?, temperature?, maxTokens?, topP?, stopSequences?, raw
LLMResponseNormalized response: id, model, content, toolCalls?, usage?, finishReason, raw
StreamChunkA single streaming delta: index, delta, toolCallDelta?, finishReason?, usage?
RecordedStreamComplete stream recording: chunks array, aggregatedContent, aggregatedToolCalls?, duration, totalChunks
TokenUsagePrompt, completion, and total token counts

Error Hierarchy

All errors extend the abstract AgentReplayError base class, which provides machine-readable code, optional cause, and JSON serialization via toJSON().

Error ClassCodeWhen
AgentReplayError(base)Base class for all errors
RecordingFailedErrorRECORDING_FAILEDRecording session could not start or complete
TraceNotFoundErrorTRACE_NOT_FOUNDRequested trace file does not exist
InvalidTraceErrorINVALID_TRACETrace data failed validation with ValidationError[]
ReplayFailedErrorREPLAY_FAILEDReplay failed at a specific step
StateCaptureErrorSTATE_CAPTURE_FAILEDState serialization failed for a given state type
DivergenceErrorDIVERGENCE_DETECTEDLive replay diverged from the recorded trace
InterceptorErrorINTERCEPTOR_FAILEDLLM provider interceptor could not be installed

Storage Abstractions

ExportDescription
TraceStoragePluggable interface: save, load, list, delete, search
StorageOptionsCompression and encryption flags
TraceFilterFilter traces by tags, date range, or status
SearchQueryFull-text search with limit and offset
TraceSearchResultPaginated results with total count

Configuration

ExportDescription
RecordingConfigRecording options: name, providers?, outputPath?, captureState?, checkpointInterval?, tags?
ReplayConfigBase replay config: mode, checkpointId?, maxSteps?, timeout?, onProgress?, signal?
PartialReplayConfigExtends ReplayConfig with mode: "partial" and required checkpointId
DiffReplayConfigExtends ReplayConfig with mode: "diff" and optional diffOptions
ReplayProgressProgress callback payload: percent, currentStep, totalSteps
ReplayResultReplay output: trace, outputs, duration, divergence?
DivergenceReportWhen live replay diverges: step, expected, actual, path
DiffOptionsDiff configuration: includeSemantic?, includeStructural?, similarityThreshold?
DiffResultDiff output: diffs[], statistics, report, severity
TraceDiffIndividual difference: type, severity, message, details
DiffStatisticsSummary: totalDifferences, semanticChanges, structuralChanges

Related Packages

License

MIT

All packagesagent-replay overview