observe

package
v0.3.0-beta.4 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// OverviewAttentionKindApproval marks items waiting for an approval decision.
	OverviewAttentionKindApproval = "approval"
	// OverviewAttentionKindNeedsInput marks items escalated for operator attention.
	OverviewAttentionKindNeedsInput = "needs_input"
	// OverviewAttentionKindFailure marks items whose latest execution failed.
	OverviewAttentionKindFailure = "failure"

	// OverviewActionApprove approves an approval-gated task.
	OverviewActionApprove = "approve"
	// OverviewActionReject rejects an approval-gated task.
	OverviewActionReject = "reject"
	// OverviewActionRetry retries the failed run behind an attention item.
	OverviewActionRetry = "retry"
	// OverviewActionOpen opens the attention item's owning entity.
	OverviewActionOpen = "open"
)
View Source
const (
	TaskInboxLaneMyWork     = taskpkg.InboxLaneMyWork
	TaskInboxLaneApprovals  = taskpkg.InboxLaneApprovals
	TaskInboxLaneFailedRuns = taskpkg.InboxLaneFailedRuns
	TaskInboxLaneBlocked    = taskpkg.InboxLaneBlocked
	TaskInboxLaneArchived   = taskpkg.InboxLaneArchived
)

Variables

This section is empty.

Functions

func ValidateUsageWindowDays

func ValidateUsageWindowDays(days int) error

ValidateUsageWindowDays reports whether days is an accepted overview usage window. It is the single allowlist shared by the daemon, API, and CLI.

Types

type AgentProbeTargetSource

type AgentProbeTargetSource func(ctx context.Context) ([]acp.ProbeTarget, error)

AgentProbeTargetSource resolves the currently configured ACP-compatible agent/provider commands that should be checked in observe health.

type BridgeAggregateHealth

type BridgeAggregateHealth struct {
	TotalInstances        int                `json:"total_instances"`
	RouteCount            int                `json:"route_count"`
	DeliveryBacklog       int                `json:"delivery_backlog"`
	DeliveryDroppedTotal  int                `json:"delivery_dropped_total"`
	DeliveryFailuresTotal int                `json:"delivery_failures_total"`
	AuthFailuresTotal     int                `json:"auth_failures_total"`
	StatusCounts          BridgeStatusCounts `json:"status_counts"`
}

BridgeAggregateHealth captures the additive bridge summary included in the daemon health surface.

type BridgeInstanceHealth

type BridgeInstanceHealth struct {
	BridgeInstanceID        string                 `json:"bridge_instance_id"`
	Status                  bridgepkg.BridgeStatus `json:"status"`
	RouteCount              int                    `json:"route_count"`
	DeliveryBacklog         int                    `json:"delivery_backlog"`
	DeliveryDroppedTotal    int                    `json:"delivery_dropped_total"`
	DeliveryDroppedByReason map[string]int         `json:"delivery_dropped_by_reason,omitempty"`
	DeliveryFailuresTotal   int                    `json:"delivery_failures_total"`
	AuthFailuresTotal       int                    `json:"auth_failures_total"`
	LastSuccessAt           time.Time              `json:"last_success_at"`
	LastError               string                 `json:"last_error,omitempty"`
	LastErrorAt             time.Time              `json:"last_error_at"`
}

BridgeInstanceHealth captures the effective health/telemetry for one bridge instance.

type BridgeSource

type BridgeSource interface {
	ListInstances(ctx context.Context) ([]bridgepkg.BridgeInstance, error)
	CountBridgeRoutes(ctx context.Context, bridgeInstanceIDs []string) (map[string]int, error)
	DeliveryMetrics() map[string]bridgepkg.BridgeDeliveryMetrics
	DeliveryMetricsFor(bridgeInstanceIDs []string) (map[string]bridgepkg.BridgeDeliveryMetrics, error)
}

BridgeSource exposes the daemon-owned bridge runtime data needed by observability health and query surfaces.

type BridgeStatusCounts

type BridgeStatusCounts struct {
	Disabled     int `json:"disabled"`
	Starting     int `json:"starting"`
	Ready        int `json:"ready"`
	Degraded     int `json:"degraded"`
	AuthRequired int `json:"auth_required"`
	Error        int `json:"error"`
}

BridgeStatusCounts captures the current effective per-status instance counts.

type CostCatalog

type CostCatalog interface {
	ListModels(context.Context, modelcatalog.ListOptions) ([]modelcatalog.Model, error)
}

CostCatalog is the merged model projection consumed by usage estimation.

type FailureHealth

type FailureHealth struct {
	Status string                    `json:"status"`
	Total  int                       `json:"total"`
	ByKind map[store.FailureKind]int `json:"by_kind,omitempty"`
	Recent []SessionFailureHealth    `json:"recent,omitempty"`
}

FailureHealth summarizes persisted lifecycle failures across indexed sessions.

type Health

type Health struct {
	Status             string                  `json:"status"`
	UptimeSeconds      int64                   `json:"uptime_seconds"`
	ActiveSessions     int                     `json:"active_sessions"`
	ActiveAgents       int                     `json:"active_agents"`
	GlobalDBSizeBytes  int64                   `json:"global_db_size_bytes"`
	SessionDBSizeBytes int64                   `json:"session_db_size_bytes"`
	Persistence        PersistenceHealth       `json:"persistence"`
	Retention          RetentionHealth         `json:"retention"`
	Failures           FailureHealth           `json:"failures"`
	AgentProbes        []acp.ProbeResult       `json:"agent_probes,omitempty"`
	Bridges            BridgeAggregateHealth   `json:"bridges"`
	Tasks              TaskHealth              `json:"tasks"`
	Activities         []SessionActivityHealth `json:"activities,omitempty"`
	Version            string                  `json:"version"`
}

