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
- func CloneActivityPresentation(in *tools.ActivityPresentation) *tools.ActivityPresentation
- func ContextPressureThresholdRatio(pressure config.ContextPressure) float64
- func ContextPressureUsedRatio(pressure config.ContextPressure) float64
- func RequestID(runID string, step int) string
- func SortContextStatuses(statuses []ContextStatus)
- func ValidateActivityTimeline(timeline ActivityTimeline) error
- type ActivityAttentionReason
- type ActivityCounts
- type ActivityItem
- type ActivityKind
- type ActivityRunMeta
- type ActivitySeverity
- type ActivityStatus
- type ActivitySummary
- type ActivityTimeline
- type CompactionDebugEvent
- type CompactionDebugStage
- type CompactionDebugStatus
- type CompactionEvent
- type CompactionPhase
- type CompactionStatus
- type CompletionReason
- type ContextDisplayStatus
- type ContextPhase
- type ContextStatus
- func ContextStatusFromProviderUsage(usage ProviderUsageObservation) (ContextStatus, bool)
- func ContextStatusFromProviderUsageEvent(ev Event) (ContextStatus, bool)
- func ContextStatusFromRequest(req RequestObservation) ContextStatus
- func ContextStatusesFromObservations(requests []RequestObservation, usages []ProviderUsageObservation, ...) []ContextStatus
- func ContextStatusesFromRequests(requests []RequestObservation, events []Event) []ContextStatus
- type ContinuationReason
- type Event
- type EventType
- type FinishReason
- type ProviderUsage
- type ProviderUsageObservation
- type RequestObservation
Constants ¶
const ( CompactionPhaseStart CompactionPhase = "start" CompactionPhaseComplete CompactionPhase = "complete" CompactionPhaseFailed CompactionPhase = "failed" CompactionPhaseCancelled CompactionPhase = "cancelled" CompactionPhaseNoop CompactionPhase = "noop" CompactionStatusRunning CompactionStatus = "running" CompactionStatusCompacted CompactionStatus = "compacted" CompactionStatusFailed CompactionStatus = "failed" CompactionStatusCancelled CompactionStatus = "cancelled" CompactionStatusNoop CompactionStatus = "noop" )
const ( CompactionDebugStageBegin CompactionDebugStage = "begin" CompactionDebugStagePoll CompactionDebugStage = "poll" CompactionDebugStagePreflight CompactionDebugStage = "preflight" CompactionDebugStageGenerateAttemptStart CompactionDebugStage = "generate_attempt_start" CompactionDebugStageGenerateAttemptComplete CompactionDebugStage = "generate_attempt_complete" CompactionDebugStageRequestRebuildStart CompactionDebugStage = "request_rebuild_start" CompactionDebugStageRequestRebuildComplete CompactionDebugStage = "request_rebuild_complete" CompactionDebugStageRequestValidation CompactionDebugStage = "request_validation" CompactionDebugStageInstallStart CompactionDebugStage = "install_start" CompactionDebugStageInstallComplete CompactionDebugStage = "install_complete" CompactionDebugStatusRunning CompactionDebugStatus = "running" CompactionDebugStatusOK CompactionDebugStatus = "ok" CompactionDebugStatusRetrying CompactionDebugStatus = "retrying" CompactionDebugStatusFailed CompactionDebugStatus = "failed" CompactionDebugStatusCancelled CompactionDebugStatus = "cancelled" )
const ( ContextPhaseProjectedRequest ContextPhase = "projected_request" ContextPhaseProviderUsage ContextPhase = "provider_usage" ContextStatusStable ContextDisplayStatus = "stable" ContextStatusNearThreshold ContextDisplayStatus = "near_threshold" ContextStatusWillCompact ContextDisplayStatus = "will_compact" ContextStatusHardLimit ContextDisplayStatus = "hard_limit" ContextStatusEstimated ContextDisplayStatus = "estimated" ProviderUsagePhaseStreamUsage = "stream_usage" ProviderUsagePhaseFinalContextStatus = "final_context_status" )
Variables ¶
This section is empty.
Functions ¶
func CloneActivityPresentation ¶
func CloneActivityPresentation(in *tools.ActivityPresentation) *tools.ActivityPresentation
func ContextPressureThresholdRatio ¶
func ContextPressureThresholdRatio(pressure config.ContextPressure) float64
func ContextPressureUsedRatio ¶
func ContextPressureUsedRatio(pressure config.ContextPressure) float64
func SortContextStatuses ¶
func SortContextStatuses(statuses []ContextStatus)
func ValidateActivityTimeline ¶
func ValidateActivityTimeline(timeline ActivityTimeline) error
Types ¶
type ActivityAttentionReason ¶
type ActivityAttentionReason string
const ( ActivityAttentionRunning ActivityAttentionReason = "running" ActivityAttentionWaiting ActivityAttentionReason = "waiting" ActivityAttentionApproval ActivityAttentionReason = "approval" ActivityAttentionError ActivityAttentionReason = "error" )
type ActivityCounts ¶
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"`
Declined int `json:"declined,omitempty"`
Canceled int `json:"canceled,omitempty"`
Approval int `json:"approval,omitempty"`
}
type ActivityItem ¶
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"`
Presentation *tools.ActivityPresentation `json:"presentation,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
type ActivityKind ¶
type ActivityKind string
const ( ActivityTimelineSchemaVersion = 1 ActivityKindTool ActivityKind = "tool" ActivityKindHosted ActivityKind = "hosted_tool" ActivityKindControl ActivityKind = "control" ActivityKindBudget ActivityKind = "budget" )
type ActivityRunMeta ¶
type ActivitySeverity ¶
type ActivitySeverity string
const ( ActivitySeverityQuiet ActivitySeverity = "quiet" ActivitySeverityNormal ActivitySeverity = "normal" ActivitySeverityWarning ActivitySeverity = "warning" ActivitySeverityError ActivitySeverity = "error" ActivitySeverityBlocking ActivitySeverity = "blocking" )
type ActivityStatus ¶
type ActivityStatus string
const ( ActivityStatusPending ActivityStatus = "pending" ActivityStatusRunning ActivityStatus = "running" ActivityStatusWaiting ActivityStatus = "waiting" ActivityStatusSuccess ActivityStatus = "success" ActivityStatusError ActivityStatus = "error" ActivityStatusDeclined ActivityStatus = "declined" ActivityStatusCanceled ActivityStatus = "canceled" )
type ActivitySummary ¶
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"`
}
func RebuildActivitySummary ¶
func RebuildActivitySummary(timeline ActivityTimeline) ActivitySummary
RebuildActivitySummary recomputes item-derived summary state while preserving the timeline duration and settled run-level error or canceled status.
type ActivityTimeline ¶
type ActivityTimeline struct {
SchemaVersion int `json:"schema_version"`
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
TraceID identity.TraceID `json:"trace_id,omitempty"`
Summary ActivitySummary `json:"summary"`
Items []ActivityItem `json:"items"`
}
func BuildActivityTimeline ¶
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 tools.ActivityPresentation that has already crossed the event sanitizer.
func CloneActivityTimeline ¶
func CloneActivityTimeline(in *ActivityTimeline) *ActivityTimeline
type CompactionDebugEvent ¶
type CompactionDebugEvent struct {
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
Step int `json:"step,omitempty"`
OperationID string `json:"operation_id,omitempty"`
RequestID string `json:"request_id,omitempty"`
Stage CompactionDebugStage `json:"stage"`
Status CompactionDebugStatus `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 ¶
func CompactionDebugEventFromEvent(ev Event) (CompactionDebugEvent, bool)
func CompactionDebugEventsFromEvents ¶
func CompactionDebugEventsFromEvents(events []Event) []CompactionDebugEvent
func (CompactionDebugEvent) Validate ¶
func (e CompactionDebugEvent) Validate() error
type CompactionDebugStage ¶
type CompactionDebugStage string
func (CompactionDebugStage) Valid ¶
func (s CompactionDebugStage) Valid() bool
type CompactionDebugStatus ¶
type CompactionDebugStatus string
func (CompactionDebugStatus) Valid ¶
func (s CompactionDebugStatus) Valid() bool
type CompactionEvent ¶
type CompactionEvent struct {
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
Step int `json:"step,omitempty"`
OperationID string `json:"operation_id,omitempty"`
RequestID string `json:"request_id,omitempty"`
Phase CompactionPhase `json:"phase"`
Status CompactionStatus `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 ¶
func CompactionEventFromEvent(ev Event) (CompactionEvent, bool)
func CompactionEventsFromEvents ¶
func CompactionEventsFromEvents(events []Event) []CompactionEvent
func (CompactionEvent) Validate ¶
func (e CompactionEvent) Validate() error
type CompactionPhase ¶
type CompactionPhase string
func (CompactionPhase) Valid ¶
func (p CompactionPhase) Valid() bool
type CompactionStatus ¶
type CompactionStatus string
func (CompactionStatus) Valid ¶
func (s CompactionStatus) Valid() bool
type CompletionReason ¶
type CompletionReason string
CompletionReason explains why a provider-loop decision completed a run.
const ( CompletionReasonNaturalStop CompletionReason = "natural_stop" CompletionReasonHookStop CompletionReason = "hook_stop" )
func (CompletionReason) Valid ¶
func (r CompletionReason) Valid() bool
type ContextDisplayStatus ¶
type ContextDisplayStatus string
func ContextPressureDisplayStatus ¶
func ContextPressureDisplayStatus(pressure config.ContextPressure) ContextDisplayStatus
func (ContextDisplayStatus) Valid ¶
func (s ContextDisplayStatus) Valid() bool
type ContextPhase ¶
type ContextPhase string
func (ContextPhase) Valid ¶
func (p ContextPhase) Valid() bool
type ContextStatus ¶
type ContextStatus struct {
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
Step int `json:"step,omitempty"`
RequestID string `json:"request_id,omitempty"`
LogicalRequestID identity.LogicalRequestID `json:"logical_request_id,omitempty"`
Attempt int `json:"attempt,omitempty"`
Phase ContextPhase `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 ContextDisplayStatus `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
func (ContextStatus) Validate ¶
func (s ContextStatus) Validate() error
type ContinuationReason ¶
type ContinuationReason string
ContinuationReason explains why a provider-loop decision continued.
const ( ContinuationReasonToolResults ContinuationReason = "tool_results" ContinuationReasonCompaction ContinuationReason = "compaction" ContinuationReasonProviderTruncated ContinuationReason = "provider_truncated" ContinuationReasonRetryEmpty ContinuationReason = "retry_empty" ContinuationReasonNoProgress ContinuationReason = "no_progress" ContinuationReasonHook ContinuationReason = "hook" )
func (ContinuationReason) Valid ¶
func (r ContinuationReason) Valid() bool
type Event ¶
type Event struct {
Type EventType `json:"type"`
TraceID identity.TraceID `json:"trace_id,omitempty"`
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `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 FinishReason `json:"finish_reason,omitempty"`
RawFinishReason string `json:"raw_finish_reason,omitempty"`
FinishInferred bool `json:"finish_inferred,omitempty"`
CompletionReason CompletionReason `json:"completion_reason,omitempty"`
ContinuationReason ContinuationReason `json:"continuation_reason,omitempty"`
Activity *tools.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 EventType ¶
type EventType string
EventType identifies one sanitized runtime lifecycle fact.
const ( EventTypeStepStart EventType = "step_start" EventTypeProviderRequest EventType = "provider_request" EventTypeProviderDelta EventType = "provider_delta" EventTypeProviderReasoning EventType = "provider_reasoning" EventTypeProviderToolCallStart EventType = "provider_tool_call_start" EventTypeProviderToolCallDelta EventType = "provider_tool_call_delta" EventTypeProviderToolCallEnd EventType = "provider_tool_call_end" EventTypeProviderUsage EventType = "provider_usage" EventTypeProviderSources EventType = "provider_sources" EventTypeProviderFinish EventType = "provider_finish" EventTypeProviderRetry EventType = "provider_retry" EventTypeToolCall EventType = "tool_call" EventTypeToolDispatchStarted EventType = "tool_dispatch_started" EventTypeToolActivityUpdated EventType = "tool_activity_updated" EventTypeToolResult EventType = "tool_result" EventTypeToolApprovalRequested EventType = "tool_approval_requested" EventTypeToolApprovalApproved EventType = "tool_approval_approved" EventTypeToolApprovalRejected EventType = "tool_approval_rejected" EventTypeToolApprovalTimedOut EventType = "tool_approval_timed_out" EventTypeToolApprovalCanceled EventType = "tool_approval_canceled" EventTypeHostedToolCall EventType = "hosted_tool_call" EventTypeHostedToolResult EventType = "hosted_tool_result" EventTypeMCPServerConnecting EventType = "mcp_server_connecting" EventTypeMCPServerReady EventType = "mcp_server_ready" EventTypeMCPServerFailed EventType = "mcp_server_failed" EventTypeMCPToolsListed EventType = "mcp_tools_listed" EventTypeMCPToolCall EventType = "mcp_tool_call" EventTypeMCPToolResult EventType = "mcp_tool_result" EventTypeSkillDetected EventType = "skill_detected" EventTypeSkillLoaded EventType = "skill_loaded" EventTypeSkillBlocked EventType = "skill_blocked" EventTypeSkillInstallRequired EventType = "skill_install_required" EventTypeSkillDisclosureApplied EventType = "skill_disclosure_applied" EventTypeContextCompact EventType = "context_compact" EventTypeContextCompactDebug EventType = "context_compact_debug" EventTypeContextContinue EventType = "context_continue" EventTypeThreadEntryCommitted EventType = "thread_entry_committed" EventTypeThreadTitlePending EventType = "thread_title_pending" EventTypeThreadTitleUpdated EventType = "thread_title_updated" EventTypeThreadTitleFailed EventType = "thread_title_failed" EventTypeControlSignal EventType = "control_signal" EventTypeBudgetExceeded EventType = "budget_exceeded" EventTypeStepEnd EventType = "step_end" EventTypeRunEnd EventType = "run_end" )
type FinishReason ¶
type FinishReason string
FinishReason is Floret's provider-neutral normalized model finish reason.
const ( FinishReasonUnknown FinishReason = "unknown" FinishReasonStop FinishReason = "stop" FinishReasonToolCalls FinishReason = "tool_calls" FinishReasonLength FinishReason = "length" FinishReasonContentFilter FinishReason = "content_filter" FinishReasonError FinishReason = "error" FinishReasonCancelled FinishReason = "cancelled" )
func (FinishReason) Valid ¶
func (r FinishReason) Valid() bool
type ProviderUsage ¶
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 ¶
func (u ProviderUsage) Normalized() ProviderUsage
type ProviderUsageObservation ¶
type ProviderUsageObservation struct {
RunID identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
Step int `json:"step,omitempty"`
RequestID string `json:"request_id,omitempty"`
LogicalRequestID identity.LogicalRequestID `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 identity.RunID `json:"run_id,omitempty"`
ThreadID identity.ThreadID `json:"thread_id,omitempty"`
TurnID identity.TurnID `json:"turn_id,omitempty"`
Step int `json:"step"`
RequestID string `json:"request_id,omitempty"`
LogicalRequestID identity.LogicalRequestID `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"`
}