observation

package
v0.3.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 19, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package observation defines host-facing runtime observation DTOs.

Runtime events are presentation-neutral facts, and those facts may still be too low-level for a host UI or API response. Package observation projects selected events and narrow observation DTOs into stable, UI-neutral status records that a host can render without parsing assistant text, exposing prompt-cache storage records, or depending on internal inspection types.

Observation values are not raw debug records. They intentionally omit provider payloads, model deltas, reasoning, tool arguments, tool results, and local paths. Hosts that need raw local inspection should build that capability as an explicit privileged surface behind its own product boundary.

Index

Constants

View Source 
const (
	EventTypeToolCall              = "tool_call"
	EventTypeToolResult            = "tool_result"
	EventTypeToolApprovalRequested = "tool_approval_requested"
	EventTypeToolApprovalApproved  = "tool_approval_approved"
	EventTypeToolApprovalRejected  = "tool_approval_rejected"
	EventTypeToolApprovalTimedOut  = "tool_approval_timed_out"
	EventTypeToolApprovalCanceled  = "tool_approval_canceled"
	EventTypeHostedToolCall        = "hosted_tool_call"
	EventTypeHostedToolResult      = "hosted_tool_result"
	EventTypeControlSignal         = "control_signal"
	EventTypeBudgetExceeded        = "budget_exceeded"
	EventTypeRunEnd                = "run_end"

	ActivityTimelineSchemaVersion = 1

	ActivityKindTool     ActivityKind = "tool"
	ActivityKindHosted   ActivityKind = "hosted_tool"
	ActivityKindApproval ActivityKind = "approval"
	ActivityKindControl  ActivityKind = "control"
	ActivityKindBudget   ActivityKind = "budget"
)
View Source 
const (
	EventTypeProviderUsage    = "provider_usage"
	EventTypeContextCompact   = "context_compact"
	CompactionPhaseStart      = "start"
	CompactionPhaseComplete   = "complete"
	CompactionPhaseFailed     = "failed"
	CompactionStatusRunning   = "running"
	CompactionStatusCompacted = "compacted"
	CompactionStatusFailed    = "failed"
)
View Source 
const (
	ContextPhaseProjectedRequest = "projected_request"
	ContextPhaseProviderUsage    = "provider_usage"

	ContextStatusStable        = "stable"
	ContextStatusNearThreshold = "near_threshold"
	ContextStatusWillCompact   = "will_compact"
	ContextStatusHardLimit     = "hard_limit"
	ContextStatusEstimated     = "estimated"

	ProviderUsagePhaseStreamUsage        = "stream_usage"
	ProviderUsagePhaseFinalContextStatus = "final_context_status"
)

Variables

This section is empty.

Functions

func ContextPressureDisplayStatus added in v0.3.0 

func ContextPressureDisplayStatus(pressure config.ContextPressure) string

func ContextPressureThresholdRatio added in v0.3.0 

func ContextPressureThresholdRatio(pressure config.ContextPressure) float64

func ContextPressureUsedRatio added in v0.3.0 

func ContextPressureUsedRatio(pressure config.ContextPressure) float64

func RequestID 

func RequestID(runID string, step int) string

func SortContextStatuses 

func SortContextStatuses(statuses []ContextStatus)

func ValidateActivityTimeline added in v0.3.4 

func ValidateActivityTimeline(timeline ActivityTimeline) error

Types

type ActivityAttentionReason added in v0.3.4 

type ActivityAttentionReason string
const (
	ActivityAttentionRunning  ActivityAttentionReason = "running"
	ActivityAttentionWaiting  ActivityAttentionReason = "waiting"
	ActivityAttentionApproval ActivityAttentionReason = "approval"
	ActivityAttentionError    ActivityAttentionReason = "error"
)

type ActivityChip added in v0.3.7 

type ActivityChip struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	Value string `json:"value,omitempty"`
	Tone  string `json:"tone,omitempty"`
}

type ActivityCounts added in v0.3.4 

type ActivityCounts struct {
	Pending  int `json:"pending,omitempty"`
	Running  int `json:"running,omitempty"`
	Waiting  int `json:"waiting,omitempty"`
	Success  int `json:"success,omitempty"`
	Error    int `json:"error,omitempty"`
	Canceled int `json:"canceled,omitempty"`
	Approval int `json:"approval,omitempty"`
}

type ActivityItem added in v0.3.4 

