telemetry

type ActivationState struct {
	FirstConnectedServerEver      bool     `json:"first_connected_server_ever"`
	FirstMCPClientEver            bool     `json:"first_mcp_client_ever"`
	FirstRetrieveToolsCallEver    bool     `json:"first_retrieve_tools_call_ever"`
	MCPClientsSeenEver            []string `json:"mcp_clients_seen_ever"`
	RetrieveToolsCalls24h         int      `json:"retrieve_tools_calls_24h"`
	EstimatedTokensSaved24hBucket string   `json:"estimated_tokens_saved_24h_bucket"`
	ConfiguredIDECount            int      `json:"configured_ide_count"`
}

type ActivationStore interface {
	// Load reads the full activation state. Missing bucket or keys yield
	// zero values.
	Load(db *bbolt.DB) (ActivationState, error)

	// Save writes the full activation state, enforcing monotonic flags
	// (true cannot revert to false).
	Save(db *bbolt.DB, st ActivationState) error

	// MarkFirstConnectedServer sets first_connected_server_ever=true if not
	// already set. No-op if already true.
	MarkFirstConnectedServer(db *bbolt.DB) error

	// MarkFirstMCPClient sets first_mcp_client_ever=true if not already set.
	MarkFirstMCPClient(db *bbolt.DB) error

	// MarkFirstRetrieveToolsCall sets first_retrieve_tools_call_ever=true
	// if not already set.
	MarkFirstRetrieveToolsCall(db *bbolt.DB) error

	// RecordMCPClient adds sanitized client name to the seen list. Dedups
	// on insert; drops when cap (16) is reached.
	RecordMCPClient(db *bbolt.DB, name string) error

	// IncrementRetrieveToolsCall bumps the 24h window counter by 1,
	// rolling the window if it has expired.
	IncrementRetrieveToolsCall(db *bbolt.DB) error

	// AddTokensSaved adds n to the 24h token-savings estimator counter.
	AddTokensSaved(db *bbolt.DB, n int) error

	// SetInstallerPending writes the installer_heartbeat_pending flag.
	SetInstallerPending(db *bbolt.DB, v bool) error

	// IsInstallerPending reports whether installer_heartbeat_pending is
	// currently set.
	IsInstallerPending(db *bbolt.DB) (bool, error)
}

type AnonymityViolation struct {
	// Rule is a short stable identifier ("blocked_prefix", "blocked_value",
	// "env_markers_non_bool") suitable for metrics labels.
	Rule string
	// Pattern is the literal substring or env-var name that matched.
	Pattern string
	// Reason is a human-readable summary (no payload contents).
	Reason string
}

type AutostartReader struct {
	// Path is the filesystem location of the tray-written sidecar. Tests
	// override this; production uses DefaultAutostartReader.
	Path string
	// contains filtered or unexported fields
}

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

type DiagnosticsCounterStore interface {
	// RecordErrorCode increments the 24h sliding counter for the given MCPX_
	// code and adds it to the unique_codes_ever set (idempotent on second add).
	// Only values that match the MCPX_ prefix are accepted; others are silently
	// dropped to prevent free-text from leaking into telemetry.
	RecordErrorCode(db *bbolt.DB, code string) error

	// RecordFixAttempt increments fix_attempted_24h. If outcome == "success",
	// also increments fix_succeeded_24h. Unknown outcomes are counted as
	// attempted-only (graceful: new outcome strings from future code won't panic).
	RecordFixAttempt(db *bbolt.DB, outcome string) error

	// Snapshot loads the current counter state, applying 24h decay at now.
	Snapshot(db *bbolt.DB) (DiagnosticsCounters, error)
}

type DiagnosticsCounters struct {
	// ErrorCodeCounts24h maps stable MCPX_ code strings to 24h occurrence counts.
	// Safe: only MCPX_* enum constants are stored here, never free text, paths,
	// server names, or user-entered values.
	ErrorCodeCounts24h map[string]int `json:"error_code_counts_24h,omitempty"`
	// FixAttempted24h counts POST /api/v1/diagnostics/fix calls in the last 24h.
	FixAttempted24h int `json:"fix_attempted_24h"`
	// FixSucceeded24h counts fix invocations with outcome="success" in the last 24h.
	FixSucceeded24h int `json:"fix_succeeded_24h"`
	// UniqueCodesEver is the cardinality of the all-time error code set.
	// Bounded by the MCPX_ catalog size (~30 codes), never approaches PII risk.
	UniqueCodesEver int `json:"unique_codes_ever"`
}

type DoctorCheckResult interface {
	GetName() string
	IsPass() bool
}