Health is the daemon-local observability health snapshot.

type HookCatalogSource

type HookCatalogSource interface {
	Catalog(filter hookspkg.CatalogFilter) ([]hookspkg.CatalogEntry, error)
}

HookCatalogSource provides resolved hook catalog views from the live runtime.

type HookRunStore

type HookRunStore interface {
	RecordHookRun(context.Context, hookspkg.HookRunRecord) error
	QueryHookRuns(context.Context, store.HookRunQuery) ([]hookspkg.HookRunRecord, error)
	Close(context.Context) error
}

HookRunStore is the session-scoped storage surface used for hook run audits.

type HookStoreOpener

type HookStoreOpener func(ctx context.Context, sessionID string, path string) (HookRunStore, error)

HookStoreOpener opens the per-session store used for hook run audit queries.

type LatencyMetric

type LatencyMetric struct {
	Samples       int   `json:"samples"`
	AverageMillis int64 `json:"average_ms"`
	MaximumMillis int64 `json:"maximum_ms"`
}

LatencyMetric summarizes one task-run latency family in milliseconds.

type MemoryEventSource

type MemoryEventSource interface {
	ListMemoryEventSummaries(
		ctx context.Context,
		workspaces []string,
		query store.EventSummaryQuery,
	) ([]store.EventSummary, error)
}

MemoryEventSource exposes canonical memory events across all memory DB authorities.

type Observer

type Observer struct {
	// contains filtered or unexported fields
}

Observer implements session.Notifier and exposes query/health helpers for global observability.

func New

func New(ctx context.Context, opts ...Option) (*Observer, error)

New constructs an Observer and opens the global Compozy database when needed.

func (*Observer) AttachHooks

func (o *Observer) AttachHooks(source HookCatalogSource)

AttachHooks swaps in the live hook catalog source after the hook runtime is built.

func (*Observer) CheckBridgeCatalogReady

func (o *Observer) CheckBridgeCatalogReady() error

CheckBridgeCatalogReady verifies that bounded health dependencies are wired.

func (*Observer) ClearBridgeRuntimeIssue

func (o *Observer) ClearBridgeRuntimeIssue(bridgeInstanceID string)

ClearBridgeRuntimeIssue removes the live runtime override for one instance after the adapter recovers.

func (*Observer) Close

func (o *Observer) Close(ctx context.Context) error

Close flushes and closes the backing global registry.

func (*Observer) Health

func (o *Observer) Health(ctx context.Context) (Health, error)

Health returns the current daemon-local observability health snapshot.

func (*Observer) OnAgentEvent

func (o *Observer) OnAgentEvent(ctx context.Context, sessionID string, payload any)

OnAgentEvent records one lightweight cross-session event summary and any derived aggregates.

func (*Observer) OnAgentEventForSession

func (o *Observer) OnAgentEventForSession(ctx context.Context, sess *session.Session, payload any)

OnAgentEventForSession records event summaries for the active session.

func (*Observer) OnSandboxLifecycleEvent

func (o *Observer) OnSandboxLifecycleEvent(_ context.Context, event session.SandboxLifecycleEvent)

OnSandboxLifecycleEvent receives optional sandbox lifecycle spans from session orchestration.

func (*Observer) OnSessionCreated

func (o *Observer) OnSessionCreated(ctx context.Context, sess *session.Session)

OnSessionCreated tracks the live session snapshot used by observability reads.

func (*Observer) OnSessionStopped

func (o *Observer) OnSessionStopped(_ context.Context, sess *session.Session)

OnSessionStopped removes the live snapshot after the manager persists lifecycle state.

func (*Observer) QueryBridgeEffectiveStatuses

func (o *Observer) QueryBridgeEffectiveStatuses(
	ctx context.Context,
	records []bridgepkg.BridgeCatalogRecord,
) (map[string]bridgepkg.BridgeStatus, error)

QueryBridgeEffectiveStatuses merges persisted lifecycle state with live runtime overrides.

func (*Observer) QueryBridgeHealth

func (o *Observer) QueryBridgeHealth(ctx context.Context) ([]BridgeInstanceHealth, error)

QueryBridgeHealth returns the current per-instance bridge health snapshot.

func (*Observer) QueryBridgeHealthFor

func (o *Observer) QueryBridgeHealthFor(
	ctx context.Context,
	instances []bridgepkg.BridgeInstance,
) ([]BridgeInstanceHealth, error)

QueryBridgeHealthFor returns complete health only for the supplied bridge page.

func (*Observer) QueryEvents

func (o *Observer) QueryEvents(ctx context.Context, query store.EventSummaryQuery) ([]store.EventSummary, error)

QueryEvents returns cross-session event summaries ordered for CLI/API consumption.

func (*Observer) QueryHookCatalog

func (o *Observer) QueryHookCatalog(
	ctx context.Context,
	filter hookspkg.CatalogFilter,
) ([]hookspkg.CatalogEntry, error)

QueryHookCatalog returns the resolved hook catalog for the supplied filter.

func (*Observer) QueryHookEvents

func (o *Observer) QueryHookEvents(_ context.Context, filter hookspkg.EventFilter) ([]hookspkg.EventDescriptor, error)

QueryHookEvents returns the supported hook taxonomy metadata.

func (*Observer) QueryHookRuns

func (o *Observer) QueryHookRuns(
	ctx context.Context,
	query store.HookRunQuery,
) (records []hookspkg.HookRunRecord, err error)

QueryHookRuns returns persisted per-session hook execution records.

