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
	// ActualModel is the catalog model id that served the call (after router/fallback/provider default).
	// When set on llm.generation, exporters should prefer this over ObservationMeta.Model (planned).
	ActualModel string
	// 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
	// GenerationMessages carries the full assembled prompt for exporters that
	// optimize generation input recording (e.g. Langfuse). Does not affect LLM calls.
	GenerationMessages []agentkit.ModelMessage
	// 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
	// Attributes are merged into exporter metadata (tool paths, delegate task, etc.).
	Attributes map[string]string
}

type Toolkit interface {
	WithExporter(context.Context, Exporter) context.Context
	ExporterFrom(context.Context) Exporter
	WithTurnID(context.Context, string) context.Context
	WithToolParent(context.Context, string) context.Context
	WithScopeParent(context.Context, string) context.Context
	ToolParentFrom(context.Context) string
	ScopeParentFrom(context.Context) string
	BeginTurn(context.Context, TurnMeta) (context.Context, func(TurnEnd))
	BeginObservation(context.Context, ObservationMeta) (context.Context, func(ObservationEnd))
	RecordEvent(context.Context, string, map[string]string)
	ObservationMetaFromContext(context.Context, ObservationMeta) ObservationMeta
	ContextObservationAttrs(context.Context) map[string]string
	EnrichEventAttrs(context.Context, map[string]string) map[string]string
	FormatMessage(agentkit.ModelMessage) string
	FormatGenerationInputForExport(prev, cur []agentkit.ModelMessage, maxFieldBytes int, dedupePrefix bool) string
	RedactJSON(string) string
	PreparePayload(raw string, maxBytes int, redact bool) string
	AttachmentSpanAttrs(attachments []agentkit.InboundAttachment) map[string]string
}

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
	// WorkspaceKey is the tenant workspace routing key (TurnEnvelope.Workspace).
	WorkspaceKey string
	// AttachmentSources lists inbound attachment paths (comma-separated, no base64).
	AttachmentSources string
	// Model is the session-effective model id for trace metadata (session/global
	// override applied; falls back to the agent's configured default).
	Model string
	Input string
}

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}