type DoctorCounts struct {
	Pass int64 `json:"pass"`
	Fail int64 `json:"fail"`
}

type EnvDisabledReason string

type EnvKind string

type EnvMarkers struct {
	// HasCIEnv is true when any known CI env var is set (e.g., CI=true,
	// GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL, CIRCLECI).
	HasCIEnv bool `json:"has_ci_env"`

	// HasCloudIDEEnv is true when a cloud-IDE env var is set (e.g.,
	// CODESPACES, GITPOD_WORKSPACE_ID, REPL_ID, STACKBLITZ_WORKER,
	// DAYTONA_WORKSPACE_ID, CODER_AGENT_TOKEN).
	HasCloudIDEEnv bool `json:"has_cloud_ide_env"`

	// IsContainer is true when /.dockerenv or /run/.containerenv exists, or
	// the $container env var is set.
	IsContainer bool `json:"is_container"`

	// HasTTY is true when stdin is attached to a terminal.
	HasTTY bool `json:"has_tty"`

	// HasDisplay is true when DISPLAY or WAYLAND_DISPLAY env var is set
	// (Linux desktop session indicator).
	HasDisplay bool `json:"has_display"`
}

type ErrorCategory string

type FeatureFlagSnapshot struct {
	EnableSocket                  bool     `json:"enable_socket"`
	EnableWebUI                   bool     `json:"enable_web_ui"`
	EnablePrompts                 bool     `json:"enable_prompts"`
	RequireMCPAuth                bool     `json:"require_mcp_auth"`
	EnableCodeExecution           bool     `json:"enable_code_execution"`
	QuarantineEnabled             bool     `json:"quarantine_enabled"`
	SensitiveDataDetectionEnabled bool     `json:"sensitive_data_detection_enabled"`
	OAuthProviderTypes            []string `json:"oauth_provider_types"`

	// Schema v3: DockerAvailable reports whether the host has a reachable
	// Docker daemon, as observed by the runtime's checkDockerDaemon probe.
	// Populated by the telemetry service at heartbeat time (not by
	// BuildFeatureFlagSnapshot) so the snapshot helper stays side-effect-free
	// and doesn't shell out to `docker info`.
	DockerAvailable bool `json:"docker_available"`

	// Schema v5 (MCP-2745): DockerIsolationEnabled is the global
	// docker_isolation.enabled flag. Set by BuildFeatureFlagSnapshot (pure,
	// config-only). Together with DockerCLISource it lets the dashboard tell
	// "isolation on, 0 matching servers" apart from "isolation off".
	DockerIsolationEnabled bool `json:"docker_isolation_enabled"`

	// Schema v5 (MCP-2745): DockerCLISource is the coarse, fixed-enum branch
	// that resolved the `docker` CLI — one of "path" | "bundled" |
	// "login_shell" | "absent". This is the direct #696 fleet signal (docker
	// installed but not on the spawn PATH). NEVER the path string itself.
	// Populated by the telemetry service at heartbeat time (the resolution is a
	// runtime concern) — mirrors DockerAvailable.
	DockerCLISource string `json:"docker_cli_source,omitempty"`
}

type FeedbackContext struct {
	Version              string `json:"version"`
	Edition              string `json:"edition"`
	OS                   string `json:"os"`
	Arch                 string `json:"arch"`
	ServerCount          int    `json:"server_count"`
	ConnectedServerCount int    `json:"connected_server_count"`
	RoutingMode          string `json:"routing_mode"`
}

type FeedbackRequest struct {
	Category string          `json:"category"` // bug, feature, other
	Message  string          `json:"message"`
	Email    string          `json:"email,omitempty"`
	Context  FeedbackContext `json:"context"`
}

type FeedbackResponse struct {
	Success  bool   `json:"success"`
	IssueURL string `json:"issue_url,omitempty"`
	Error    string `json:"error,omitempty"`
}

type FileProber interface {
	// Exists returns true if the file at path exists (any type: file, dir,
	// symlink). Errors other than "not exists" are treated as "exists" to
	// avoid mis-classifying a container due to permission issues.
	Exists(path string) bool
}

type FunnelState struct {
	// WebUIOpened is the lifetime count of embedded Web UI index serves.
	WebUIOpened int64
	// DaysSinceInstall is the non-negative whole-day age of the install,
	// clamped at 0 on clock skew. Only meaningful when HasInstallDay is true.
	DaysSinceInstall int
	// HasInstallDay reports whether a first-install stamp exists yet.
	HasInstallDay bool
	// ActiveDays30d is the number of distinct active UTC days in the
	// trailing 30-day window (0..30; 0 only before any activity is recorded).
	ActiveDays30d int
}