func (*Observer) QueryObserveOverview

func (o *Observer) QueryObserveOverview(ctx context.Context, query OverviewQuery) (OverviewView, error)

QueryObserveOverview composes the home overview read model (global by default, optionally workspace-scoped).

func (*Observer) QueryPermissionLog

func (o *Observer) QueryPermissionLog(
	ctx context.Context,
	query store.PermissionLogQuery,
) ([]store.PermissionLogEntry, error)

QueryPermissionLog returns permission audit rows.

func (*Observer) QueryTaskDashboard

func (o *Observer) QueryTaskDashboard(ctx context.Context, query TaskDashboardQuery) (TaskDashboardView, error)

QueryTaskDashboard returns the observer-backed aggregate task dashboard view.

func (*Observer) QueryTaskInbox

func (o *Observer) QueryTaskInbox(
	ctx context.Context,
	query TaskInboxQuery,
	actor taskpkg.ActorIdentity,
) (TaskInboxView, error)

QueryTaskInbox returns one bounded actor-scoped inbox page.

func (*Observer) QueryTaskMetrics

func (o *Observer) QueryTaskMetrics(ctx context.Context, query TaskMetricsQuery) (TaskMetrics, error)

QueryTaskMetrics returns task-domain counters and latency summaries derived from durable state and audit rows.

func (*Observer) QueryTaskSummary

func (o *Observer) QueryTaskSummary(ctx context.Context, query TaskSummaryQuery) (Summary, error)

QueryTaskSummary returns the current task summary buckets filtered by the supplied view.

func (*Observer) QueryTokenStats

func (o *Observer) QueryTokenStats(ctx context.Context, query store.TokenStatsQuery) ([]store.TokenStats, error)

QueryTokenStats returns aggregated per-session token usage rows.

func (*Observer) Reconcile

func (o *Observer) Reconcile(ctx context.Context) (store.ReconcileResult, error)

Reconcile scans the sessions directory and reconciles the global session index.

func (*Observer) RecordBridgeAuthFailure

func (o *Observer) RecordBridgeAuthFailure(bridgeInstanceID string)

RecordBridgeAuthFailure increments the per-instance auth failure counter.

func (*Observer) RecordBridgeRuntimeIssue

func (o *Observer) RecordBridgeRuntimeIssue(bridgeInstanceID string, status bridgepkg.BridgeStatus, message string)

RecordBridgeRuntimeIssue records a live runtime degradation/error signal for one instance without mutating the persisted bridge configuration.

func (*Observer) ShutdownRetention

func (o *Observer) ShutdownRetention(ctx context.Context) error

ShutdownRetention stops the owned retention sweep loop and waits for it to exit.

func (*Observer) StartRetention

func (o *Observer) StartRetention(ctx context.Context) error

StartRetention starts the owned retention sweep loop.

func (*Observer) SweepRetention

func (o *Observer) SweepRetention(ctx context.Context) (RetentionHealth, error)

SweepRetention runs one deterministic retention sweep using the observer clock.

func (*Observer) WriteHookRecord

func (o *Observer) WriteHookRecord(ctx context.Context, sessionID string, record hookspkg.HookRunRecord) (err error)

WriteHookRecord persists one hook execution record when the session database already exists.

type Option

type Option func(*Observer)

Option customizes Observer construction.

func WithAgentProbeSource

func WithAgentProbeSource(source AgentProbeTargetSource, timeout time.Duration) Option

WithAgentProbeSource injects the downstream ACP command source used by health.

func WithBridgeSource

func WithBridgeSource(source BridgeSource) Option

WithBridgeSource injects the daemon-owned bridge runtime seam used for bridge-specific health aggregation and query helpers.

func WithCostCatalog

func WithCostCatalog(catalog CostCatalog) Option

WithCostCatalog injects the merged model catalog used for silent-agent estimation.

func WithHomePaths

func WithHomePaths(homePaths compozyconfig.HomePaths) Option

WithHomePaths overrides the Compozy home layout used by observe/.

func WithHookCatalogSource

func WithHookCatalogSource(source HookCatalogSource) Option

WithHookCatalogSource injects the runtime hook catalog source used by hook introspection.

func WithHookStoreOpener

func WithHookStoreOpener(opener HookStoreOpener) Option

WithHookStoreOpener overrides the per-session hook run store opener, mainly for tests.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger injects the logger used for best-effort observer failures.

func WithMemoryEventSource

func WithMemoryEventSource(source MemoryEventSource) Option

WithMemoryEventSource injects the Memory v2 canonical event aggregation source.

func WithNow

func WithNow(now func() time.Time) Option

WithNow overrides the observer clock, mainly for tests.

func WithObservabilityConfig

func WithObservabilityConfig(cfg compozyconfig.ObservabilityConfig) Option

WithObservabilityConfig applies observability settings that affect observer-owned background work.

func WithPermissionModeResolver

func WithPermissionModeResolver(resolver PermissionModeResolver) Option

WithPermissionModeResolver injects custom permission resolution logic.

func WithProviderAuthModeResolver

func WithProviderAuthModeResolver(resolver ProviderAuthModeResolver) Option

WithProviderAuthModeResolver overrides provider auth resolution for session snapshots.

func WithRegistry

func WithRegistry(registry Registry) Option

WithRegistry injects the global registry implementation used by observe/.

func WithRetentionConfig

func WithRetentionConfig(cfg RetentionConfig) Option

WithRetentionConfig overrides retention behavior, mainly for tests.

func WithSessionSource

func WithSessionSource(source SessionSource) Option

WithSessionSource injects the active session source used for health metrics.

