observation

package
v0.3.37 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 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"
	CompactionPhaseCancelled  = "cancelled"
	CompactionStatusRunning   = "running"
	CompactionStatusCompacted = "compacted"
	CompactionStatusFailed    = "failed"
	CompactionStatusCancelled = "cancelled"
)
View Source 
const (
	EventTypeContextCompactDebug = "context_compact_debug"

	CompactionDebugStageBegin                   = "begin"
	CompactionDebugStagePoll                    = "poll"
	CompactionDebugStagePreflight               = "preflight"
	CompactionDebugStageGenerateAttemptStart    = "generate_attempt_start"
	CompactionDebugStageGenerateAttemptComplete = "generate_attempt_complete"
	CompactionDebugStageRequestRebuildStart     = "request_rebuild_start"
	CompactionDebugStageRequestRebuildComplete  = "request_rebuild_complete"
	CompactionDebugStageRequestValidation       = "request_validation"
	CompactionDebugStageInstallStart            = "install_start"
	CompactionDebugStageInstallComplete         = "install_complete"

	CompactionDebugStatusRunning   = "running"
	CompactionDebugStatusOK        = "ok"
	CompactionDebugStatusRetrying  = "retrying"
	CompactionDebugStatusFailed    = "failed"
	CompactionDebugStatusCancelled = "cancelled"
)
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 CompactionDebugEvent added in v0.3.28 

type CompactionDebugEvent struct {
	RunID                            string                 `json:"run_id,omitempty"`
	ThreadID                         string                 `json:"thread_id,omitempty"`
	TurnID                           string                 `json:"turn_id,omitempty"`
	Step                             int                    `json:"step,omitempty"`
	OperationID                      string                 `json:"operation_id,omitempty"`
	RequestID                        string                 `json:"request_id,omitempty"`
	Stage                            string                 `json:"stage"`
	Status                           string                 `json:"status"`
	Trigger                          string                 `json:"trigger,omitempty"`
	Reason                           string                 `json:"reason,omitempty"`
	Source                           string                 `json:"source,omitempty"`
	CompactionConvergenceAttempt     int                    `json:"compaction_convergence_attempt,omitempty"`
	HistoryMessageCount              int                    `json:"history_message_count,omitempty"`
	ActiveMessageCount               int                    `json:"active_message_count,omitempty"`
	TokensBefore                     int64                  `json:"tokens_before,omitempty"`
	TokensAfterEstimate              int64                  `json:"tokens_after_estimate,omitempty"`
	ContextBefore                    config.ContextUsage    `json:"context_before,omitempty"`
	ContextAfter                     config.ContextUsage    `json:"context_after,omitempty"`
	BeforePressure                   config.ContextPressure `json:"before_pressure,omitempty"`
	RequestEstimate                  config.RequestEstimate `json:"request_estimate,omitempty"`
	ValidatedContextPressure         config.ContextPressure `json:"validated_context_pressure,omitempty"`
	HardLimitExceeded                bool                   `json:"hard_limit_exceeded,omitempty"`
	FixedInputTokens                 int64                  `json:"fixed_input_tokens,omitempty"`
	ReducibleInputTokens             int64                  `json:"reducible_input_tokens,omitempty"`
	RequestSafeLimit                 int64                  `json:"request_safe_limit,omitempty"`
	CompactedContextTargetTokens     int64                  `json:"compacted_context_target_tokens,omitempty"`
	NextCompactedContextTargetTokens int64                  `json:"next_compacted_context_target_tokens,omitempty"`
	ConsecutiveFailures              int                    `json:"consecutive_failures,omitempty"`
	DurationMS                       int64                  `json:"duration_ms,omitempty"`
	ProviderStateKind                string                 `json:"provider_state_kind,omitempty"`
	NextAction                       string                 `json:"next_action,omitempty"`
	Error                            string                 `json:"error,omitempty"`
	ObservedAt                       time.Time              `json:"observed_at"`
}

func CompactionDebugEventFromEvent added in v0.3.28 

func CompactionDebugEventFromEvent(ev Event) (CompactionDebugEvent, bool)

func CompactionDebugEventsFromEvents added in v0.3.28 

func CompactionDebugEventsFromEvents(events []Event) []CompactionDebugEvent

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"`
	OperationID         string                 `json:"operation_id,omitempty"`
	RequestID           string                 `json:"request_id,omitempty"`
	Phase               string                 `json:"phase"`
	Status              string                 `json:"status"`
	Trigger             string                 `json:"trigger,omitempty"`
	Reason              string                 `json:"reason,omitempty"`
	Source              string                 `json:"source,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"`
}

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"`
	Compaction      *CompactionEvent      `json:"compaction,omitempty"`
	CompactionDebug *CompactionDebugEvent `json:"compaction_debug,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"`
}

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"`
}

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.