type ActivityItem struct {
	ItemID           string                    `json:"item_id"`
	ToolID           string                    `json:"tool_id,omitempty"`
	ToolName         string                    `json:"tool_name,omitempty"`
	Kind             ActivityKind              `json:"kind"`
	Status           ActivityStatus            `json:"status"`
	Severity         ActivitySeverity          `json:"severity"`
	NeedsAttention   bool                      `json:"needs_attention"`
	AttentionReasons []ActivityAttentionReason `json:"attention_reasons,omitempty"`
	RequiresApproval bool                      `json:"requires_approval"`
	ApprovalState    string                    `json:"approval_state,omitempty"`
	StartedAtUnixMS  int64                     `json:"started_at_unix_ms,omitempty"`
	EndedAtUnixMS    int64                     `json:"ended_at_unix_ms,omitempty"`
	Label            string                    `json:"label,omitempty"`
	Description      string                    `json:"description,omitempty"`
	Renderer         ActivityRenderer          `json:"renderer,omitempty"`
	Chips            []ActivityChip            `json:"chips,omitempty"`
	TargetRefs       []ActivityTargetRef       `json:"target_refs,omitempty"`
	Payload          map[string]any            `json:"payload,omitempty"`
	Metadata         map[string]string         `json:"metadata,omitempty"`
}

type ActivityKind added in v0.3.4 

type ActivityKind string

type ActivityPresentation added in v0.3.7 

type ActivityPresentation struct {
	Label       string              `json:"label,omitempty"`
	Description string              `json:"description,omitempty"`
	Renderer    ActivityRenderer    `json:"renderer,omitempty"`
	Chips       []ActivityChip      `json:"chips,omitempty"`
	TargetRefs  []ActivityTargetRef `json:"target_refs,omitempty"`
	Payload     map[string]any      `json:"payload,omitempty"`
}

type ActivityRenderer added in v0.3.7 

type ActivityRenderer string
const (
	ActivityRendererStructured ActivityRenderer = "structured"
	ActivityRendererTerminal   ActivityRenderer = "terminal"
	ActivityRendererFile       ActivityRenderer = "file"
	ActivityRendererPatch      ActivityRenderer = "patch"
	ActivityRendererWebSearch  ActivityRenderer = "web_search"
	ActivityRendererTodos      ActivityRenderer = "todos"
	ActivityRendererQuestion   ActivityRenderer = "question"
	ActivityRendererCompletion ActivityRenderer = "completion"
)

type ActivityRunMeta added in v0.3.4 

type ActivityRunMeta struct {
	RunID    string `json:"run_id,omitempty"`
	ThreadID string `json:"thread_id,omitempty"`
	TurnID   string `json:"turn_id,omitempty"`
	TraceID  string `json:"trace_id,omitempty"`
}

type ActivitySeverity added in v0.3.4 

type ActivitySeverity string
const (
	ActivitySeverityQuiet    ActivitySeverity = "quiet"
	ActivitySeverityNormal   ActivitySeverity = "normal"
	ActivitySeverityWarning  ActivitySeverity = "warning"
	ActivitySeverityError    ActivitySeverity = "error"
	ActivitySeverityBlocking ActivitySeverity = "blocking"
)

type ActivityStatus added in v0.3.4 

type ActivityStatus string
const (
	ActivityStatusPending  ActivityStatus = "pending"
	ActivityStatusRunning  ActivityStatus = "running"
	ActivityStatusWaiting  ActivityStatus = "waiting"
	ActivityStatusSuccess  ActivityStatus = "success"
	ActivityStatusError    ActivityStatus = "error"
	ActivityStatusCanceled ActivityStatus = "canceled"
)

type ActivitySummary added in v0.3.4 

type ActivitySummary struct {
	Status           ActivityStatus            `json:"status"`
	Severity         ActivitySeverity          `json:"severity"`
	NeedsAttention   bool                      `json:"needs_attention"`
	AttentionReasons []ActivityAttentionReason `json:"attention_reasons,omitempty"`
	TotalItems       int                       `json:"total_items"`
	Counts           ActivityCounts            `json:"counts"`
	DurationMS       int64                     `json:"duration_ms,omitempty"`
}

type ActivityTargetRef added in v0.3.7 

type ActivityTargetRef struct {
	Kind  string `json:"kind"`
	Label string `json:"label"`
	URI   string `json:"uri,omitempty"`
	Path  string `json:"path,omitempty"`
	Line  int    `json:"line,omitempty"`
}

type ActivityTimeline added in v0.3.4 

type ActivityTimeline struct {
	SchemaVersion int             `json:"schema_version"`
	RunID         string          `json:"run_id,omitempty"`
	ThreadID      string          `json:"thread_id,omitempty"`
	TurnID        string          `json:"turn_id,omitempty"`
	TraceID       string          `json:"trace_id,omitempty"`
	Summary       ActivitySummary `json:"summary"`
	Items         []ActivityItem  `json:"items"`
}

func BuildActivityTimeline added in v0.3.4 

func BuildActivityTimeline(meta ActivityRunMeta, events []Event, nowUnixMS int64) ActivityTimeline

BuildActivityTimeline projects sanitized runtime events into a stable activity summary. Tool-facing display details enter the timeline only through an explicit ActivityPresentation that has already crossed the event sanitizer.

type CompactionEvent 