func WithStartTime

func WithStartTime(startedAt time.Time) Option

WithStartTime overrides the recorded daemon start time.

func WithTaskDashboardConfig

func WithTaskDashboardConfig(cfg TaskDashboardConfig) Option

WithTaskDashboardConfig overrides the dashboard thresholds and active-run list sizing used by the observer task dashboard view.

func WithTaskHealthConfig

func WithTaskHealthConfig(cfg TaskHealthConfig) Option

WithTaskHealthConfig overrides the task-run stuck thresholds used by the observer health view.

func WithVersionSource

func WithVersionSource(source VersionSource) Option

WithVersionSource overrides the build metadata source.

func WithWorkspaceResolver

func WithWorkspaceResolver(resolver workspacepkg.RuntimeResolver) Option

WithWorkspaceResolver injects workspace resolution for config lookups that need a filesystem root.

type OverviewAgentShare

type OverviewAgentShare struct {
	AgentName string
	Tokens    int64
	Fraction  float64
}

OverviewAgentShare is one agent's fraction of window token usage.

type OverviewAttention

type OverviewAttention struct {
	Total  int
	ByKind map[string]int
	Items  []OverviewAttentionItem
}

OverviewAttention lists everything currently waiting on the user.

type OverviewAttentionItem

type OverviewAttentionItem struct {
	Kind       string
	Title      string
	Detail     string
	TaskID     string
	RunID      string
	SessionID  string
	OccurredAt time.Time
	Actions    []string
}

OverviewAttentionItem is one actionable attention row.

type OverviewLongestSession

type OverviewLongestSession struct {
	SessionID       string
	AgentName       string
	DurationSeconds int64
	Date            string
}

OverviewLongestSession is the longest user session inside the pulse window.

type OverviewNetwork

type OverviewNetwork struct {
	MessagesToday int
}

OverviewNetwork carries today-windowed network counters.

type OverviewOutcomes

type OverviewOutcomes struct {
	WindowDays int
	Days       []store.TaskRunOutcomeDay
	Completed  int
	Failed     int
	Canceled   int
	SuccessPct float64
}

OverviewOutcomes summarizes terminal run outcomes across the fixed window.

type OverviewPulse

type OverviewPulse struct {
	WindowDays     int
	Buckets        []store.EventHourWeekdayBucket
	Busiest        *store.EventHourWeekdayBucket
	LongestSession *OverviewLongestSession
}

OverviewPulse summarizes hour-by-weekday activity plus derived insights.

type OverviewQuery

type OverviewQuery struct {
	WorkspaceID     string
	TaskScope       taskpkg.CatalogScope
	UsageWindowDays int
	Actor           taskpkg.ActorIdentity
}

OverviewQuery bounds one home overview read.

func (*OverviewQuery) Validate

func (q *OverviewQuery) Validate() error

Validate normalizes the usage window and rejects unsupported values.

type OverviewStore

type OverviewStore interface {
	UpsertTokenUsageDaily(ctx context.Context, update store.TokenUsageDailyUpdate) error
	ListTokenUsageByDay(ctx context.Context, query store.OverviewDayQuery) ([]store.TokenUsageDay, error)
	ListTokenUsageByAgent(ctx context.Context, query store.OverviewDayQuery) ([]store.TokenUsageAgentTotal, error)
	SumTokenUsageCost(ctx context.Context, query store.OverviewDayQuery) ([]store.TokenUsageCostGroup, error)
	CountTaskRunOutcomesByDay(ctx context.Context, query store.OverviewSinceQuery) ([]store.TaskRunOutcomeDay, error)
	CountTasksClosedByDay(ctx context.Context, query store.OverviewSinceQuery) ([]store.TaskClosedDay, error)
	CountEventsByHourWeekday(
		ctx context.Context,
		query store.OverviewSinceQuery,
	) ([]store.EventHourWeekdayBucket, error)
	LatestEventSummaryAt(ctx context.Context, workspaceID string) (time.Time, error)
	CountNetworkMessagesSince(ctx context.Context, query store.OverviewSinceQuery) (int, error)
	CountHookDispatchesSince(ctx context.Context, query store.OverviewSinceQuery) (store.HookDispatchCounts, error)
	LongestUserSessionSince(ctx context.Context, query store.OverviewSinceQuery) (*store.LongestSessionSample, error)
}

OverviewStore is the aggregate persistence capability behind the home overview.

type OverviewSystem

type OverviewSystem struct {
	HookRunsToday     int
	HookFailuresToday int
	RetentionDays     int
}

OverviewSystem carries today-windowed system counters plus retention truth.

type OverviewToday

type OverviewToday struct {
	RunsCompleted int
	RunsFailed    int
	TasksClosed   int
}

OverviewToday summarizes today's terminal work.

type OverviewUsage

type OverviewUsage struct {
	WindowDays    int
	RetentionDays int
	Truncated     bool
	TotalTokens   int64
	EstimatedCost *float64
	CostCurrency  string
	CostStatus    string
	Days          []store.TokenUsageDay
	AgentShare    []OverviewAgentShare
}

OverviewUsage summarizes token usage and estimated cost for the selected window.

type OverviewView

type OverviewView struct {
	GeneratedAt time.Time
	Attention   OverviewAttention
	Today       OverviewToday
	Outcomes    OverviewOutcomes
	Usage       OverviewUsage
	Pulse       OverviewPulse
	Network     OverviewNetwork
	System      OverviewSystem
	Freshness   TaskDashboardFreshness
}

OverviewView is the composed home overview read model.

type PermissionModeResolver

type PermissionModeResolver func(ctx context.Context, agentName, workspaceID string) (string, error)