type FunnelStore interface {
	// IncrementWebUIOpened bumps the lifetime index-serve counter by 1.
	IncrementWebUIOpened(db *bbolt.DB) error

	// RecordActivity stamps the first-install day if absent and adds now's
	// UTC day to the active-day set, pruning members that have aged out of
	// the trailing window. Out-of-order days are tolerated: a day is a set
	// member, not a delta.
	RecordActivity(db *bbolt.DB, now time.Time) error

	// Snapshot reads the payload-safe reduction of the bucket at `now`.
	// Aging is applied at read time as well, so a stale on-disk set never
	// inflates the surfaced count. A missing bucket yields a zero state.
	Snapshot(db *bbolt.DB, now time.Time) (FunnelState, error)
}

type HandshakeChecker interface {
	LaunchedViaTray() bool
}

type HeartbeatPayload struct {
	// v1 fields (preserved unchanged)
	AnonymousID string `json:"anonymous_id"`
	// MachineID (schema v6) is a stable, non-reversible hash of the OS machine
	// id — HMAC-SHA256 keyed by the OS machine id, scoped by an app-specific key
	// (see machine_id.go). Unlike anonymous_id (a UUID persisted in the config
	// file, which is regenerated on every run in ephemeral environments —
	// throwaway HOMEs, Docker layers, CI), this value is stable per physical
	// machine, letting the dashboard dedup ephemeral installs. Empty/omitted
	// when the OS machine id cannot be read (containers without /etc/machine-id,
	// permission errors, exotic platforms); the backend treats empty as
	// "unknown". The raw machine id is NEVER transmitted — only the salted hash.
	// It rides the same opt-out gate as every other field (the whole heartbeat
	// is suppressed when telemetry is disabled).
	MachineID            string `json:"machine_id,omitempty"`
	Version              string `json:"version"`
	Edition              string `json:"edition"`
	OS                   string `json:"os"`
	Arch                 string `json:"arch"`
	GoVersion            string `json:"go_version"`
	ServerCount          int    `json:"server_count"`
	ConnectedServerCount int    `json:"connected_server_count"`
	ToolCount            int    `json:"tool_count"`
	UptimeHours          int    `json:"uptime_hours"`
	RoutingMode          string `json:"routing_mode"`
	QuarantineEnabled    bool   `json:"quarantine_enabled"`
	Timestamp            string `json:"timestamp"`

	// Spec 042 (Tier 2) additions
	SchemaVersion               int                         `json:"schema_version,omitempty"`
	AnonymousIDCreatedAt        string                      `json:"anonymous_id_created_at,omitempty"`
	CurrentVersion              string                      `json:"current_version,omitempty"`
	PreviousVersion             string                      `json:"previous_version"`
	LastStartupOutcome          string                      `json:"last_startup_outcome,omitempty"`
	SurfaceRequests             map[string]int64            `json:"surface_requests,omitempty"`
	BuiltinToolCalls            map[string]int64            `json:"builtin_tool_calls,omitempty"`
	UpstreamToolCallCountBucket string                      `json:"upstream_tool_call_count_bucket,omitempty"`
	RESTEndpointCalls           map[string]map[string]int64 `json:"rest_endpoint_calls,omitempty"`
	FeatureFlags                *FeatureFlagSnapshot        `json:"feature_flags,omitempty"`
	ErrorCategoryCounts         map[string]int64            `json:"error_category_counts,omitempty"`
	DoctorChecks                map[string]DoctorCounts     `json:"doctor_checks,omitempty"`

	// Schema v3 additions.
	// ServerProtocolCounts is a fixed-enum histogram over cfg.Servers by
	// Protocol. Keys are exactly: stdio, http, sse, streamable_http, auto.
	// Never contains server names, URLs, or unknown values (unknown/empty
	// protocols bucket into "auto").
	ServerProtocolCounts map[string]int `json:"server_protocol_counts,omitempty"`
	// ServerDockerIsolatedCount is the number of configured servers the
	// runtime actually wraps in Docker isolation. Distinct from "has Docker
	// available" — an install can have Docker but never use it for isolation.
	ServerDockerIsolatedCount int `json:"server_docker_isolated_count,omitempty"`

	// Spec 044 additions. schema_version stays at 3 (set by spec 042); these
	// fields are additive and forward-compatible.
	//
	// EnvKind: ground-truth classification of the process environment, computed
	// once at startup by DetectEnvKindOnce. One of the EnvKind* constants.
	EnvKind string `json:"env_kind,omitempty"`
	// EnvMarkers: raw boolean observations feeding EnvKind. Fields are ALL
	// booleans — the anonymity scanner re-asserts this on the serialized form.
	EnvMarkers *EnvMarkers `json:"env_markers,omitempty"`

	// Activation is the retention funnel snapshot: monotonic first-ever flags,
	// 24h sliding counters, and bucketed token-savings estimate. Loaded from
	// the BBolt activation bucket at heartbeat build time. nil when the store
	// is not wired (e.g. in short-lived CLI commands).
	Activation *ActivationState `json:"activation,omitempty"`

	// LaunchSource: how the process was launched. One of "installer", "tray",
	// "login_item", "cli", "unknown". Detected once at startup via
	// DetectLaunchSourceOnce, with a one-shot "installer" override driven by
	// the installer_heartbeat_pending BBolt flag (cleared after first heartbeat).
	LaunchSource string `json:"launch_source,omitempty"`

	// AutostartEnabled: tri-state login-item status.
	//   - *true  : tray reports the app IS registered as a login item
	//   - *false : tray reports the app is NOT registered
	//   - nil    : unknown (tray not running, Linux, or sidecar absent)
	// Pointer intentional so JSON null is distinguishable from false —
	// receivers need this to separate "user disabled" from "we don't know".
	AutostartEnabled *bool `json:"autostart_enabled"`

	// ConnectedClientCount is the number of supported AI clients in which
	// mcpproxy is currently registered (i.e. has the URL/auth in their
	// native config file). Computed by connect.Service from the existing
	// per-client adapter table.
	ConnectedClientCount int `json:"connected_client_count,omitempty"`

	// ConnectedClientIDs are the identifiers of supported clients currently
	// pointing at mcpproxy. Drawn ONLY from the fixed adapter table
	// (e.g. "claude-code", "cursor", "vscode", "windsurf", "codex",
	// "gemini"). User-entered values, paths, and arbitrary strings MUST
	// NEVER appear in this field — the anonymity scanner asserts this.
	ConnectedClientIDs []string `json:"connected_client_ids,omitempty"`

	// WizardEngaged is true once the user completed or explicitly skipped
	// the first-run onboarding wizard. Once true, the wizard does not
	// auto-show again, even if state regresses.
	WizardEngaged bool `json:"wizard_engaged,omitempty"`

	// WizardConnectStep is the per-step status for "Connect an AI client":
	// one of "" (not shown to this install), "completed",
	// "completed_external" (Spec 080: connected outside the wizard —
	// CLI/ConnectModal/manual config — detected at dismissal), or "skipped".
	// Consumers switching on completed|skipped must treat unknown values as
	// "other/engaged".
	WizardConnectStep string `json:"wizard_connect_step,omitempty"`

	// WizardServerStep is the per-step status for "Add an MCP server":
	// one of "" (not shown to this install), "completed", or "skipped".
	WizardServerStep string `json:"wizard_server_step,omitempty"`

	// WizardShown is true once the onboarding wizard has rendered at least
	// once for this install (OnboardingState.FirstShownAt set). Combined
	// with WizardEngaged it makes "shown but ignored" observable:
	// wizard_shown=true with wizard_engaged absent/false.
	WizardShown bool `json:"wizard_shown,omitempty"`

	// WebUIOpened is the lifetime count of embedded Web UI index-document
	// serves (the UI entrypoint), persisted in BBolt. Independent of the
	// X-MCPProxy-Client-header-based surface_requests.webui counter: it
	// counts opening the UI, not SPA API traffic. Asset and API requests
	// never increment it. Coarse by design (health checkers fetching /
	// count too); documented as "index serves".
	WebUIOpened int64 `json:"web_ui_opened,omitempty"`

	// DaysSinceInstall is the whole-day UTC age of the install, from a
	// persisted first-install day stamp independent of anonymous_id.
	// Non-negative (clamped at 0 on clock skew). Pointer so day 0 (install
	// day) is transmitted while "store not wired" is omitted — the same
	// nil-safety as Activation. No install timestamp is ever transmitted.
	DaysSinceInstall *int `json:"days_since_install,omitempty"`

	// ActiveDays30d is the number of distinct active UTC days in the
	// trailing 30-day window (1..30 once any activity is recorded). Only
	// this cardinality leaves the machine; the per-day set stays local.
	ActiveDays30d int `json:"active_days_30d,omitempty"`

	// PreviousShutdown reports how the PREVIOUS process instance ended:
	// "clean" (graceful-shutdown path resolved the persisted marker) or
	// "crash" (marker armed at startup but never resolved — SIGKILL, panic,
	// power loss). Absent on a first-ever run (no prior marker) or when the
	// store is not wired — a fresh install is never misreported as a crash
	// (FR-010/FR-013). Computed once at startup and stable across all
	// heartbeats of the instance (FR-011).
	PreviousShutdown string `json:"previous_shutdown,omitempty"`

	// LastErrorCode is the most recently observed stable MCPX_* diagnostic
	// code (same fixed code set as diagnostics.error_code_counts_24h),
	// persisted across restarts so the post-crash heartbeat carries the
	// pre-crash code. Enum code only — never message text, stack traces,
	// server names, or paths. Absent when no error was ever recorded
	// (FR-012).
	LastErrorCode string `json:"last_error_code,omitempty"`

	// Spec 044 Phase H: diagnostics counter snapshot. Omitted entirely when
	// all counters are zero (omitempty on the pointer). No PII: only stable
	// MCPX_* enum strings, non-negative int counts.
	Diagnostics *DiagnosticsCounters `json:"diagnostics,omitempty"`
}

