telemetry

type Exporter interface {
	BeginTurn(ctx context.Context, meta TurnMeta) (context.Context, func(TurnEnd))
	BeginObservation(ctx context.Context, meta ObservationMeta) (context.Context, func(ObservationEnd))
	RecordEvent(ctx context.Context, name string, attrs map[string]string)
	Flush(ctx context.Context) error
	Shutdown(ctx context.Context) error
}

type ObservationEnd struct {
	Output string
	Err    error
	Usage  *Usage
	// CompletionStartTime is when the model first produced output (TTFT boundary).
	// Zero means unavailable, e.g. the stream ended before any content arrived.
	CompletionStartTime time.Time
	// FirstTextTime is when the first user-visible text or thinking delta arrived.
	// Langfuse TTFT prefers this over CompletionStartTime when set.
	FirstTextTime time.Time
}

type ObservationKind string

type ObservationMeta struct {
	Name  string
	Kind  ObservationKind
	Model string
	Input string
	// ToolNames lists model-visible tools for an LLM generation.
	ToolNames []string
	// AgentID labels which agent produced this observation.
	AgentID string
	// SessionID labels the session that produced this observation.
	SessionID string
	// Scope marks a span that should parent nested generations (e.g. subagent.turn).
	Scope bool
}

type TurnEnd struct {
	Output     string
	Err        error
	Usage      *Usage
	Steps      int
	StopReason string
}

type TurnMeta struct {
	TurnID            string
	SessionID         string
	DeliverySessionID string
	AgentID           string
	PlatformID        string
	UserID            string
	Input             string
}

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}