PermissionModeResolver resolves the effective permission mode for a live session using its durable workspace reference.

type PersistenceHealth

type PersistenceHealth struct {
	Status             string `json:"status"`
	GlobalDBSizeBytes  int64  `json:"global_db_size_bytes"`
	SessionDBSizeBytes int64  `json:"session_db_size_bytes"`
}

PersistenceHealth captures store health that later hardening tracks can extend without overloading unrelated API payloads.

type ProviderAuthModeResolver

type ProviderAuthModeResolver func(
	ctx context.Context,
	agentName string,
	provider string,
	model string,
	workspaceID string,
) (compozyconfig.ProviderAuthMode, error)

ProviderAuthModeResolver resolves the effective auth owner for one session runtime.

type Registry

type Registry interface {
	RegisterSession(ctx context.Context, session store.SessionInfo) error
	ListSessions(ctx context.Context, query store.SessionListQuery) ([]store.SessionInfo, error)
	ReconcileSessions(ctx context.Context, sessions []store.SessionInfo) (store.ReconcileResult, error)
	WriteEventSummary(ctx context.Context, summary store.EventSummary) error
	ListEventSummaries(ctx context.Context, query store.EventSummaryQuery) ([]store.EventSummary, error)
	RecordTokenUsage(ctx context.Context, stats store.TokenStatsUpdate, daily store.TokenUsageDailyUpdate) error
	ListTokenStats(ctx context.Context, query store.TokenStatsQuery) ([]store.TokenStats, error)
	WritePermissionLog(ctx context.Context, entry store.PermissionLogEntry) error
	ListPermissionLog(ctx context.Context, query store.PermissionLogQuery) ([]store.PermissionLogEntry, error)
	ListNetworkAudit(ctx context.Context, query store.NetworkAuditQuery) ([]store.NetworkAuditEntry, error)
	ListTasks(ctx context.Context, query taskpkg.Query) ([]taskpkg.Summary, error)
	CountDependencies(ctx context.Context, taskID string) (int, error)
	ListTaskRuns(ctx context.Context, query taskpkg.RunQuery) ([]taskpkg.Run, error)
	ListTaskEvents(ctx context.Context, query taskpkg.EventQuery) ([]taskpkg.Event, error)
	ListTaskTriageStates(ctx context.Context, actor taskpkg.ActorIdentity) ([]taskpkg.TriageState, error)
	Path() string
	Close(ctx context.Context) error
}

Registry is the narrowed global persistence surface consumed by observe/.

type RetentionConfig

type RetentionConfig struct {
	Enabled       bool
	RetentionDays int
	SweepInterval time.Duration
}

RetentionConfig controls observer retention sweeps.

func RetentionConfigFromObservability

func RetentionConfigFromObservability(cfg compozyconfig.ObservabilityConfig) RetentionConfig

RetentionConfigFromObservability maps daemon configuration into observer retention settings.

type RetentionHealth

type RetentionHealth struct {
	Enabled                  bool       `json:"enabled"`
	RetentionDays            int        `json:"retention_days"`
	SweepIntervalSeconds     int64      `json:"sweep_interval_seconds"`
	LastSweepStatus          string     `json:"last_sweep_status"`
	LastSweepAt              *time.Time `json:"last_sweep_at,omitempty"`
	LastCutoffAt             *time.Time `json:"last_cutoff_at,omitempty"`
	LastSweepError           string     `json:"last_sweep_error,omitempty"`
	DeletedEventSummaries    int64      `json:"deleted_event_summaries"`
	DeletedTokenStats        int64      `json:"deleted_token_stats"`
	DeletedTokenUsageDaily   int64      `json:"deleted_token_usage_daily"`
	DeletedPermissionLogRows int64      `json:"deleted_permission_log_rows"`
}

RetentionHealth captures the operator-visible state of observability retention.

type SessionActivityHealth

type SessionActivityHealth struct {
	SessionID          string     `json:"session_id"`
	TurnID             string     `json:"turn_id,omitempty"`
	TurnSource         string     `json:"turn_source,omitempty"`
	TurnStartedAt      *time.Time `json:"turn_started_at,omitempty"`
	LastActivityAt     *time.Time `json:"last_activity_at,omitempty"`
	LastActivityKind   string     `json:"last_activity_kind,omitempty"`
	LastActivityDetail string     `json:"last_activity_detail,omitempty"`
	CurrentTool        string     `json:"current_tool,omitempty"`
	ToolCallID         string     `json:"tool_call_id,omitempty"`
	LastProgressAt     *time.Time `json:"last_progress_at,omitempty"`
	IterationCurrent   int        `json:"iteration_current,omitempty"`
	IterationMax       int        `json:"iteration_max,omitempty"`
	IdleSeconds        int64      `json:"idle_seconds,omitempty"`
	ElapsedSeconds     int64      `json:"elapsed_seconds,omitempty"`
	Status             string     `json:"status"`
	StallState         string     `json:"stall_state,omitempty"`
	StallReason        string     `json:"stall_reason,omitempty"`
}

SessionActivityHealth captures the active runtime supervision state exposed through the daemon health view.

type SessionFailureHealth

type SessionFailureHealth struct {
	SessionID       string            `json:"session_id"`
	AgentName       string            `json:"agent_name,omitempty"`
	Provider        string            `json:"provider,omitempty"`
	WorkspaceID     string            `json:"workspace_id,omitempty"`
	State           string            `json:"state,omitempty"`
	FailureKind     store.FailureKind `json:"failure_kind"`
	Summary         string            `json:"summary,omitempty"`
	CrashBundlePath string            `json:"crash_bundle_path,omitempty"`
	UpdatedAt       time.Time         `json:"updated_at"`
}