type LaunchSource string

type OnboardingSnapshot struct {
	ConnectedClientCount int
	ConnectedClientIDs   []string
	WizardEngaged        bool
	WizardConnectStep    string
	WizardServerStep     string
	// WizardShown (Spec 080 US2): the wizard rendered at least once for
	// this install — derived from OnboardingState.FirstShownAt != nil.
	WizardShown bool
}

type OptOutBeacon struct {
	Event       string `json:"event"`
	AnonymousID string `json:"anonymous_id"`
}

type PPIDChecker interface {
	IsLoginItemParent() bool
}

type PreChurnStore interface {
	// ArmShutdownMarker derives the previous instance's shutdown outcome from
	// the persisted marker — PreviousShutdownClean (marker resolved),
	// PreviousShutdownCrash (marker armed but unresolved), or
	// PreviousShutdownUnknown (no marker; first-ever run) — and re-arms the
	// marker for the current instance in the same transaction. Call once,
	// early in startup, so crash loops are visible (FR-010 edge case).
	ArmShutdownMarker(db *bbolt.DB) (string, error)

	// ResolveCleanShutdown marks the current instance's shutdown as graceful.
	// Called from the runtime shutdown path while the DB is still open.
	// Idempotent.
	ResolveCleanShutdown(db *bbolt.DB) error

	// RecordLastErrorCode persists code as the most recent diagnostic code,
	// overwriting any prior value. Only codes registered in the diagnostics
	// catalog (the fixed set behind error_code_counts_24h) are accepted;
	// anything else is silently dropped (FR-012).
	RecordLastErrorCode(db *bbolt.DB, code string) error

	// LastErrorCode returns the most recently recorded MCPX_* code, or ""
	// when none was ever recorded. Values are re-validated at read time so a
	// corrupt on-disk value is never surfaced.
	LastErrorCode(db *bbolt.DB) (string, error)
}

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