type CompactionEvent struct {
	RunID                   string                 `json:"run_id,omitempty"`
	ThreadID                string                 `json:"thread_id,omitempty"`
	TurnID                  string                 `json:"turn_id,omitempty"`
	Step                    int                    `json:"step,omitempty"`
	Phase                   string                 `json:"phase"`
	Status                  string                 `json:"status"`
	Trigger                 string                 `json:"trigger,omitempty"`
	Reason                  string                 `json:"reason,omitempty"`
	CompactionID            string                 `json:"compaction_id,omitempty"`
	CompactionGeneration    int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID      string                 `json:"compaction_window_id,omitempty"`
	CompactedThroughEntryID string                 `json:"compacted_through_entry_id,omitempty"`
	TokensBefore            int64                  `json:"tokens_before,omitempty"`
	TokensAfterEstimate     int64                  `json:"tokens_after_estimate,omitempty"`
	BeforePressure          config.ContextPressure `json:"before_pressure,omitempty"`
	ContextBefore           config.ContextUsage    `json:"context_before,omitempty"`
	ContextAfter            config.ContextUsage    `json:"context_after,omitempty"`
	Error                   string                 `json:"error,omitempty"`
	ObservedAt              time.Time              `json:"observed_at"`
}

func CompactionEventFromEvent added in v0.3.0 

func CompactionEventFromEvent(ev Event) (CompactionEvent, bool)

func CompactionEventsFromEvents added in v0.3.0 

func CompactionEventsFromEvents(events []Event) []CompactionEvent

type ContextStatus 

type ContextStatus struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step,omitempty"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Phase                string                 `json:"phase"`
	Provider             string                 `json:"provider,omitempty"`
	Model                string                 `json:"model,omitempty"`
	ObservedAt           time.Time              `json:"observed_at"`
	Usage                ProviderUsage          `json:"usage,omitempty"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ContextPressure      config.ContextPressure `json:"context_pressure,omitempty"`
	UsedRatio            float64                `json:"used_ratio,omitempty"`
	ThresholdRatio       float64                `json:"threshold_ratio,omitempty"`
	Status               string                 `json:"status"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

func ContextStatusFromProviderUsage 

func ContextStatusFromProviderUsage(usage ProviderUsageObservation) (ContextStatus, bool)

func ContextStatusFromProviderUsageEvent 

func ContextStatusFromProviderUsageEvent(ev Event) (ContextStatus, bool)

func ContextStatusFromRequest 

func ContextStatusFromRequest(req RequestObservation) ContextStatus

func ContextStatusesFromObservations 

func ContextStatusesFromObservations(requests []RequestObservation, usages []ProviderUsageObservation, events []Event) []ContextStatus

func ContextStatusesFromRequests 

func ContextStatusesFromRequests(requests []RequestObservation, events []Event) []ContextStatus

func (ContextStatus) PhaseOrder 

func (s ContextStatus) PhaseOrder() int

type Event added in v0.3.0 

type Event struct {
	Type         string                `json:"type"`
	TraceID      string                `json:"trace_id,omitempty"`
	RunID        string                `json:"run_id,omitempty"`
	ThreadID     string                `json:"thread_id,omitempty"`
	TurnID       string                `json:"turn_id,omitempty"`
	Step         int                   `json:"step,omitempty"`
	Provider     string                `json:"provider,omitempty"`
	Model        string                `json:"model,omitempty"`
	Message      string                `json:"message,omitempty"`
	Result       string                `json:"result,omitempty"`
	Error        string                `json:"error,omitempty"`
	ToolID       string                `json:"tool_id,omitempty"`
	ToolName     string                `json:"tool_name,omitempty"`
	ToolKind     string                `json:"tool_kind,omitempty"`
	ArgsHash     string                `json:"args_hash,omitempty"`
	DurationMS   int64                 `json:"duration_ms,omitempty"`
	FinishReason string                `json:"finish_reason,omitempty"`
	Activity     *ActivityPresentation `json:"activity,omitempty"`
	Metadata     map[string]any        `json:"metadata,omitempty"`
	ObservedAt   time.Time             `json:"observed_at"`
}

type ProviderUsage added in v0.3.0 

type ProviderUsage struct {
	InputTokens       int64   `json:"input_tokens,omitempty"`
	OutputTokens      int64   `json:"output_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens   int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens  int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens       int64   `json:"total_tokens,omitempty"`
	WindowInputTokens int64   `json:"window_input_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
	Source            string  `json:"source,omitempty"`
	Available         bool    `json:"available,omitempty"`
}

func (ProviderUsage) Normalized added in v0.3.0 

func (u ProviderUsage) Normalized() ProviderUsage

type ProviderUsageObservation 

type ProviderUsageObservation struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step,omitempty"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Provider             string                 `json:"provider,omitempty"`
	Model                string                 `json:"model,omitempty"`
	ObservedAt           time.Time              `json:"observed_at"`
	Usage                ProviderUsage          `json:"usage,omitempty"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ContextPressure      config.ContextPressure `json:"context_pressure,omitempty"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

type RequestObservation 

type RequestObservation struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Provider             string                 `json:"provider"`
	Model                string                 `json:"model"`
	ObservedAt           time.Time              `json:"observed_at"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ProjectedPressure    config.ContextPressure `json:"projected_context_pressure,omitempty"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.