SessionFailureHealth is a compact, redacted lifecycle failure row.

type SessionSource

type SessionSource interface {
	List() []*session.Info
}

SessionSource reports the currently active in-memory sessions.

type StuckTaskRun

type StuckTaskRun struct {
	TaskID     string             `json:"task_id"`
	RunID      string             `json:"run_id"`
	Status     taskpkg.RunStatus  `json:"status"`
	OriginKind taskpkg.OriginKind `json:"origin_kind"`
	ChannelID  string             `json:"channel_id,omitempty"`
	SessionID  string             `json:"session_id,omitempty"`
	AgeMillis  int64              `json:"age_ms"`
}

StuckTaskRun reports one run that exceeded the configured claimed/starting/running threshold.

type Summary

type Summary struct {
	TotalTasks  int               `json:"total_tasks"`
	TotalRuns   int               `json:"total_runs"`
	TaskTotals  []TaskStatusTotal `json:"task_totals,omitempty"`
	TaskOrigins []TaskOriginTotal `json:"task_origins,omitempty"`
	RunTotals   []TaskRunTotal    `json:"run_totals,omitempty"`
	OwnerTotals []TaskOwnerTotal  `json:"owner_totals,omitempty"`
	QueueDepth  []TaskQueueDepth  `json:"queue_depth,omitempty"`
}

Summary exposes the current read-side task summary buckets.

type TaskCancelRequestTotal

type TaskCancelRequestTotal struct {
	OriginKind taskpkg.OriginKind `json:"origin_kind"`
	Count      int                `json:"count"`
}

TaskCancelRequestTotal reports cancellation requests grouped by origin.

type TaskDashboardActiveRun

type TaskDashboardActiveRun struct {
	TaskID                       string              `json:"task_id"`
	TaskIdentifier               string              `json:"task_identifier,omitempty"`
	TaskTitle                    string              `json:"task_title"`
	TaskStatus                   taskpkg.Status      `json:"task_status"`
	TaskPriority                 taskpkg.Priority    `json:"task_priority,omitempty"`
	TaskOwner                    *taskpkg.Ownership  `json:"task_owner,omitempty"`
	Scope                        taskpkg.Scope       `json:"scope"`
	WorkspaceID                  string              `json:"workspace_id,omitempty"`
	LatestEventSeq               int64               `json:"latest_event_seq"`
	RunID                        string              `json:"run_id"`
	RunStatus                    taskpkg.RunStatus   `json:"run_status"`
	Attempt                      int                 `json:"attempt"`
	MaxAttempts                  int                 `json:"max_attempts"`
	SessionID                    string              `json:"session_id,omitempty"`
	ResolvedNetworkParticipation *participation.Spec `json:"resolved_network_participation,omitempty"`
	LastActivityAt               time.Time           `json:"last_activity_at"`
	AgeMilli                     int64               `json:"age_ms"`
	HealthStatus                 string              `json:"health_status"`
	Stuck                        bool                `json:"stuck"`
	Error                        string              `json:"error,omitempty"`
}

TaskDashboardActiveRun exposes one recent active-run card payload.

type TaskDashboardActiveRuns

type TaskDashboardActiveRuns struct {
	Total    int                      `json:"total"`
	Running  int                      `json:"running"`
	Starting int                      `json:"starting"`
	Claimed  int                      `json:"claimed"`
	Queued   int                      `json:"queued"`
	Items    []TaskDashboardActiveRun `json:"items,omitempty"`
}

TaskDashboardActiveRuns summarizes the currently active run set and exposes recent cards.

type TaskDashboardBlockedCard

type TaskDashboardBlockedCard struct {
	Tasks                int    `json:"tasks"`
	AwaitingApproval     int    `json:"awaiting_approval"`
	AwaitingDependencies int    `json:"awaiting_dependencies"`
	HealthStatus         string `json:"health_status"`
}

TaskDashboardBlockedCard summarizes blocked work and approval/dependency pressure.

type TaskDashboardCards

type TaskDashboardCards struct {
	InProgress TaskDashboardInProgressCard `json:"in_progress"`
	Blocked    TaskDashboardBlockedCard    `json:"blocked"`
	Failed     TaskDashboardFailedCard     `json:"failed"`
	Latency    TaskDashboardLatencyCard    `json:"latency"`
}

TaskDashboardCards exposes dashboard-ready card values without leaking raw summary buckets.

type TaskDashboardConfig

type TaskDashboardConfig struct {
	ActiveRunLimit   int
	BacklogWarnAfter time.Duration
	StaleAfter       time.Duration
}

TaskDashboardConfig controls task dashboard freshness/backlog thresholds and active-run list size.

type TaskDashboardFailedCard

type TaskDashboardFailedCard struct {
	Tasks        int    `json:"tasks"`
	FailedRuns   int    `json:"failed_runs"`
	ForcedStops  int    `json:"forced_stops"`
	HealthStatus string `json:"health_status"`
}

TaskDashboardFailedCard summarizes failed work and disruptive run outcomes.

type TaskDashboardFreshness

type TaskDashboardFreshness struct {
	ObservedAt       time.Time `json:"observed_at"`
	LatestActivityAt time.Time `json:"latest_activity_at"`
	AgeMilli         int64     `json:"age_ms"`
	StaleAfterMilli  int64     `json:"stale_after_ms"`
	HasLiveWork      bool      `json:"has_live_work"`
	Status           string    `json:"status"`
	Stale            bool      `json:"stale"`
}