type RegistrySnapshot struct {
	SurfaceCounts               map[string]int64            `json:"surface_requests"`
	BuiltinToolCalls            map[string]int64            `json:"builtin_tool_calls"`
	UpstreamToolCallCountBucket string                      `json:"upstream_tool_call_count_bucket"`
	RESTEndpointCalls           map[string]map[string]int64 `json:"rest_endpoint_calls"`
	ErrorCategoryCounts         map[string]int64            `json:"error_category_counts"`
	DoctorChecks                map[string]DoctorCounts     `json:"doctor_checks"`
}

type RuntimeStats interface {
	GetServerCount() int
	GetConnectedServerCount() int
	GetToolCount() int
	GetRoutingMode() string
	IsQuarantineEnabled() bool
	// Schema v3 additions.
	// IsDockerAvailable reports whether the host has a reachable Docker
	// daemon. Implementations should memoize the probe result (running
	// `docker info` on every heartbeat has cost) and return the cached value.
	IsDockerAvailable() bool
	// GetDockerIsolatedServerCount returns how many currently-configured
	// servers the runtime is actually wrapping in a Docker container.
	GetDockerIsolatedServerCount() int
	// GetDockerCLISource returns the coarse, fixed-enum branch that resolved
	// the docker CLI — "path" | "bundled" | "login_shell" | "absent" (schema
	// v5, MCP-2745). Implementations should memoize the resolution (it shares
	// the shellwrap docker-path cache) and NEVER return the path string.
	GetDockerCLISource() string
}

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

type Surface int

type TTYChecker interface {
	IsTerminal() bool
}