TaskDashboardFreshness exposes the recency and stale-warning state of the dashboard snapshot.

type TaskDashboardHealth

type TaskDashboardHealth struct {
	Status           string `json:"status"`
	StuckRuns        int    `json:"stuck_runs"`
	ActiveOrphanRuns int    `json:"active_orphan_runs"`
	QueueBacklog     bool   `json:"queue_backlog"`
}

TaskDashboardHealth reports warning-oriented dashboard health indicators.

type TaskDashboardInProgressCard

type TaskDashboardInProgressCard struct {
	Tasks        int    `json:"tasks"`
	ActiveRuns   int    `json:"active_runs"`
	RunningRuns  int    `json:"running_runs"`
	StartingRuns int    `json:"starting_runs"`
	ClaimedRuns  int    `json:"claimed_runs"`
	QueuedRuns   int    `json:"queued_runs"`
	HealthStatus string `json:"health_status"`
}

TaskDashboardInProgressCard summarizes active work and live run pressure.

type TaskDashboardLatencyCard

type TaskDashboardLatencyCard struct {
	ClaimLatencyMillis LatencyMetric `json:"claim_latency_ms"`
	StartLatencyMillis LatencyMetric `json:"start_latency_ms"`
}

TaskDashboardLatencyCard exposes current run-queue latency summaries for operator cards.

type TaskDashboardQuery

type TaskDashboardQuery struct {
	Scope                taskpkg.Scope      `json:"scope,omitempty"`
	WorkspaceID          string             `json:"workspace_id,omitempty"`
	OwnerKind            taskpkg.OwnerKind  `json:"owner_kind,omitempty"`
	OwnerRef             string             `json:"owner_ref,omitempty"`
	ParticipationChannel string             `json:"participation_channel,omitempty"`
	OriginKind           taskpkg.OriginKind `json:"origin_kind,omitempty"`
}

TaskDashboardQuery filters the observer-backed task dashboard read model.

func (TaskDashboardQuery) Validate

func (q TaskDashboardQuery) Validate() error

Validate ensures the dashboard query uses supported filters.

type TaskDashboardQueue

type TaskDashboardQueue struct {
	Total                 int              `json:"total"`
	Depth                 []TaskQueueDepth `json:"depth,omitempty"`
	OldestQueuedAt        time.Time        `json:"oldest_queued_at"`
	OldestQueueAgeMilli   int64            `json:"oldest_queue_age_ms"`
	BacklogWarning        bool             `json:"backlog_warning"`
	BacklogStatus         string           `json:"backlog_status"`
	BacklogThresholdMilli int64            `json:"backlog_threshold_ms"`
}

TaskDashboardQueue reports backlog state for queued task work.

type TaskDashboardStatusBreakdown

type TaskDashboardStatusBreakdown struct {
	Status       taskpkg.Status `json:"status"`
	Count        int            `json:"count"`
	SharePercent int            `json:"share_percent"`
}

TaskDashboardStatusBreakdown reports one aggregated task status bucket for chart rendering.

type TaskDashboardTotals

type TaskDashboardTotals struct {
	TasksTotal             int `json:"tasks_total"`
	RunsTotal              int `json:"runs_total"`
	DraftTasks             int `json:"draft_tasks"`
	PendingTasks           int `json:"pending_tasks"`
	ReadyTasks             int `json:"ready_tasks"`
	InProgressTasks        int `json:"in_progress_tasks"`
	BlockedTasks           int `json:"blocked_tasks"`
	CompletedTasks         int `json:"completed_tasks"`
	FailedTasks            int `json:"failed_tasks"`
	CanceledTasks          int `json:"canceled_tasks"`
	AwaitingApprovalTasks  int `json:"awaiting_approval_tasks"`
	DependencyBlockedTasks int `json:"dependency_blocked_tasks"`
	QueuedRuns             int `json:"queued_runs"`
	ClaimedRuns            int `json:"claimed_runs"`
	StartingRuns           int `json:"starting_runs"`
	RunningRuns            int `json:"running_runs"`
	CompletedRuns          int `json:"completed_runs"`
	FailedRuns             int `json:"failed_runs"`
	CanceledRuns           int `json:"canceled_runs"`
	ActiveRuns             int `json:"active_runs"`
}

TaskDashboardTotals collapses the current task and run totals into chart-friendly counters.

type TaskDashboardView

type TaskDashboardView struct {
	Totals          TaskDashboardTotals            `json:"totals"`
	Cards           TaskDashboardCards             `json:"cards"`
	StatusBreakdown []TaskDashboardStatusBreakdown `json:"status_breakdown,omitempty"`
	Queue           TaskDashboardQueue             `json:"queue"`
	Health          TaskDashboardHealth            `json:"health"`
	ActiveRuns      TaskDashboardActiveRuns        `json:"active_runs"`
	Freshness       TaskDashboardFreshness         `json:"freshness"`
}

TaskDashboardView exposes the observer-owned aggregate payload for the Paper task dashboard.

type TaskHealth

type TaskHealth struct {
	Status                     string             `json:"status"`
	QueueDepthTotal            int                `json:"queue_depth_total"`
	OldestQueuedAt             time.Time          `json:"oldest_queued_at"`
	OldestQueueAgeMilli        int64              `json:"oldest_queue_age_ms"`
	QueueDepth                 []TaskQueueDepth   `json:"queue_depth,omitempty"`
	StuckRuns                  []StuckTaskRun     `json:"stuck_runs,omitempty"`
	ActiveOrphanRuns           int                `json:"active_orphan_runs"`
	TaskTotals                 []TaskStatusTotal  `json:"task_totals,omitempty"`
	RunTotals                  []TaskRunTotal     `json:"run_totals,omitempty"`
	OwnerTotals                []TaskOwnerTotal   `json:"owner_totals,omitempty"`
	ForcedStopsSinceStart      int                `json:"forced_stops_since_start"`
	DuplicateIngressSinceStart int                `json:"duplicate_ingress_since_start"`
	ChannelMismatchSinceStart  int                `json:"channel_mismatch_since_start"`
	RecoverySinceStart         TaskRecoveryTotals `json:"recovery_since_start"`
}

TaskHealth exposes the current operational task-health view.

type TaskHealthConfig

type TaskHealthConfig struct {
	ClaimedStuckAfter  time.Duration
	StartingStuckAfter time.Duration
	RunningStuckAfter  time.Duration
}

TaskHealthConfig controls task-run stuck detection in the read-side health view.

type TaskInboxItem

type TaskInboxItem = taskpkg.InboxItem

type TaskInboxLane

type TaskInboxLane = taskpkg.InboxLane

type TaskInboxLaneGroup

type TaskInboxLaneGroup = taskpkg.InboxLaneGroup

type TaskInboxQuery

type TaskInboxQuery = taskpkg.InboxQuery

type TaskInboxView

type TaskInboxView = taskpkg.InboxPage

type TaskMetrics

type TaskMetrics struct {
	TasksTotal              []TaskStatusTotal        `json:"tasks_total,omitempty"`
	TaskRunsTotal           []TaskRunTotal           `json:"task_runs_total,omitempty"`
	TaskQueueDepth          []TaskQueueDepth         `json:"task_queue_depth,omitempty"`
	TaskCancelRequestsTotal []TaskCancelRequestTotal `json:"task_cancel_requests_total,omitempty"`
	TaskForcedStopsTotal    int                      `json:"task_forced_stops_total"`
	TaskClaimLatencyMillis  LatencyMetric            `json:"task_claim_latency_ms"`
	TaskStartLatencyMillis  LatencyMetric            `json:"task_start_latency_ms"`
	DuplicateIngressTotal   int                      `json:"duplicate_ingress_total"`
	ChannelMismatchTotal    int                      `json:"channel_mismatch_total"`
	RecoveryTotals          TaskRecoveryTotals       `json:"recovery_totals"`
}

TaskMetrics exposes current counters and latency summaries for the task domain.

type TaskMetricsQuery

type TaskMetricsQuery struct {
	Since                time.Time          `json:"since"`
	ParticipationChannel string             `json:"participation_channel,omitempty"`
	OriginKind           taskpkg.OriginKind `json:"origin_kind,omitempty"`
}

TaskMetricsQuery filters audit-derived metrics and current queue metrics.

func (TaskMetricsQuery) Validate

func (q TaskMetricsQuery) Validate() error

Validate ensures the metrics query uses supported filters.

type TaskOriginTotal

type TaskOriginTotal struct {
	OriginKind taskpkg.OriginKind `json:"origin_kind"`
	ChannelID  string             `json:"channel_id,omitempty"`
	Count      int                `json:"count"`
}

TaskOriginTotal reports one current task-origin bucket.

type TaskOwnerTotal

type TaskOwnerTotal struct {
	OwnerKind taskpkg.OwnerKind `json:"owner_kind"`
	OwnerRef  string            `json:"owner_ref"`
	Count     int               `json:"count"`
}

TaskOwnerTotal reports one current ownership bucket.

type TaskQueueDepth

type TaskQueueDepth struct {
	ChannelID           string    `json:"channel_id,omitempty"`
	Count               int       `json:"count"`
	OldestQueuedAt      time.Time `json:"oldest_queued_at"`
	OldestQueueAgeMilli int64     `json:"oldest_queue_age_ms"`
}

TaskQueueDepth reports queued work by channel.

type TaskRecoveryTotals

type TaskRecoveryTotals struct {
	Requeued      int `json:"requeued"`
	MarkedRunning int `json:"marked_running"`
	Failed        int `json:"failed"`
}

TaskRecoveryTotals reports boot-recovery outcomes grouped by manager action.

type TaskRunTotal

type TaskRunTotal struct {
	Status     taskpkg.RunStatus  `json:"status"`
	OriginKind taskpkg.OriginKind `json:"origin_kind"`
	ChannelID  string             `json:"channel_id,omitempty"`
	Count      int                `json:"count"`
}

TaskRunTotal reports one current task-run bucket.

type TaskStatusTotal

type TaskStatusTotal struct {
	Scope     taskpkg.Scope  `json:"scope"`
	Status    taskpkg.Status `json:"status"`
	ChannelID string         `json:"channel_id,omitempty"`
	Count     int            `json:"count"`
}

TaskStatusTotal reports one current task-count bucket.

type TaskSummaryQuery

type TaskSummaryQuery struct {
	Scope                taskpkg.Scope      `json:"scope,omitempty"`
	WorkspaceID          string             `json:"workspace_id,omitempty"`
	OwnerKind            taskpkg.OwnerKind  `json:"owner_kind,omitempty"`
	OwnerRef             string             `json:"owner_ref,omitempty"`
	ParticipationChannel string             `json:"participation_channel,omitempty"`
	OriginKind           taskpkg.OriginKind `json:"origin_kind,omitempty"`
	Search               string             `json:"search,omitempty"`
}

TaskSummaryQuery filters the current task summary view.

func (TaskSummaryQuery) Validate

func (q TaskSummaryQuery) Validate() error

Validate ensures the summary query uses supported filters.

type VersionSource

type VersionSource func() version.Info

VersionSource returns the current daemon build metadata.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL