LCOV - code coverage report
Current view: top level - packages/telemetry/src - types.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 100.0 % 7 7
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : /**
       2              :  * Telemetry Provider Interface
       3              :  *
       4              :  * CRITICAL: OSS Build Safety
       5              :  * This module is excluded from OSS builds via conditional compilation.
       6              :  * When DISTRIBUTION is unset (OSS builds), Vite's tree-shaking removes this code entirely,
       7              :  * ensuring the open source build contains no telemetry dependencies.
       8              :  *
       9              :  * To verify OSS builds are clean:
      10              :  * 1. `DISTRIBUTION= pnpm build` (OSS build)
      11              :  * 2. `grep -RinE --include='*.js' 'trackWorkflow|trackEvent|mixpanel' dist/` (should find nothing)
      12              :  * 3. Check dist/assets/*.js files contain no tracking code
      13              :  */
      14              : 
      15              : import {
      16              :   AUTH_TELEMETRY_EVENT,
      17              :   SESSION_TELEMETRY_EVENT,
      18              :   SSO_TELEMETRY_EVENT
      19              : } from '@comfyorg/account-core/telemetry'
      20              : import type {
      21              :   BillingCycle,
      22              :   BillingTelemetryEvent,
      23              :   BillingTelemetryEventName,
      24              :   CheckoutJourneyTelemetryEvent,
      25              :   CheckoutJourneyTelemetryEventName,
      26              :   CheckoutJourneyTelemetryEventPayload,
      27              :   ResubscribeSource,
      28              :   BillingTierKey as TierKey,
      29              :   SubscriptionCheckoutTier,
      30              :   SubscriptionCheckoutType
      31              : } from '@comfyorg/account-core/billing'
      32              : import { BILLING_TELEMETRY_EVENTS } from '@comfyorg/account-core/billing'
      33              : import type { BillingSource } from '@comfyorg/billing-contract'
      34              : import type {
      35              :   AgentRunMode,
      36              :   SubscriptionTier,
      37              :   WorkspaceWithRole
      38              : } from '@comfyorg/ingest-types'
      39              : import type {
      40              :   AuthErrorMetadata,
      41              :   AuthFlowAction,
      42              :   AuthMethod,
      43              :   SsoTelemetryEvent,
      44              :   WebSessionTelemetryEvent
      45              : } from '@comfyorg/account-core/telemetry'
      46              : import type { SessionRefreshOutcome } from '@comfyorg/account-core/session'
      47              : 
      48              : import type { AppMode } from '@comfyorg/graph-model/appMode'
      49              : 
      50              : export type { AuthMethod }
      51              : 
      52              : export type PaymentIntentSource = BillingSource
      53              : 
      54              : /**
      55              :  * Authentication metadata for sign-up tracking
      56              :  */
      57              : export interface AuthMetadata {
      58              :   method?: AuthMethod
      59              :   is_new_user?: boolean
      60              :   user_id?: string
      61              :   email?: string
      62              :   share_id?: string
      63              :   referrer_url?: string
      64              :   utm_source?: string
      65              :   utm_medium?: string
      66              :   utm_campaign?: string
      67              : }
      68              : 
      69              : export type { AuthErrorMetadata, AuthFlowAction }
      70              : 
      71              : export type UnifiedAuthRetryFailureReason =
      72              :   | 'missing_bearer'
      73              :   | 'non_replayable_body'
      74              :   | 'remint_failed'
      75              :   | 'retry_rejected'
      76              :   | 'retry_request_failed'
      77              :   | 'token_unavailable'
      78              : 
      79              : export interface UnifiedAuthRetryMetadata {
      80              :   transport: 'axios' | 'fetch' | 'ws'
      81              :   outcome: 'succeeded' | 'failed'
      82              :   final_status?: number
      83              :   failure_reason?: UnifiedAuthRetryFailureReason
      84              : }
      85              : 
      86              : export type UnifiedAuthRefreshOutcome = SessionRefreshOutcome
      87              : 
      88              : /**
      89              :  * Outcome of one proactive unified Cloud-JWT refresh attempt. This lifecycle
      90              :  * drives session-cookie rotation, so a dead refresh chain breaks every
      91              :  * cookie-authenticated <img>/media load (FE-1595).
      92              :  */
      93              : export interface UnifiedAuthRefreshMetadata {
      94              :   outcome: UnifiedAuthRefreshOutcome
      95              :   retry_count?: number
      96              : }
      97              : 
      98              : /**
      99              :  * One failed image preview. An `<img>` error event reports no status, so
     100              :  * everything past `source` is reconstructed by `describeImageLoadFailure()`:
     101              :  * `status` comes from re-requesting the URL once, the rest from the URL and the
     102              :  * page. Fields are optional because a probe that was capped, blocked or never
     103              :  * applicable must still produce a report — a missing field is a real outcome,
     104              :  * recorded in `probe_outcome` rather than guessed at.
     105              :  */
     106              : export interface ImageLoadFailureMetadata {
     107              :   /**
     108              :    * Which surface failed. `node_image_preview` / `node_video_preview` are the
     109              :    * Vue node renderer; `canvas_node_image` / `canvas_node_video` are the
     110              :    * litegraph canvas previews. `Comfy.VueNodes.Enabled` defaults off, but on
     111              :    * for Cloud and Desktop users whose `Comfy.InstalledVersion` is 1.41.0 or
     112              :    * later, and App Builder turns it on.
     113              :    * Splitting on this is what keeps a rate measured on one renderer from being
     114              :    * read as the rate for everyone.
     115              :    * Under Vue nodes, an upload widget still loads its preview through the
     116              :    * canvas loader, so one broken upload can report under both a `canvas_*`
     117              :    * and a `node_*` source. Count per source rather than summing them.
     118              :    */
     119              :   source:
     120              :     | 'node_image_preview'
     121              :     | 'node_video_preview'
     122              :     | 'canvas_node_image'
     123              :     | 'canvas_node_video'
     124              :   /** Load attempts made before giving up, including the first. */
     125              :   attempts?: number
     126              :   /** True when the load timed out rather than erroring — a stall, not a rejection. */
     127              :   timed_out?: boolean
     128              :   /** HTTP status of the follow-up probe. Absent unless `probe_outcome` is `probed`. */
     129              :   status?: number
     130              :   probe_outcome?:
     131              :     | 'probed'
     132              :     | 'probe_failed'
     133              :     | 'probe_timeout'
     134              :     | 'probe_capped'
     135              :     | 'probe_blocked'
     136              :     | 'probe_redirected'
     137              :     | 'probe_abandoned'
     138              :     | 'invalid_src'
     139              :   /** `/api/view?type=` — separates an expired output from a missing upload. */
     140              :   resource_kind?: 'output' | 'input' | 'temp' | 'unspecified' | 'not_api_view'
     141              :   /** Filename shape only; never the filename, which is user-authored. */
     142              :   filename_kind?: 'content_hash' | 'template' | 'named' | 'none'
     143              :   /** Time since this page loaded. Auth-expiry failures skew old; 404s do not. */
     144              :   page_age_ms?: number
     145              :   online?: boolean
     146              :   same_origin?: boolean
     147              : }
     148              : 
     149              : /**
     150              :  * One row per session describing how long startup took and where the time
     151              :  * went. `total_ms` is measured from navigation start, so it is directly
     152              :  * comparable to what a user experiences and can be percentiled across sessions
     153              :  * without joining per-phase events.
     154              :  *
     155              :  * `outcome` keeps the bad sessions in the data:
     156              :  * - `completed` — the loading screen came down normally.
     157              :  * - `failed` — startup threw; the loading screen came down anyway.
     158              :  * - `timed_out` — startup was still running at the watchdog deadline. Emitted
     159              :  *   *in addition to* whichever terminal row eventually follows, so a load that
     160              :  *   hangs is counted even when it never finishes. `pending` names the phases
     161              :  *   still open, which is where the session is stuck.
     162              :  *
     163              :  * Without the `timed_out` row the sessions users complain about are precisely
     164              :  * the ones absent from the data.
     165              :  */
     166              : export interface BootstrapCompleteMetadata {
     167              :   total_ms: number
     168              :   outcome: 'completed' | 'failed' | 'timed_out'
     169              :   phase_count: number
     170              :   /** Wall-clock ms not covered by any recorded phase. */
     171              :   untraced_ms: number
     172              :   /** Wall-clock ms the tab was hidden during startup. */
     173              :   hidden_ms: number
     174              :   /**
     175              :    * Per-phase durations, keyed `<namespace>/<phase>` (e.g.
     176              :    * `bootstrap/object-info`). Nested phases intentionally overlap their
     177              :    * aggregate parent, so consumers must not sum entries across the map.
     178              :    */
     179              :   phases: Record<string, number>
     180              :   /** Phases still running when this row was emitted. Only set for `timed_out`. */
     181              :   pending?: string[]
     182              : }
     183              : 
     184              : /**
     185              :  * Survey field ids mapped to answers. Fields are backend-overridable, so all
     186              :  * are optional.
     187              :  */
     188              : export interface SurveyResponses {
     189              :   // Current default schema (see defaultSurveySchema.ts)
     190              :   intent?: string | string[]
     191              :   intentOther?: string
     192              :   experience?: string
     193              :   focus?: string
     194              :   source?: string
     195              :   sourceOther?: string
     196              :   source_social?: string
     197              :   // Legacy fields — only emitted by older backend-supplied schemas, never by
     198              :   // the current default. Kept so historical responses still typecheck.
     199              :   familiarity?: string
     200              :   industry?: string
     201              :   useCase?: string
     202              :   making?: string[]
     203              :   role?: string
     204              :   teamSize?: string
     205              :   usage?: string
     206              : }
     207              : 
     208              : /** Stages inside the coachmark sequence, which is what `step_count` counts. */
     209              : export type OnboardingTourStepStage =
     210              :   | 'not_started'
     211              :   | 'started'
     212              :   | 'step_shown'
     213              :   | 'completed'
     214              :   | 'skipped'
     215              : 
     216              : /** The nudge follows the tour, so it has no step to report. */
     217              : export type OnboardingTourNudgeStage =
     218              :   | 'nudge_shown'
     219              :   | 'explore_templates_clicked'
     220              : 
     221              : export type OnboardingTourStage =
     222              :   | OnboardingTourStepStage
     223              :   | OnboardingTourNudgeStage
     224              : 
     225              : export type OnboardingTourSkipReason =
     226              :   | 'user'
     227              :   | 'target_timeout'
     228              :   | 'trigger_lost'
     229              :   | 'postponed'
     230              : 
     231              : export type OnboardingTourNotStartedReason =
     232              :   | 'already_seen'
     233              :   | 'no_roles'
     234              :   | 'run_only'
     235              :   | 'no_steps'
     236              :   | 'resolver_failed'
     237              : 
     238              : /**
     239              :  * `step_number` is 1-based and matches the "Step N of M" indicator the user
     240              :  * sees, with `step_count` as M. Both `step_number` and `coach_id` are absent
     241              :  * for steps with no numbered spotlight (e.g. the landing). `skip_reason` is
     242              :  * present only on the `skipped` stage.
     243              :  */
     244              : export interface OnboardingTourStepMetadata {
     245              :   tour: string
     246              :   step_count: number
     247              :   step_number?: number
     248              :   coach_id?: string
     249              :   skip_reason?: OnboardingTourSkipReason
     250              :   not_started_reason?: OnboardingTourNotStartedReason
     251              : }
     252              : 
     253              : /** The nudge is post-tour, so it reports no step and no count. */
     254              : export interface OnboardingTourNudgeMetadata {
     255              :   tour: string
     256              :   /**
     257              :    * Whether the tour was walked to the end. Without it `nudge_shown` and
     258              :    * `explore_templates_clicked` cannot be split by how the tour ended, so a
     259              :    * conversion from a completed tour and one from a tour that never started
     260              :    * land in the same bucket.
     261              :    */
     262              :   tour_completed?: boolean
     263              : }
     264              : 
     265              : export type OnboardingTourMetadata =
     266              :   | OnboardingTourStepMetadata
     267              :   | OnboardingTourNudgeMetadata
     268              : 
     269              : export type InAppSurveyStage = 'shown' | 'sent' | 'dismissed'
     270              : 
     271              : export interface InAppSurveyEvent {
     272              :   surveyId: string
     273              :   responses?: Record<string, string>
     274              :   properties?: Record<string, string>
     275              : }
     276              : 
     277              : export interface SurveyResponsesNormalized extends SurveyResponses {
     278              :   industry_normalized?: string
     279              :   industry_raw?: string
     280              :   useCase_normalized?: string
     281              :   useCase_raw?: string
     282              : }
     283              : 
     284              : type AuthRail = 'web_session' | 'token'
     285              : 
     286              : /**
     287              :  * The selected workspace and the auth rail its requests ride on. The RUM
     288              :  * global context and the Run-gate events carry it, so a blocked run or a
     289              :  * failure can be split by the workspace it was scoped to.
     290              :  */
     291              : export interface WorkspaceTelemetryContext {
     292              :   workspace_id: string
     293              :   workspace_type: WorkspaceWithRole['type']
     294              :   workspace_role: WorkspaceWithRole['role']
     295              :   workspace_tier: SubscriptionTier | null
     296              :   auth_rail: AuthRail
     297              : }
     298              : 
     299              : /** A billing read for the selected workspace that the server resolved for another. */
     300              : export interface WorkspaceScopeMismatchMetadata extends WorkspaceTelemetryContext {
     301              :   resolved_workspace_id: string
     302              :   resolved_workspace_type: WorkspaceWithRole['type'] | 'unknown'
     303              : }
     304              : 
     305              : /**
     306              :  * Run button tracking properties
     307              :  */
     308              : export interface RunButtonProperties extends Partial<WorkspaceTelemetryContext> {
     309              :   subscribe_to_run: boolean
     310              :   workflow_type: 'template' | 'custom'
     311              :   workflow_name: string
     312              :   custom_node_count: number
     313              :   total_node_count: number
     314              :   subgraph_count: number
     315              :   has_api_nodes: boolean
     316              :   api_node_names: string[]
     317              :   has_toolkit_nodes: boolean
     318              :   toolkit_node_names: string[]
     319              :   trigger_source?: ExecutionTriggerSource
     320              :   view_mode: AppMode
     321              :   is_app_mode: boolean
     322              :   dock_state: ActionbarDockState
     323              :   /** Whether the agent panel was open when the run was submitted. */
     324              :   agent_panel_open: boolean
     325              : }
     326              : 
     327              : /**
     328              :  * Execution context for workflow tracking
     329              :  */
     330              : export interface ExecutionContext {
     331              :   is_template: boolean
     332              :   workflow_name?: string
     333              :   // Template metadata (only present when is_template = true)
     334              :   template_source?: string
     335              :   template_category?: string
     336              :   template_tags?: string[]
     337              :   template_models?: string[]
     338              :   template_use_case?: string
     339              :   template_license?: string
     340              :   // Node composition metrics
     341              :   custom_node_count: number
     342              :   api_node_count: number
     343              :   subgraph_count: number
     344              :   total_node_count: number
     345              :   has_api_nodes: boolean
     346              :   api_node_names: string[]
     347              :   has_toolkit_nodes: boolean
     348              :   toolkit_node_names: string[]
     349              :   toolkit_node_count: number
     350              :   trigger_source?: ExecutionTriggerSource
     351              : }
     352              : 
     353              : /**
     354              :  * Execution error metadata
     355              :  */
     356              : export interface ExecutionErrorMetadata {
     357              :   jobId: string
     358              :   nodeId?: string
     359              :   nodeType?: string
     360              :   error?: string
     361              : }
     362              : 
     363              : export interface WorkflowExecutionContext {
     364              :   workflow_type: 'template' | 'custom'
     365              :   view_mode: AppMode
     366              :   execution_scope: 'full' | 'partial'
     367              :   total_node_count: number
     368              :   executable_node_count: number
     369              :   custom_node_count: number
     370              :   api_node_count: number
     371              :   subgraph_count: number
     372              : }
     373              : 
     374              : export interface WorkflowQueueIntent {
     375              :   trigger_source?: ExecutionTriggerSource
     376              : }
     377              : 
     378              : export interface WorkflowExecutionIntent {
     379              :   trigger_source: ExecutionTriggerSource
     380              : }
     381              : 
     382              : export type WorkflowExecutionFailureReason =
     383              :   | 'prompt_build_failed'
     384              :   | 'submission_rejected'
     385              :   | 'submission_failed'
     386              :   | 'execution_failed'
     387              :   | 'execution_interrupted'
     388              : 
     389              : interface ExecutionOutcomeBaseMetadata extends WorkflowExecutionIntent {
     390              :   startTime: number
     391              :   submissionAcceptedAt?: number
     392              :   executionStartedAt?: number
     393              :   endTime: number
     394              :   workflowContext?: WorkflowExecutionContext
     395              : }
     396              : 
     397              : export type ExecutionOutcomeMetadata = ExecutionOutcomeBaseMetadata &
     398              :   (
     399              :     | {
     400              :         success: true
     401              :         failureReason: ''
     402              :       }
     403              :     | {
     404              :         success: false
     405              :         failureReason: WorkflowExecutionFailureReason
     406              :       }
     407              :   )
     408              : 
     409              : /**
     410              :  * Execution success metadata
     411              :  */
     412              : export interface ExecutionSuccessMetadata {
     413              :   jobId: string
     414              : }
     415              : 
     416              : export interface SharedWorkflowRunMetadata {
     417              :   job_id: string
     418              :   share_id: string
     419              :   view_mode: AppMode
     420              :   is_app_mode: boolean
     421              : }
     422              : 
     423              : export type ActionbarDockState = 'docked' | 'floating'
     424              : 
     425              : /**
     426              :  * Template metadata for workflow tracking
     427              :  */
     428              : export interface TemplateMetadata {
     429              :   workflow_name: string
     430              :   template_source?: string
     431              :   template_category?: string
     432              :   template_tags?: string[]
     433              :   template_models?: string[]
     434              :   template_use_case?: string
     435              :   template_license?: string
     436              : }
     437              : 
     438              : /**
     439              :  * Credit topup metadata
     440              :  */
     441              : export interface CreditTopupMetadata {
     442              :   credit_amount: number
     443              : }
     444              : 
     445              : /**
     446              :  * Workflow import metadata
     447              :  */
     448              : export interface MissingNodePack {
     449              :   /**
     450              :    * Custom node pack identifier (cnrId / aux_id from node properties).
     451              :    * `'unknown'` when the workflow JSON has no pack hint for the node.
     452              :    */
     453              :   pack_id: string
     454              :   node_types: string[]
     455              : }
     456              : 
     457              : export interface WorkflowImportMetadata {
     458              :   missing_node_count: number
     459              :   missing_node_types: string[]
     460              :   /**
     461              :    * Missing nodes grouped by their custom node pack. Populated from the
     462              :    * `cnr_id` / `aux_id` baked into node properties — no network lookups.
     463              :    */
     464              :   missing_node_packs?: MissingNodePack[]
     465              :   /**
     466              :    * The source of the workflow open/import action
     467              :    */
     468              :   open_source?:
     469              :     | 'file_button'
     470              :     | 'file_drop'
     471              :     | 'template'
     472              :     | 'shared_url'
     473              :     | 'unknown'
     474              :   share_id?: string
     475              : }
     476              : 
     477              : export interface EnterLinearMetadata {
     478              :   source?: string
     479              : }
     480              : 
     481              : export type WorkflowLinkOutOfSyncReason =
     482              :   | 'no_sidebar_path'
     483              :   | 'name_ambiguous'
     484              :   | 'file_missing'
     485              :   | 'content_mismatch'
     486              :   | 'unknown'
     487              : 
     488              : export type WorkflowLinkOpenedMetadata =
     489              :   | {
     490              :       outcome: 'opened' | 'not_found' | 'error'
     491              :       workspace_id: string | null
     492              :     }
     493              :   | {
     494              :       outcome: 'out_of_sync'
     495              :       reason: WorkflowLinkOutOfSyncReason
     496              :       workspace_id: string | null
     497              :     }
     498              : 
     499              : export interface WorkflowSavedMetadata {
     500              :   is_app: boolean
     501              :   is_new: boolean
     502              : }
     503              : 
     504              : export interface DefaultViewSetMetadata {
     505              :   default_view: 'app' | 'graph'
     506              : }
     507              : 
     508              : type ShareFlowStep =
     509              :   | 'dialog_opened'
     510              :   | 'save_prompted'
     511              :   | 'link_created'
     512              :   | 'link_copied'
     513              : 
     514              : export interface ShareFlowMetadata {
     515              :   step: ShareFlowStep
     516              :   source?: 'app_mode' | 'graph_mode'
     517              :   share_id?: string
     518              :   view_mode: AppMode
     519              :   is_app_mode: boolean
     520              : }
     521              : 
     522              : export interface ShareLinkOpenedMetadata {
     523              :   share_id: string
     524              :   is_authenticated: boolean
     525              :   view_mode: AppMode
     526              :   is_app_mode: boolean
     527              : }
     528              : 
     529              : /**
     530              :  * Workflow open metadata
     531              :  */
     532              : /**
     533              :  * Enumerated sources for workflow open/import actions.
     534              :  */
     535              : export type WorkflowOpenSource = NonNullable<
     536              :   WorkflowImportMetadata['open_source']
     537              : >
     538              : 
     539              : /**
     540              :  * Template library metadata
     541              :  */
     542              : export interface TemplateLibraryMetadata {
     543              :   source: 'sidebar' | 'menu' | 'command' | 'appbuilder' | 'first_run_nudge'
     544              : }
     545              : 
     546              : /**
     547              :  * Template library closed metadata
     548              :  */
     549              : export interface TemplateLibraryClosedMetadata {
     550              :   template_selected: boolean
     551              :   time_spent_seconds: number
     552              : }
     553              : 
     554              : /**
     555              :  * Page visibility metadata
     556              :  */
     557              : export interface PageVisibilityMetadata {
     558              :   visibility_state: 'visible' | 'hidden'
     559              :   agent_panel_open: boolean
     560              : }
     561              : 
     562              : /**
     563              :  * Tab count metadata
     564              :  */
     565              : export interface TabCountMetadata {
     566              :   tab_count: number
     567              : }
     568              : 
     569              : /**
     570              :  * Shell layout snapshot, sent once per session when the app is ready
     571              :  */
     572              : export interface ShellLayoutMetadata {
     573              :   view_mode: AppMode
     574              :   is_app_mode: boolean
     575              :   dock_state: ActionbarDockState
     576              :   actionbar_position: string
     577              :   active_sidebar_tab: string | null
     578              :   right_side_panel_open: boolean
     579              :   bottom_panel_open: boolean
     580              :   open_workflow_tabs: number
     581              : }
     582              : 
     583              : /**
     584              :  * Settings change metadata
     585              :  */
     586              : export interface SettingChangedMetadata {
     587              :   setting_id: string
     588              :   previous_value?: unknown
     589              :   new_value?: unknown
     590              : }
     591              : 
     592              : /**
     593              :  * Node search metadata
     594              :  */
     595              : export interface NodeSearchMetadata {
     596              :   query: string
     597              : }
     598              : 
     599              : /**
     600              :  * Search query metadata. One event per debounced query change across
     601              :  * each search surface.
     602              :  */
     603              : export type SearchSurface =
     604              :   | 'node_modal'
     605              :   | 'node_sidebar'
     606              :   | 'apps'
     607              :   | 'templates'
     608              :   | 'settings'
     609              : 
     610              : export interface SearchQueryMetadata {
     611              :   surface: SearchSurface
     612              :   query: string
     613              :   query_length: number
     614              :   result_count: number
     615              :   has_results: boolean
     616              : }
     617              : 
     618              : /**
     619              :  * Node added metadata. `source` indicates how the user initiated the add.
     620              :  * Bulk additions during workflow load are excluded — workflow_imported
     621              :  * already covers that.
     622              :  */
     623              : export type NodeAddSource =
     624              :   | 'sidebar_drag'
     625              :   | 'asset_browser'
     626              :   | 'search_modal'
     627              :   | 'paste'
     628              :   | 'programmatic'
     629              :   | 'unknown'
     630              : 
     631              : export interface NodeAddedMetadata {
     632              :   node_type: string
     633              :   source: NodeAddSource
     634              : }
     635              : 
     636              : /**
     637              :  * Node search result selection metadata
     638              :  */
     639              : export interface NodeSearchResultMetadata {
     640              :   node_type: string
     641              :   last_query: string
     642              : }
     643              : 
     644              : /**
     645              :  * Template filter tracking metadata
     646              :  */
     647              : export interface TemplateFilterMetadata {
     648              :   search_query?: string
     649              :   selected_models: string[]
     650              :   selected_use_cases: string[]
     651              :   selected_runs_on: string[]
     652              :   sort_by:
     653              :     | 'relevance'
     654              :     | 'default'
     655              :     | 'recommended'
     656              :     | 'popular'
     657              :     | 'alphabetical'
     658              :     | 'newest'
     659              :     | 'vram-low-to-high'
     660              :     | 'model-size-low-to-high'
     661              :   filtered_count: number
     662              :   total_count: number
     663              : }
     664              : 
     665              : /**
     666              :  * UI button click tracking metadata
     667              :  */
     668              : export interface UiButtonClickMetadata {
     669              :   button_id: string
     670              :   element_group: string
     671              : }
     672              : 
     673              : /**
     674              :  * In-App Agent message rating metadata (PM-98). `vote` is null when the user retracts a
     675              :  * prior thumb, which the eval pipeline records as a retraction rather than dropping.
     676              :  */
     677              : export interface AgentMessageFeedbackMetadata extends Record<string, unknown> {
     678              :   message_id: string
     679              :   turn_id: string
     680              :   vote: 'up' | 'down' | null
     681              :   workflow_id: string | null
     682              : }
     683              : 
     684              : export type AgentPanelCloseSource =
     685              :   | 'close_button'
     686              :   | 'workflow_switch'
     687              :   | 'topbar_button'
     688              :   | 'pagehide'
     689              : export interface AgentPanelOpenedMetadata extends Record<string, unknown> {
     690              :   source:
     691              :     | 'restored'
     692              :     | 'topbar_button'
     693              :     | 'automatic_consent'
     694              :     | 'activation'
     695              :     | 'error_context'
     696              :     | 'cloud_button'
     697              : }
     698              : export type AgentConsentNotOfferedReason =
     699              :   | 'first_run_screen'
     700              :   | 'tour_active'
     701              :   | 'dialog_open'
     702              :   | 'boot_undecided'
     703              :   | 'storage_unavailable'
     704              : export interface AgentConsentNotOfferedMetadata extends Record<
     705              :   string,
     706              :   unknown
     707              : > {
     708              :   reason: AgentConsentNotOfferedReason
     709              : }
     710              : /**
     711              :  * Why an automatic consent offer ended without making the offer or naming a
     712              :  * surface that holds it. Query by `exit`; see the Agent README.
     713              :  */
     714              : export type AgentConsentOfferExit =
     715              :   /** The stored consent read has not settled, so consent is unknown. */
     716              :   | 'consent_unresolved'
     717              :   /** The stored consent read rejected. */
     718              :   | 'consent_read_failed'
     719              :   /** Consent is already stored for this scope, so no card is needed. */
     720              :   | 'consent_already_accepted'
     721              :   /** Another offer attempt for this page load has not finished. */
     722              :   | 'offer_in_flight'
     723              :   /** The card has already been on screen for this scope this page load. */
     724              :   | 'card_already_seen'
     725              :   /** This launch is past the panel's automatic-open launches. */
     726              :   | 'activation_window_complete'
     727              :   /** The first-run startup probe rejected. */
     728              :   | 'startup_probe_failed'
     729              :   /**
     730              :    * The consent scope moved while it was being resolved - a different account,
     731              :    * a workspace transition, or a switch that started - so the read that would
     732              :    * have decided whether to ask was never made. `request` stage only.
     733              :    */
     734              :   | 'scope_changed_before_read'
     735              :   /**
     736              :    * Resolving the consent scope raised. The account or the workspace went away
     737              :    * between the offer decision and the request. `request` stage only.
     738              :    */
     739              :   | 'scope_probe_failed'
     740              :   /**
     741              :    * The consent scope moved while the stored-consent read was in flight, so the
     742              :    * answer that came back belonged to a scope that is no longer current.
     743              :    * `request` stage only.
     744              :    */
     745              :   | 'scope_changed_after_read'
     746              :   /**
     747              :    * The card was asked for and the dialog closed before it rendered, so there
     748              :    * is no `agent_consent_shown` and no outcome to record against one. `request`
     749              :    * stage only.
     750              :    */
     751              :   | 'card_closed_before_mount'
     752              : /**
     753              :  * Which link in the offer chain exited. The same condition is checked at more
     754              :  * than one of these - the pair (`exit`, `stage`) is what identifies a single
     755              :  * exit in the code, so neither property is readable on its own.
     756              :  */
     757              : export type AgentConsentOfferStage =
     758              :   /** `loadConsentIfEligible` - before the consent read, or on its result. */
     759              :   | 'load'
     760              :   /** Waiting on the first-run startup decision. */
     761              :   | 'startup'
     762              :   /** `offerConsentUnprompted` - the offer attempt itself. */
     763              :   | 'offer'
     764              :   /** The consent request itself, after the chain has decided to ask. */
     765              :   | 'request'
     766              : export interface AgentConsentOfferExitedMetadata extends Record<
     767              :   string,
     768              :   unknown
     769              : > {
     770              :   exit: AgentConsentOfferExit
     771              :   stage: AgentConsentOfferStage
     772              :   /**
     773              :    * Whether a hold was armed at the moment of the exit, i.e. whether this page
     774              :    * load still has a queued retry. False on an owed-and-not-made exit means the
     775              :    * offer is gone for this page load with nothing scheduled to bring it back.
     776              :    *
     777              :    * Two qualifications, both from the `request` stage. It is **structurally
     778              :    * false** there: the offer drops the hold immediately before requesting, and
     779              :    * the only thing that re-arms it is the `canShow` hook, which runs after
     780              :    * every `request` exit. And the hold is not the only wake-up - `withConsent`
     781              :    * settling re-drives the chain when the identity changed - so on the two
     782              :    * `scope_changed_*` exits a retry does happen, by a mechanism this property
     783              :    * does not describe.
     784              :    */
     785              :   retry_armed: boolean
     786              :   /**
     787              :    * Which surface asked. Set **only** at the `request` stage, which is the one
     788              :    * stage reachable from the topbar button as well as the automatic offer;
     789              :    * every other stage is inside `offerConsentUnprompted` and automatic by
     790              :    * construction. A query about automatic offers must therefore either restrict
     791              :    * to `stage != 'request'` or filter `trigger = 'first_load'` - counting the
     792              :    * `request` stage unsplit mixes a user-initiated click into the automatic
     793              :    * denominator.
     794              :    */
     795              :   trigger?: AgentConsentTrigger
     796              : }
     797              : export type AgentOnboardingNotShownMetadata =
     798              :   | { reason: 'app_mode' | 'tour_active' | 'dialog_open' }
     799              :   | { reason: 'target_missing'; step: number }
     800              : export type AgentSendGate = 'composer' | 'consent' | 'coach'
     801              : export type AgentComposerDropReason =
     802              :   | 'cannot_submit'
     803              :   | 'submission_pending'
     804              :   | 'no_target'
     805              :   | 'empty'
     806              :   | 'attachment_uploading'
     807              : /**
     808              :  * The session refused a submitted send: `send_busy` while another is in
     809              :  * flight, `target_unavailable` when its workflow target changed or has no canvas.
     810              :  */
     811              : export type AgentSessionRefusalReason = 'send_busy' | 'target_unavailable'
     812              : /** `not_completed`: the consent flow ended without accept, decline or dismiss. */
     813              : export type AgentConsentDropReason =
     814              :   | 'declined'
     815              :   | 'dismissed'
     816              :   | 'not_completed'
     817              :   | 'panel_closed'
     818              : export type AgentCoachReleaseReason =
     819              :   | 'finished'
     820              :   | 'skipped'
     821              :   | 'elsewhere'
     822              :   | 'stalled'
     823              :   | 'deferred_app_mode'
     824              :   | 'deferred_tour_active'
     825              :   | 'deferred_dialog_open'
     826              : export type AgentCoachDropReason =
     827              :   | 'panel_closed'
     828              :   | 'consent_cleared'
     829              :   | 'identity_changed'
     830              : type AgentSendGateOutcome =
     831              :   | {
     832              :       gate: 'composer'
     833              :       outcome: 'dropped'
     834              :       reason: AgentComposerDropReason
     835              :       client_message_id: null
     836              :       held_ms: null
     837              :     }
     838              :   | {
     839              :       gate: 'composer'
     840              :       outcome: 'dropped'
     841              :       reason: AgentSessionRefusalReason
     842              :       client_message_id: string | null
     843              :       held_ms: null
     844              :     }
     845              :   | {
     846              :       gate: 'consent' | 'coach'
     847              :       outcome: 'held'
     848              :       reason: null
     849              :       client_message_id: string
     850              :       held_ms: null
     851              :     }
     852              :   | {
     853              :       gate: 'consent'
     854              :       outcome: 'released'
     855              :       reason: 'accepted'
     856              :       client_message_id: string
     857              :       held_ms: number
     858              :     }
     859              :   | {
     860              :       gate: 'consent'
     861              :       outcome: 'dropped'
     862              :       reason: AgentConsentDropReason
     863              :       client_message_id: string
     864              :       held_ms: number
     865              :     }
     866              :   | {
     867              :       gate: 'coach'
     868              :       outcome: 'released'
     869              :       reason: AgentCoachReleaseReason
     870              :       client_message_id: string
     871              :       held_ms: number
     872              :     }
     873              :   | {
     874              :       gate: 'coach'
     875              :       outcome: 'dropped'
     876              :       reason: AgentCoachDropReason
     877              :       client_message_id: string
     878              :       held_ms: number
     879              :     }
     880              : /**
     881              :  * A first-send gate outcome, joinable to `app:agent_message_sent` by
     882              :  * `client_message_id`.
     883              :  */
     884              : export type AgentSendGatedMetadata = AgentSendGateOutcome & {
     885              :   thread_id: string | null
     886              :   /** Page load id, also sent on the agent feedback form. */
     887              :   client_session_id: string
     888              : }
     889              : export interface AgentPanelClosedMetadata extends Record<string, unknown> {
     890              :   source: AgentPanelCloseSource
     891              :   open_duration_ms: number | null
     892              : }
     893              : /** How far the open panel got before its content was drawn. */
     894              : export type AgentPanelRenderStage =
     895              :   | 'dock_unresolved'
     896              :   | 'root_unresolved'
     897              :   | 'root_resolved_not_mounted'
     898              : export interface AgentPanelRenderStalledMetadata extends Record<
     899              :   string,
     900              :   unknown
     901              : > {
     902              :   stage: AgentPanelRenderStage
     903              : }
     904              : export interface AgentEntryButtonClickedMetadata extends Record<
     905              :   string,
     906              :   unknown
     907              : > {
     908              :   resulting_state: 'opened' | 'closed'
     909              : }
     910              : export type AgentConsentTrigger =
     911              :   | 'first_load'
     912              :   | 'button_click'
     913              :   | 'first_message'
     914              : export interface AgentConsentShownMetadata extends Record<string, unknown> {
     915              :   trigger: AgentConsentTrigger
     916              : }
     917              : /**
     918              :  * How a consent card that was on screen ended, plus the moment consent becomes
     919              :  * stored. It used to carry only the two deciding values, which left a card that
     920              :  * was shown and then went quiet covering three different endings at once - a
     921              :  * dismissal, an acceptance whose save did not stick, and a signed-out
     922              :  * acceptance whose sign-in was abandoned. Those are now named, and
     923              :  * `save_error_shown` separates giving up after a failed save from walking away.
     924              :  *
     925              :  * **Only `accepted` means consent is stored.** That was this event's whole
     926              :  * meaning before the other values existed, so any query that counted it as "a
     927              :  * decision that stuck" must now filter `decision = 'accepted'`, and one that
     928              :  * wants "the user answered" wants `decision in ('accepted', 'rejected')`.
     929              :  *
     930              :  * **The pairing with `agent_consent_shown`, exactly.** For a signed-in user -
     931              :  * the whole cloud population - every impression ends in exactly one of these,
     932              :  * so an impression with no outcome is a defect rather than a dismissal. In the
     933              :  * signed-out (local) flow the card is only the first half: it ends at
     934              :  * `accepted_pending_sign_in`, and `accepted` follows separately if the sign-in
     935              :  * and the real save land. So `accepted` is the one value that is not always the
     936              :  * card's own ending, which is how it keeps meaning "consent is stored".
     937              :  */
     938              : export type AgentConsentDecision =
     939              :   /** Accepted, and the acceptance is durably stored. */
     940              :   | 'accepted'
     941              :   /** Declined on the card. Nothing is stored; the card can be offered again. */
     942              :   | 'rejected'
     943              :   /**
     944              :    * Closed without deciding - Escape, the overlay mask, or a programmatic close
     945              :    * such as navigation. Distinguishing this from `accept_not_persisted` is the
     946              :    * difference between the user walking away and the product failing them.
     947              :    */
     948              :   | 'dismissed'
     949              :   /**
     950              :    * Accepted, and the write did not stick without raising: the scope moved
     951              :    * mid-save or the workspace auth header was gone. The user believes they
     952              :    * consented and no consent exists.
     953              :    */
     954              :   | 'accept_not_persisted'
     955              :   /**
     956              :    * Accepted the card in the signed-out flow, where the card is only the first
     957              :    * half: a sign-in and a real save still have to land before consent exists,
     958              :    * and they report `accepted` themselves when they do. So this value with no
     959              :    * later `accepted` is an abandoned sign-in, which is the third case this
     960              :    * event could not previously name.
     961              :    */
     962              :   | 'accepted_pending_sign_in'
     963              : export interface AgentConsentResolvedMetadata extends Record<string, unknown> {
     964              :   decision: AgentConsentDecision
     965              :   /**
     966              :    * Whether the card had already shown a save error when it reached this
     967              :    * outcome. A raised save leaves the card open and retryable, so its ending is
     968              :    * one of the values above rather than an outcome of its own - this is what
     969              :    * tells "dismissed after the save failed" from "dismissed without trying",
     970              :    * and marks an `accepted` that only landed on a retry.
     971              :    */
     972              :   save_error_shown: boolean
     973              : }
     974              : export type AgentOnboardingAction = 'next' | 'finish' | 'skip'
     975              : export type AgentOnboardingCard = 'intro' | 'workflow' | 'history'
     976              : /**
     977              :  * `step` is 1-based and matches the "Step N of M" indicator on the card.
     978              :  * `finish` marks completion, so the gap from `agent_onboarding_shown` is the
     979              :  * onboarding time. `card` is the stable identity to funnel on, since `step`
     980              :  * shifts when cards change. `total` is the tour length at the time of the event.
     981              :  */
     982              : export interface AgentOnboardingStepMetadata extends Record<string, unknown> {
     983              :   step: number
     984              :   card: AgentOnboardingCard
     985              :   total: number
     986              :   action: AgentOnboardingAction
     987              : }
     988              : /**
     989              :  * Where the composer's text came from, by the affordance that put it there:
     990              :  * `suggestion` is an empty-state suggestion chip, `edited` is an earlier prompt
     991              :  * reopened through the conversation's edit action, and `typed` is everything
     992              :  * the user wrote themselves. Each send falls into exactly one — a chip the user
     993              :  * then reworded stays `suggestion`, because the chip is still what it came from.
     994              :  */
     995              : export type AgentInputMethod =
     996              :   | 'typed'
     997              :   | 'suggestion'
     998              :   | 'edited'
     999              :   | 'error_context'
    1000              : /**
    1001              :  * A starter prompt by the slot it occupies in the empty state, not by the text
    1002              :  * it shows: the copy is owned elsewhere and changes without the funnel
    1003              :  * changing. `unregistered` means the rendered set is larger than this union —
    1004              :  * a prompt was appended to either English distribution list without a matching
    1005              :  * entry in `starterPrompts.ts`, so that extra chip reads as an unmapped slot.
    1006              :  */
    1007              : export type AgentStarterPromptId =
    1008              :   | 'slot_1'
    1009              :   | 'slot_2'
    1010              :   | 'slot_3'
    1011              :   | 'slot_4'
    1012              :   | 'slot_5'
    1013              :   | 'unregistered'
    1014              : /**
    1015              :  * Where the free-use notice was placed, for the DES-1221 placement experiment.
    1016              :  *
    1017              :  * Deliberately the PostHog variant keys verbatim: the analysis joins this property to
    1018              :  * `$feature/agent-free-use-message-placement`, and a translation layer between
    1019              :  * the two is one more place for the arms to drift apart.
    1020              :  */
    1021         2356 : export const AGENT_FREE_USE_PLACEMENTS = [
    1022              :   'top-banner',
    1023              :   'near-composer',
    1024              :   'above-input',
    1025              :   'inside-input'
    1026              : ] as const
    1027              : export type AgentFreeUsePlacement = (typeof AGENT_FREE_USE_PLACEMENTS)[number]
    1028              : export type AgentFreeUseVariant = 'control' | AgentFreeUsePlacement
    1029              : export interface AgentFreeUseExposureMetadata extends Record<string, unknown> {
    1030              :   placement: AgentFreeUseVariant
    1031              :   '$feature/agent-free-use-message-placement': AgentFreeUseVariant
    1032              : }
    1033              : export type AgentCreditUsageVariant = 'control' | 'treatment'
    1034              : export interface AgentCreditUsageExposureMetadata extends Record<
    1035              :   string,
    1036              :   unknown
    1037              : > {
    1038              :   variant: AgentCreditUsageVariant
    1039              :   '$feature/agent-credit-usage-summary': AgentCreditUsageVariant
    1040              : }
    1041              : /**
    1042              :  * Interactions with the notice itself. This event adds what the existing
    1043              :  * outcome events cannot say: whether the notice was actually on screen in its
    1044              :  * assigned arm, and what the viewer did with it.
    1045              :  */
    1046              : export interface AgentFreeUseNoticeMetadata extends Record<string, unknown> {
    1047              :   action: 'shown' | 'dismissed' | 'learn_more_clicked'
    1048              :   placement: AgentFreeUsePlacement
    1049              : }
    1050              : export interface AgentCreditTransitionNoticeMetadata extends Record<
    1051              :   string,
    1052              :   unknown
    1053              : > {
    1054              :   action: 'shown' | 'dismissed'
    1055              : }
    1056              : export interface AgentStarterPromptClickedMetadata extends Record<
    1057              :   string,
    1058              :   unknown
    1059              : > {
    1060              :   prompt_id: AgentStarterPromptId
    1061              :   /** Slot position, so a reorder is visible rather than silently re-labelling. */
    1062              :   prompt_index: number
    1063              :   /** Size of the rendered set, so a set that grew or shrank is visible too. */
    1064              :   prompt_count: number
    1065              :   /**
    1066              :    * How many of that set the viewer could actually see. A panel narrower than
    1067              :    * 460px hides everything past the third chip with a container query, so this
    1068              :    * is 3 there and `prompt_count` elsewhere. Deliberately not folded into
    1069              :    * `prompt_count`: that field has to keep meaning "set size", and a reader
    1070              :    * cannot otherwise tell a shrunken set from a narrow panel.
    1071              :    */
    1072              :   visible_prompt_count: number
    1073              :   /**
    1074              :    * FNV-1a of the *displayed* text, 8 hex chars. Here so a copy change under a
    1075              :    * stable `prompt_id` is detectable — without it, a before/after read cannot
    1076              :    * tell a better slot from a rewritten one. Not the text itself (job `Don't`
    1077              :    * #3), and not reversible.
    1078              :    */
    1079              :   prompt_text_hash: string
    1080              :   /** The i18n locale that produced `prompt_text_hash`; two locales are two hashes of one prompt. */
    1081              :   locale: string
    1082              :   /**
    1083              :    * Minted per click. Carried onto every `app:agent_message_sent` attempt
    1084              :    * attributable to this click as `starter_prompt_click_id`. Retries mint a
    1085              :    * new `client_message_id` but retain this id, so click conversion must count
    1086              :    * distinct `starter_prompt_click_id` values rather than send events. A click
    1087              :    * with no matching send attempt never converted.
    1088              :    */
    1089              :   click_id: string
    1090              :   /**
    1091              :    * Whether the composer was empty when the chip was clicked. Inserting
    1092              :    * appends, so `false` means the submitted text is a mix of this prompt and
    1093              :    * something else — do not read those as a clean per-prompt outcome.
    1094              :    */
    1095              :   draft_was_empty: boolean
    1096              : }
    1097              : export interface AgentMessageSentMetadata extends Record<string, unknown> {
    1098              :   attachment_count: number
    1099              :   node_tag_count: number
    1100              :   /**
    1101              :    * The thread the message was posted into, `null` when it starts a new one —
    1102              :    * the backend mints that id in its acknowledgement, after this event fires.
    1103              :    */
    1104              :   thread_id: string | null
    1105              :   /** The targeted workflow's cloud id, `null` when the tab has none yet. */
    1106              :   workflow_id: string | null
    1107              :   /**
    1108              :    * Minted client-side, one per send attempt, so duplicate deliveries of this
    1109              :    * event collapse onto one message. A retry after a failed send is a new
    1110              :    * attempt and gets a new id.
    1111              :    *
    1112              :    * Also sent to the backend on the turn POST (`client_message_id`), which
    1113              :    * echoes it onto its own `agent_turn_started` event. That is what makes this
    1114              :    * the join key for the message → turn step: the backend's `turn_id` is minted
    1115              :    * after the POST arrives, so it can never appear on this event, and
    1116              :    * `thread_id` is `null` for the first message in a thread — precisely the
    1117              :    * sends that matter most to activation. An older server that ignores the field
    1118              :    * leaves the correlation unknown for that turn, which is a gap in the read and
    1119              :    * never a failed send.
    1120              :    */
    1121              :   client_message_id: string
    1122              :   input_method: AgentInputMethod
    1123              :   /**
    1124              :    * Which starter prompt supplied this draft, `null` when none did. The last
    1125              :    * chip clicked before the send wins, because inserting appends and the send
    1126              :    * is one message. Starter-prompt suggestions always carry a non-null ID and
    1127              :    * use `input_method: 'suggestion'`.
    1128              :    */
    1129              :   starter_prompt_id: AgentStarterPromptId | null
    1130              :   /** `click_id` of the `app:agent_starter_prompt_clicked` this send came from, `null` when typed. */
    1131              :   starter_prompt_click_id: string | null
    1132              : }
    1133              : export interface AgentNodeTaggedMetadata extends Record<string, unknown> {
    1134              :   source: 'mention_picker'
    1135              : }
    1136              : export interface AgentAttachButtonClickedMetadata extends Record<
    1137              :   string,
    1138              :   unknown
    1139              : > {
    1140              :   method: 'menu' | 'drag_drop' | 'paste'
    1141              : }
    1142              : export interface AgentWorkflowAppliedMetadata extends Record<string, unknown> {
    1143              :   workflow_id: string
    1144              :   target: 'active_tab_switch' | 'active_tab_open'
    1145              : }
    1146              : export type AgentGraphProjectionStage =
    1147              :   | 'received_no_graph'
    1148              :   | 'applied'
    1149              :   | 'applied_deferred'
    1150              :   | 'discarded'
    1151              :   | 'reverted'
    1152              : 
    1153              : /**
    1154              :  * Projection telemetry for agent and actorless frames and for reverted human
    1155              :  * batches. `op_id` is the join key; no actor, node, widget, workflow or prompt
    1156              :  * identifier is sent.
    1157              :  */
    1158              : export interface AgentGraphProjectionMetadata extends Record<string, unknown> {
    1159              :   /**
    1160              :    * First non-empty op id of the frame, or of the rejected batch on
    1161              :    * `reverted`. Not necessarily creator-owned: `reverted` carries the first
    1162              :    * rejected HUMAN op id. `null` when the frame carried no op ids.
    1163              :    */
    1164              :   op_id: string | null
    1165              :   /** How many non-empty op ids it carried; `op_id` is the first of them. */
    1166              :   op_count: number
    1167              :   sequence: number
    1168              :   /**
    1169              :    * - `received_no_graph` — delivered, nothing applied yet (no graph bound).
    1170              :    * - `applied` — this frame applied. If earlier no-graph frames were still
    1171              :    *   collected, the counts are the whole batch's, as on `applied_deferred`.
    1172              :    * - `applied_deferred` — a batch flush applied this earlier no-graph frame.
    1173              :    *   The counts are the WHOLE batch's and are repeated across its frames, so
    1174              :    *   they must not be attributed to this `op_id` alone.
    1175              :    * - `discarded` — the collected changes were thrown away without applying
    1176              :    *   (own-echo discard, `doc_reset`, `schema_error`, scope disposal, follower
    1177              :    *   replacement, rebind). All counts are zero: nothing reached the canvas, so
    1178              :    *   the size of what was dropped is deliberately not reported under a count a
    1179              :    *   dashboard would read as applied work.
    1180              :    * - `reverted` — the host rejected a human batch and the document state it
    1181              :    *   claimed was put back on the canvas. The counts are that revert's.
    1182              :    */
    1183              :   stage: AgentGraphProjectionStage
    1184              :   added_count: number
    1185              :   /**
    1186              :    * Newly reported document deletes. Excludes entries already reported on an
    1187              :    * earlier pending frame, and replace-mode `removeAbsent` removals.
    1188              :    */
    1189              :   removed_count: number
    1190              :   /**
    1191              :    * Apply steps that threw, plus reported degradations that did not throw
    1192              :    * (an unresolved link, a subgraph definition that failed to register).
    1193              :    */
    1194              :   apply_failure_count: number
    1195              : }
    1196              : export type AgentStopMethod = 'button' | 'escape'
    1197              : export interface AgentStopClickedMetadata extends Record<string, unknown> {
    1198              :   method: AgentStopMethod
    1199              :   turn_id: string
    1200              :   turn_elapsed_ms: number | null
    1201              : }
    1202              : export type AgentWorkflowBindSource =
    1203              :   | 'active_tab'
    1204              :   | 'selector_chip'
    1205              :   | 'minted'
    1206              :   | 'restored'
    1207              : export interface AgentWorkflowBoundMetadata extends Record<string, unknown> {
    1208              :   thread_id: string
    1209              :   workflow_id: string
    1210              :   prev_workflow_id: string | null
    1211              :   bind_source: AgentWorkflowBindSource
    1212              : }
    1213              : export interface AgentRunApprovalShownMetadata extends Record<string, unknown> {
    1214              :   turn_id: string
    1215              :   workflow_id: string | null
    1216              : }
    1217              : export type AgentRunApprovalDecision = 'run' | 'cancel' | 'open_workflow'
    1218              : export interface AgentRunApprovalResolvedMetadata extends Record<
    1219              :   string,
    1220              :   unknown
    1221              : > {
    1222              :   decision: AgentRunApprovalDecision
    1223              :   time_to_decide_ms: number
    1224              : }
    1225              : export interface AgentRunModeChangedMetadata extends Record<string, unknown> {
    1226              :   from: AgentRunMode['mode']
    1227              :   to: AgentRunMode['mode']
    1228              : }
    1229              : export type AgentThreadStartSource =
    1230              :   | 'new_chat_button'
    1231              :   | 'first_open'
    1232              :   | 'history_select'
    1233              :   | 'history_delete'
    1234              : export interface AgentThreadStartedMetadata extends Record<string, unknown> {
    1235              :   source: AgentThreadStartSource
    1236              : }
    1237              : 
    1238              : export type AgentErrorClass =
    1239              :   | 'request_failed'
    1240              :   | 'malformed_stream_event'
    1241              :   | 'cancel_failed'
    1242              :   | 'history_load_failed'
    1243              :   | 'ask_answer_failed'
    1244              :   | 'thread_list_load_failed'
    1245              :   | 'workflow_open_failed'
    1246              : 
    1247              : export type AgentRequestPath =
    1248              :   | '/agent/threads'
    1249              :   | '/agent/threads/{threadId}/messages'
    1250              :   | '/agent/threads/{threadId}/messages/{messageId}/cancel'
    1251              :   | '/agent/threads/{threadId}/asks/{askId}/answer'
    1252              :   | '/agent/run-mode'
    1253              :   | '/workflows'
    1254              :   | '/upload/image'
    1255              :   | '/other'
    1256              : 
    1257              : export type AgentRequestErrorName =
    1258              :   | 'AgentApiError'
    1259              :   | 'AgentResponseUnreadableError'
    1260              :   | 'ZodError'
    1261              :   | 'TimeoutError'
    1262              :   | 'AbortError'
    1263              :   | 'TypeError'
    1264              :   | 'other'
    1265              : 
    1266              : export interface AgentErrorMetadata extends Record<string, unknown> {
    1267              :   error_class: AgentErrorClass
    1268              :   failure_stage: 'pre_acceptance' | 'post_acceptance'
    1269              :   retryable: boolean
    1270              :   turn_accepted: boolean
    1271              :   /** `none` is a failure the user was never shown. */
    1272              :   ui_treatment: 'inline_notice' | 'error_overlay' | 'toast' | 'none'
    1273              :   /**
    1274              :    * FE-3200: which request failed, how, and with what status.
    1275              :    *
    1276              :    * Absent on the failure classes that are not a single REST request — a
    1277              :    * malformed stream event has no status, and a stage that pre-dates this
    1278              :    * carrier emits nothing rather than a placeholder, so an absent value in
    1279              :    * the data means "not instrumented here", never "no status".
    1280              :    *
    1281              :    * `request_path` is a route template from a closed set and `request_error`
    1282              :    * an error identity from a closed set, both defined in
    1283              :    * `services/agent/agentRequestFailure.ts`. Neither can carry a thread id,
    1284              :    * a workflow id, a message, or a user.
    1285              :    */
    1286              :   request_path?: AgentRequestPath
    1287              :   request_status?: number
    1288              :   request_error?: AgentRequestErrorName
    1289              : }
    1290              : 
    1291              : /**
    1292              :  * Widget (input/parameter) favorite toggle tracking metadata.
    1293              :  * Used to measure discoverability of the right side panel favoriting feature.
    1294              :  */
    1295              : export interface WidgetFavoriteToggledMetadata {
    1296              :   node_type: string
    1297              :   widget_name: string
    1298              :   widget_type: string
    1299              :   is_favorited: boolean
    1300              :   source: 'right_side_panel'
    1301              : }
    1302              : 
    1303              : /**
    1304              :  * Fired once per duplicate link dropped during workflow load, when the loser
    1305              :  * has a *different origin* from the survivor — i.e. a connection the file
    1306              :  * recorded is silently discarded, not merely a redundant same-origin copy.
    1307              :  * Cloud cannot see the accompanying `console.warn`, so this is the only
    1308              :  * signal that a load lost a link. The survivor follows an authoritative
    1309              :  * serialized reference: `input.link` for node inputs, `linkIds` priority
    1310              :  * order for subgraph boundaries, and document order otherwise. `target`
    1311              :  * names the contested input slot.
    1312              :  */
    1313              : export interface LinkDedupDropMetadata {
    1314              :   droppedLinkId: number
    1315              :   survivorLinkId: number
    1316              :   target: string
    1317              : }
    1318              : 
    1319              : /**
    1320              :  * Fired once per node when its `widgets_values_named` restore path
    1321              :  * disagrees with what the legacy positional `widgets_values` restore
    1322              :  * would have produced. Diagnostic only — never reflects an actual
    1323              :  * mis-restored widget value, since the legacy side is a shadow
    1324              :  * computation that's never applied when the flag is on.
    1325              :  */
    1326              : export interface NamedValuesShadowDiffMismatchMetadata {
    1327              :   node_type: string
    1328              :   pack_id?: string
    1329              :   mismatch_widget_count: number
    1330              :   checked_widget_count: number
    1331              :   had_named_field: boolean
    1332              :   has_on_serialize_hook: boolean
    1333              :   has_on_configure_hook: boolean
    1334              : }
    1335              : 
    1336              : /**
    1337              :  * Fired once per workflow load (sampled), aggregating the shadow-diff
    1338              :  * results across every node checked during that load.
    1339              :  */
    1340              : export interface NamedValuesShadowDiffSummaryMetadata {
    1341              :   total_nodes_checked: number
    1342              :   nodes_with_mismatch: number
    1343              :   distinct_node_types: string[]
    1344              :   distinct_pack_ids: string[]
    1345              : }
    1346              : 
    1347              : /**
    1348              :  * Help center opened metadata
    1349              :  */
    1350              : export interface HelpCenterOpenedMetadata {
    1351              :   source: 'menu' | 'topbar' | 'sidebar'
    1352              : }
    1353              : 
    1354              : /**
    1355              :  * Help resource clicked metadata
    1356              :  */
    1357              : export interface HelpResourceClickedMetadata {
    1358              :   resource_type:
    1359              :     | 'docs'
    1360              :     | 'discord'
    1361              :     | 'github'
    1362              :     | 'help_feedback'
    1363              :     | 'manager'
    1364              :     | 'release_notes'
    1365              :     | 'status'
    1366              :   is_external: boolean
    1367              :   source:
    1368              :     | 'menu'
    1369              :     | 'help_center'
    1370              :     | 'error_dialog'
    1371              :     | 'credits_panel'
    1372              :     | 'subscription'
    1373              : }
    1374              : 
    1375              : /**
    1376              :  * Help center closed metadata
    1377              :  */
    1378              : export interface HelpCenterClosedMetadata {
    1379              :   time_spent_seconds: number
    1380              : }
    1381              : 
    1382              : /**
    1383              :  * Workflow created metadata
    1384              :  */
    1385              : export interface WorkflowCreatedMetadata {
    1386              :   workflow_type: 'blank' | 'default'
    1387              :   previous_workflow_had_nodes: boolean
    1388              : }
    1389              : 
    1390              : /**
    1391              :  * Page view metadata for route tracking
    1392              :  */
    1393              : export interface PageViewMetadata {
    1394              :   path?: string
    1395              :   referrer?: string
    1396              :   title?: string
    1397              :   [key: string]: unknown
    1398              : }
    1399              : 
    1400              : export interface CheckoutAttributionMetadata {
    1401              :   ga_client_id?: string
    1402              :   ga_session_id?: string
    1403              :   ga_session_number?: string
    1404              :   im_ref?: string
    1405              :   rewardful_referral?: string
    1406              :   utm_source?: string
    1407              :   utm_medium?: string
    1408              :   utm_campaign?: string
    1409              :   utm_term?: string
    1410              :   utm_content?: string
    1411              :   gclid?: string
    1412              :   gbraid?: string
    1413              :   wbraid?: string
    1414              : }
    1415              : 
    1416              : export interface SubscriptionMetadata extends Partial<WorkspaceTelemetryContext> {
    1417              :   current_tier?: string
    1418              :   reason?: PaymentIntentSource
    1419              :   /** Server `error.type` when a refused run opened the paywall. */
    1420              :   refusal_type?: string
    1421              : }
    1422              : 
    1423              : export interface AddCreditsClickMetadata {
    1424              :   source:
    1425              :     | 'credits_panel'
    1426              :     | 'avatar_menu'
    1427              :     | 'settings_billing_panel'
    1428              :     | 'deep_link'
    1429              :     | 'agent_paywall'
    1430              : }
    1431              : 
    1432              : export type AgentPaywallReason =
    1433              :   | 'no_funds'
    1434              :   | 'subscription_inactive'
    1435              :   | 'member_cannot_pay'
    1436              :   | 'sales_managed'
    1437              :   | 'unknown'
    1438              : 
    1439              : /**
    1440              :  * Which moment put the paywall in front of the user. The two are not
    1441              :  * interchangeable and collapsing them made the funnel unreadable:
    1442              :  *
    1443              :  * - `refused_send` is reactive — a turn POST came back 402/`no_funds`, so the
    1444              :  *   user had to compose and send a message to discover they could not.
    1445              :  * - `credits_exhausted` is standing — the client already knows the workspace
    1446              :  *   has no funds and says so beside the composer, without a refusal first.
    1447              :  *
    1448              :  * Reported because `app:agent_paywall_shown` alone cannot tell a rise in
    1449              :  * impressions caused by the standing surface from one caused by more users
    1450              :  * being refused. Without the split, "the paywall is showing more" is
    1451              :  * ambiguous between the fix working and the product getting worse.
    1452              :  */
    1453              : export type AgentPaywallSurface = 'refused_send' | 'credits_exhausted'
    1454              : 
    1455              : export interface AgentPaywallShownMetadata {
    1456              :   reason: AgentPaywallReason
    1457              :   surface: AgentPaywallSurface
    1458              : }
    1459              : 
    1460              : export type AgentPaywallCta = 'subscribe' | 'add_credits' | 'upgrade'
    1461              : 
    1462              : export interface AgentPaywallCtaMetadata {
    1463              :   cta: AgentPaywallCta
    1464              :   /** The surface whose impression this click follows. */
    1465              :   surface: AgentPaywallSurface
    1466              : }
    1467              : 
    1468              : export interface SubscriptionCancellationMetadata {
    1469              :   current_tier?: string
    1470              :   cycle?: BillingCycle
    1471              :   /**
    1472              :    * `manage_subscription_button` opens the external billing portal, where
    1473              :    * cancellation is one of the few possible actions but not the only one —
    1474              :    * treat it as probable, not certain, cancel intent.
    1475              :    */
    1476              :   source?: 'cancel_plan_menu' | 'manage_subscription_button'
    1477              :   /** ISO date the subscription runs until if the cancel goes through. */
    1478              :   end_date?: string
    1479              :   /** Present only on the `failed` stage. */
    1480              :   error_message?: string
    1481              : }
    1482              : 
    1483              : export interface ResubscribeClickMetadata {
    1484              :   source: ResubscribeSource
    1485              :   /** Why the pricing dialog was opened, when the click came from one. */
    1486              :   payment_intent_source?: PaymentIntentSource
    1487              : }
    1488              : 
    1489              : export interface BeginCheckoutMetadata
    1490              :   extends Record<string, unknown>, CheckoutAttributionMetadata {
    1491              :   user_id: string
    1492              :   tier: SubscriptionCheckoutTier
    1493              :   cycle: BillingCycle
    1494              :   checkout_type: SubscriptionCheckoutType
    1495              :   checkout_attempt_id?: string
    1496              :   billing_op_id?: string
    1497              :   previous_tier?: TierKey
    1498              :   payment_intent_source?: PaymentIntentSource
    1499              : }
    1500              : 
    1501              : interface EcommerceItemMetadata {
    1502              :   item_name: string
    1503              :   item_category: string
    1504              :   item_variant?: string
    1505              :   price: number
    1506              :   quantity: number
    1507              : }
    1508              : 
    1509              : interface EcommerceMetadata {
    1510              :   currency: string
    1511              :   value: number
    1512              :   items: EcommerceItemMetadata[]
    1513              : }
    1514              : 
    1515              : export interface SubscriptionSuccessMetadata extends Record<string, unknown> {
    1516              :   user_id?: string
    1517              :   checkout_attempt_id?: string
    1518              :   tier?: SubscriptionCheckoutTier
    1519              :   cycle?: BillingCycle
    1520              :   checkout_type?: SubscriptionCheckoutType
    1521              :   previous_tier?: TierKey
    1522              :   payment_intent_source?: PaymentIntentSource
    1523              :   /** Present when the success is reported off the workspace billing-op poller. */
    1524              :   billing_op_id?: string
    1525              :   value?: number
    1526              :   currency?: string
    1527              :   ecommerce?: EcommerceMetadata
    1528              :   /**
    1529              :    * Set when the underlying checkout attempt was initiated from the resubscribe
    1530              :    * flow, so the pending-checkout recovery in `useSubscription.ts` can emit the
    1531              :    * canonical `billing.resubscribe.succeeded` terminal instead of leaving the
    1532              :    * legacy rail's `started`/`pending` resubscribe event unclosed forever.
    1533              :    */
    1534              :   operation?: 'resubscribe'
    1535              :   /** The click-time source, carried through so the terminal event can report it. */
    1536              :   resubscribe_source?: ResubscribeClickMetadata['source']
    1537              :   recovery_outcome?: 'late_success'
    1538              : }
    1539              : 
    1540              : export interface WorkspaceInviteMetadata extends Record<string, unknown> {
    1541              :   source: 'post_upgrade_success' | 'settings_members'
    1542              :   count: number
    1543              : }
    1544              : 
    1545              : export interface WorkspaceInviteFailedMetadata extends Record<string, unknown> {
    1546              :   source: WorkspaceInviteMetadata['source']
    1547              :   attempted_count: number
    1548              :   failed_count: number
    1549              : }
    1550              : 
    1551              : export interface FetchTimeoutMetadata {
    1552              :   route: string
    1553              :   method: string
    1554              :   timeout_ms: number
    1555              : }
    1556              : 
    1557              : /** How a request that got a retryable status (429/502/503/504) ended. */
    1558              : export type FetchStatusRetryOutcome =
    1559              :   | 'recovered'
    1560              :   | 'exhausted'
    1561              :   | 'retry_after_too_long'
    1562              :   | 'timeout_budget'
    1563              :   | 'failed'
    1564              : 
    1565              : /** One request that hit a retryable status in the shared status retry. */
    1566              : export interface FetchStatusRetryMetadata {
    1567              :   transport: 'fetch' | 'axios'
    1568              :   method: string
    1569              :   host: string
    1570              :   /** Route group only, as in `app:fetch_timeout`, e.g. `/billing/:resource`. */
    1571              :   route: string
    1572              :   /** Requests sent, including the first. */
    1573              :   attempts: number
    1574              :   /** The last status the request got, if any. */
    1575              :   final_status?: number
    1576              :   outcome: FetchStatusRetryOutcome
    1577              : }
    1578              : 
    1579              : /**
    1580              :  * Telemetry provider interface for individual providers.
    1581              :  * All methods are optional - providers only implement what they need.
    1582              :  */
    1583              : export interface TelemetryProvider {
    1584              :   trackFeatureFlagEvaluation?(key: string, value: unknown): void
    1585              : 
    1586              :   // Authentication flow events
    1587              :   trackSignupOpened?(): void
    1588              :   trackAuth?(metadata: AuthMetadata): void
    1589              :   trackAuthFailed?(metadata: AuthErrorMetadata): void
    1590              :   trackUnifiedAuthRetry?(metadata: UnifiedAuthRetryMetadata): void
    1591              :   trackUnifiedAuthRefresh?(metadata: UnifiedAuthRefreshMetadata): void
    1592              :   trackWebSessionEvent?(event: WebSessionTelemetryEvent): void
    1593              :   trackSsoEvent?(event: SsoTelemetryEvent): void
    1594              :   trackImageLoadFailed?(metadata: ImageLoadFailureMetadata): void
    1595              :   trackUserLoggedIn?(): void
    1596              :   trackBootstrapComplete?(metadata: BootstrapCompleteMetadata): void
    1597              : 
    1598              :   // Subscription flow events
    1599              :   trackSubscription?(
    1600              :     event: 'modal_opened' | 'subscribe_clicked',
    1601              :     metadata?: SubscriptionMetadata
    1602              :   ): void
    1603              :   trackBeginCheckout?(metadata: BeginCheckoutMetadata): void
    1604              :   trackMonthlySubscriptionSucceeded?(
    1605              :     metadata?: SubscriptionSuccessMetadata
    1606              :   ): void
    1607              :   trackMonthlySubscriptionCancelled?(): void
    1608              :   trackSubscriptionCancellation?(
    1609              :     event: 'flow_opened' | 'confirmed' | 'abandoned' | 'failed',
    1610              :     metadata?: SubscriptionCancellationMetadata
    1611              :   ): void
    1612              :   trackResubscribeClicked?(metadata: ResubscribeClickMetadata): void
    1613              :   trackAddApiCreditButtonClicked?(metadata?: AddCreditsClickMetadata): void
    1614              :   trackApiCreditTopupButtonPurchaseClicked?(amount: number): void
    1615              :   trackApiCreditTopupSucceeded?(): void
    1616              :   trackWorkspaceInviteSent?(metadata: WorkspaceInviteMetadata): void
    1617              :   trackWorkspaceInviteFailed?(metadata: WorkspaceInviteFailedMetadata): void
    1618              :   trackRunButton?(properties: RunButtonProperties): void
    1619              : 
    1620              :   trackBillingEvent?(event: BillingTelemetryEvent): void
    1621              : 
    1622              :   setWorkspaceContext?(context: WorkspaceTelemetryContext | undefined): void
    1623              :   trackWorkspaceScopeMismatch?(metadata: WorkspaceScopeMismatchMetadata): void
    1624              : 
    1625              :   /** Emit a checkout-journey lifecycle event to this provider. */
    1626              :   trackCheckoutJourneyEvent?(event: CheckoutJourneyTelemetryEvent): void
    1627              : 
    1628              :   trackAgentPaywallShown?(metadata: AgentPaywallShownMetadata): void
    1629              :   trackAgentPaywallCtaClicked?(metadata: AgentPaywallCtaMetadata): void
    1630              :   trackAgentCreditTransitionNotice?(
    1631              :     metadata: AgentCreditTransitionNoticeMetadata
    1632              :   ): void
    1633              : 
    1634              :   // Survey flow events
    1635              :   trackSurvey?(stage: 'opened' | 'submitted', responses?: SurveyResponses): void
    1636              :   trackInAppSurvey?(stage: InAppSurveyStage, event: InAppSurveyEvent): void
    1637              : 
    1638              :   // Onboarding coachmark tour events
    1639              :   trackOnboardingTour?(
    1640              :     stage: OnboardingTourStepStage,
    1641              :     metadata: OnboardingTourStepMetadata
    1642              :   ): void
    1643              :   trackOnboardingTour?(
    1644              :     stage: OnboardingTourNudgeStage,
    1645              :     metadata: OnboardingTourNudgeMetadata
    1646              :   ): void
    1647              : 
    1648              :   // Email verification events
    1649              :   trackEmailVerification?(stage: 'opened' | 'requested' | 'completed'): void
    1650              : 
    1651              :   // Template workflow events
    1652              :   trackTemplate?(metadata: TemplateMetadata): void
    1653              :   trackTemplateLibraryOpened?(metadata: TemplateLibraryMetadata): void
    1654              :   trackTemplateLibraryClosed?(metadata: TemplateLibraryClosedMetadata): void
    1655              : 
    1656              :   // Workflow management events
    1657              :   trackWorkflowImported?(metadata: WorkflowImportMetadata): void
    1658              :   trackWorkflowOpened?(metadata: WorkflowImportMetadata): void
    1659              :   trackWorkflowLinkOpened?(metadata: WorkflowLinkOpenedMetadata): void
    1660              :   trackWorkflowSaved?(metadata: WorkflowSavedMetadata): void
    1661              :   trackDefaultViewSet?(metadata: DefaultViewSetMetadata): void
    1662              :   trackEnterLinear?(metadata: EnterLinearMetadata): void
    1663              :   trackShareFlow?(metadata: ShareFlowMetadata): void
    1664              :   trackShareLinkOpened?(metadata: ShareLinkOpenedMetadata): void
    1665              : 
    1666              :   // Page visibility events
    1667              :   trackPageVisibilityChanged?(metadata: PageVisibilityMetadata): void
    1668              : 
    1669              :   // Tab tracking events
    1670              :   trackTabCount?(metadata: TabCountMetadata): void
    1671              : 
    1672              :   // Shell layout snapshot events
    1673              :   trackShellLayout?(metadata: ShellLayoutMetadata): void
    1674              : 
    1675              :   // Node search analytics events
    1676              :   trackNodeSearch?(metadata: NodeSearchMetadata): void
    1677              :   trackNodeSearchResultSelected?(metadata: NodeSearchResultMetadata): void
    1678              : 
    1679              :   // Search query analytics
    1680              :   trackSearchQuery?(metadata: SearchQueryMetadata): void
    1681              : 
    1682              :   // Node-added-to-canvas analytics
    1683              :   trackNodeAdded?(metadata: NodeAddedMetadata): void
    1684              : 
    1685              :   // Template filter tracking events
    1686              :   trackTemplateFilterChanged?(metadata: TemplateFilterMetadata): void
    1687              : 
    1688              :   // Help center events
    1689              :   trackHelpCenterOpened?(metadata: HelpCenterOpenedMetadata): void
    1690              :   trackHelpResourceClicked?(metadata: HelpResourceClickedMetadata): void
    1691              :   trackHelpCenterClosed?(metadata: HelpCenterClosedMetadata): void
    1692              : 
    1693              :   // Workflow creation events
    1694              :   trackWorkflowCreated?(metadata: WorkflowCreatedMetadata): void
    1695              : 
    1696              :   // Workflow execution events
    1697              :   trackWorkflowExecution?(): void
    1698              :   trackExecutionOutcome?(metadata: ExecutionOutcomeMetadata): void
    1699              :   trackExecutionError?(metadata: ExecutionErrorMetadata): void
    1700              :   trackExecutionSuccess?(metadata: ExecutionSuccessMetadata): void
    1701              :   trackSharedWorkflowRun?(metadata: SharedWorkflowRunMetadata): void
    1702              : 
    1703              :   // Settings events
    1704              :   trackSettingChanged?(metadata: SettingChangedMetadata): void
    1705              : 
    1706              :   // Generic UI button click events
    1707              :   trackUiButtonClicked?(metadata: UiButtonClickMetadata): void
    1708              : 
    1709              :   // In-App Agent message rating (PM-98)
    1710              :   trackAgentMessageFeedback?(metadata: AgentMessageFeedbackMetadata): void
    1711              :   trackAgentPanelOpened?(metadata: AgentPanelOpenedMetadata): void
    1712              :   trackAgentPanelClosed?(metadata: AgentPanelClosedMetadata): void
    1713              :   trackAgentPanelRenderStalled?(metadata: AgentPanelRenderStalledMetadata): void
    1714              :   trackAgentEntryButtonClicked?(metadata: AgentEntryButtonClickedMetadata): void
    1715              :   trackAgentCloseButtonClicked?(): void
    1716              :   trackAgentConsentShown?(metadata: AgentConsentShownMetadata): void
    1717              :   trackAgentConsentResolved?(metadata: AgentConsentResolvedMetadata): void
    1718              :   trackAgentOnboardingShown?(): void
    1719              :   trackAgentOnboardingStep?(metadata: AgentOnboardingStepMetadata): void
    1720              :   trackAgentMessageSent?(metadata: AgentMessageSentMetadata): void
    1721              :   trackAgentStarterPromptClicked?(
    1722              :     metadata: AgentStarterPromptClickedMetadata
    1723              :   ): void
    1724              :   trackAgentFreeUseNotice?(metadata: AgentFreeUseNoticeMetadata): void
    1725              :   trackAgentFreeUseExposure?(metadata: AgentFreeUseExposureMetadata): void
    1726              :   trackAgentCreditUsageExposure?(
    1727              :     metadata: AgentCreditUsageExposureMetadata
    1728              :   ): void
    1729              :   trackAgentNodeTagged?(metadata: AgentNodeTaggedMetadata): void
    1730              :   trackAgentAttachButtonClicked?(
    1731              :     metadata: AgentAttachButtonClickedMetadata
    1732              :   ): void
    1733              :   trackAgentWorkflowApplied?(metadata: AgentWorkflowAppliedMetadata): void
    1734              :   trackAgentGraphProjection?(metadata: AgentGraphProjectionMetadata): void
    1735              :   trackAgentError?(metadata: AgentErrorMetadata): void
    1736              :   trackAgentStopClicked?(metadata: AgentStopClickedMetadata): void
    1737              :   trackAgentWorkflowBound?(metadata: AgentWorkflowBoundMetadata): void
    1738              :   trackAgentRunApprovalShown?(metadata: AgentRunApprovalShownMetadata): void
    1739              :   trackAgentRunApprovalResolved?(
    1740              :     metadata: AgentRunApprovalResolvedMetadata
    1741              :   ): void
    1742              :   trackAgentRunModeChanged?(metadata: AgentRunModeChangedMetadata): void
    1743              :   trackAgentThreadStarted?(metadata: AgentThreadStartedMetadata): void
    1744              :   trackAgentConsentNotOffered?(metadata: AgentConsentNotOfferedMetadata): void
    1745              :   trackAgentConsentOfferExited?(metadata: AgentConsentOfferExitedMetadata): void
    1746              :   trackAgentOnboardingNotShown?(metadata: AgentOnboardingNotShownMetadata): void
    1747              :   trackAgentSendGated?(metadata: AgentSendGatedMetadata): void
    1748              : 
    1749              :   // Right side panel widget favorite events
    1750              :   trackWidgetFavoriteToggled?(metadata: WidgetFavoriteToggledMetadata): void
    1751              : 
    1752              :   // Named values shadow-diff diagnostics
    1753              :   trackNamedValuesShadowDiffMismatch?(
    1754              :     metadata: NamedValuesShadowDiffMismatchMetadata
    1755              :   ): void
    1756              :   trackNamedValuesShadowDiffSummary?(
    1757              :     metadata: NamedValuesShadowDiffSummaryMetadata
    1758              :   ): void
    1759              : 
    1760              :   // Link deduplication diagnostics
    1761              :   trackLinkDedupDrop?(metadata: LinkDedupDropMetadata): void
    1762              : 
    1763              :   // Page view tracking
    1764              :   trackPageView?(pageName: string, properties?: PageViewMetadata): void
    1765              : 
    1766              :   // Network error events
    1767              :   trackFetchTimeout?(metadata: FetchTimeoutMetadata): void
    1768              :   trackFetchStatusRetry?(metadata: FetchStatusRetryMetadata): void
    1769              : }
    1770              : 
    1771              : /**
    1772              :  * Telemetry dispatcher interface returned by useTelemetry().
    1773              :  * All methods are required - the registry implements all methods and dispatches
    1774              :  * to registered providers using optional chaining.
    1775              :  */
    1776              : export type TelemetryDispatcher = Required<TelemetryProvider>
    1777              : 
    1778              : /**
    1779              :  * Telemetry event constants
    1780              :  *
    1781              :  * Event naming conventions:
    1782              :  * - 'app:' prefix: UI/user interaction events
    1783              :  * - No prefix: Backend/system events (execution lifecycle)
    1784              :  */
    1785         2356 : export const TelemetryEvents = {
    1786              :   // Authentication Flow
    1787              :   USER_SIGN_UP_OPENED: AUTH_TELEMETRY_EVENT.signUpOpened,
    1788              :   USER_AUTH_COMPLETED: AUTH_TELEMETRY_EVENT.authCompleted,
    1789              :   USER_AUTH_FAILED: AUTH_TELEMETRY_EVENT.authFailed,
    1790              :   USER_LOGGED_IN: 'app:user_logged_in',
    1791              :   UNIFIED_AUTH_RETRY_SUCCEEDED: 'auth.unified.request_retry.succeeded',
    1792              :   UNIFIED_AUTH_RETRY_FAILED: 'auth.unified.request_retry.failed',
    1793              :   UNIFIED_AUTH_REFRESH_SUCCEEDED: SESSION_TELEMETRY_EVENT.refreshSucceeded,
    1794              :   UNIFIED_AUTH_REFRESH_FAILED: SESSION_TELEMETRY_EVENT.refreshFailed,
    1795              :   SSO_REQUIRED_SHOWN: SSO_TELEMETRY_EVENT.requiredShown,
    1796              :   SSO_CONTINUE_CLICKED: SSO_TELEMETRY_EVENT.continueClicked,
    1797              :   SSO_SIGN_IN_FAILED: SSO_TELEMETRY_EVENT.signInFailed,
    1798              :   SSO_SIGN_IN_COMPLETED: SSO_TELEMETRY_EVENT.signInCompleted,
    1799              :   SSO_WORKSPACE_LANDED: SSO_TELEMETRY_EVENT.workspaceLanded,
    1800              :   IMAGE_LOAD_FAILED: 'app:image_load_failed',
    1801              :   BOOTSTRAP_COMPLETE: 'app:bootstrap_complete',
    1802              :   THEME_LOADED: 'app:theme_loaded',
    1803              : 
    1804              :   // Subscription Flow
    1805              :   RUN_BUTTON_CLICKED: 'app:run_button_click',
    1806              :   SUBSCRIPTION_REQUIRED_MODAL_OPENED: 'app:subscription_required_modal_opened',
    1807              :   SUBSCRIBE_NOW_BUTTON_CLICKED: 'app:subscribe_now_button_clicked',
    1808              :   MONTHLY_SUBSCRIPTION_SUCCEEDED: 'app:monthly_subscription_succeeded',
    1809              :   MONTHLY_SUBSCRIPTION_CANCELLED: 'app:monthly_subscription_cancelled',
    1810              :   SUBSCRIPTION_CANCEL_FLOW_OPENED: 'app:subscription_cancel_flow_opened',
    1811              :   SUBSCRIPTION_CANCEL_CONFIRMED: 'app:subscription_cancel_confirmed',
    1812              :   SUBSCRIPTION_CANCEL_ABANDONED: 'app:subscription_cancel_abandoned',
    1813              :   SUBSCRIPTION_CANCEL_FAILED: 'app:subscription_cancel_failed',
    1814              :   RESUBSCRIBE_BUTTON_CLICKED: 'app:resubscribe_button_clicked',
    1815              :   ADD_API_CREDIT_BUTTON_CLICKED: 'app:add_api_credit_button_clicked',
    1816              :   API_CREDIT_TOPUP_BUTTON_PURCHASE_CLICKED:
    1817              :     'app:api_credit_topup_button_purchase_clicked',
    1818              :   API_CREDIT_TOPUP_SUCCEEDED: 'app:api_credit_topup_succeeded',
    1819              :   WORKSPACE_INVITE_SENT: 'app:workspace_invite_sent',
    1820              :   WORKSPACE_INVITE_FAILED: 'app:workspace_invite_failed',
    1821              :   BEGIN_CHECKOUT: 'begin_checkout',
    1822              : 
    1823              :   AGENT_PAYWALL_SHOWN: 'app:agent_paywall_shown',
    1824              :   AGENT_PAYWALL_CTA_CLICKED: 'app:agent_paywall_cta_clicked',
    1825              : 
    1826              :   // Canonical Billing Lifecycle
    1827              :   ...BILLING_TELEMETRY_EVENTS,
    1828              : 
    1829              :   // Onboarding Survey
    1830              :   USER_SURVEY_OPENED: 'app:user_survey_opened',
    1831              :   USER_SURVEY_SUBMITTED: 'app:user_survey_submitted',
    1832              : 
    1833              :   // PostHog API surveys rendered by the app
    1834              :   IN_APP_SURVEY_SHOWN: 'survey shown',
    1835              :   IN_APP_SURVEY_SENT: 'survey sent',
    1836              :   IN_APP_SURVEY_DISMISSED: 'survey dismissed',
    1837              : 
    1838              :   // Onboarding Coachmarks
    1839              :   ONBOARDING_TOUR_NOT_STARTED: 'app:onboarding_tour_not_started',
    1840              :   ONBOARDING_TOUR_STARTED: 'app:onboarding_tour_started',
    1841              :   ONBOARDING_TOUR_STEP_SHOWN: 'app:onboarding_tour_step_shown',
    1842              :   ONBOARDING_TOUR_COMPLETED: 'app:onboarding_tour_completed',
    1843              :   ONBOARDING_TOUR_SKIPPED: 'app:onboarding_tour_skipped',
    1844              :   ONBOARDING_TOUR_NUDGE_SHOWN: 'app:onboarding_tour_nudge_shown',
    1845              :   ONBOARDING_TOUR_EXPLORE_TEMPLATES_CLICKED:
    1846              :     'app:onboarding_tour_explore_templates_clicked',
    1847              : 
    1848              :   // Email Verification
    1849              :   USER_EMAIL_VERIFY_OPENED: 'app:user_email_verify_opened',
    1850              :   USER_EMAIL_VERIFY_REQUESTED: 'app:user_email_verify_requested',
    1851              :   USER_EMAIL_VERIFY_COMPLETED: 'app:user_email_verify_completed',
    1852              : 
    1853              :   // Template Tracking
    1854              :   TEMPLATE_WORKFLOW_OPENED: 'app:template_workflow_opened',
    1855              :   TEMPLATE_LIBRARY_OPENED: 'app:template_library_opened',
    1856              :   TEMPLATE_LIBRARY_CLOSED: 'app:template_library_closed',
    1857              : 
    1858              :   // Workflow Management
    1859              :   WORKFLOW_IMPORTED: 'app:workflow_imported',
    1860              :   WORKFLOW_OPENED: 'app:workflow_opened',
    1861              :   WORKFLOW_LINK_OPENED: 'app:workflow_link_opened',
    1862              :   ENTER_LINEAR_MODE: 'app:app_mode_opened',
    1863              :   SHARE_FLOW: 'app:share_flow',
    1864              :   SHARE_LINK_OPENED: 'app:share_link_opened',
    1865              : 
    1866              :   // Page Visibility
    1867              :   PAGE_VISIBILITY_CHANGED: 'app:page_visibility_changed',
    1868              : 
    1869              :   // Tab Tracking
    1870              :   TAB_COUNT_TRACKING: 'app:tab_count_tracking',
    1871              : 
    1872              :   // Shell Layout
    1873              :   SHELL_LAYOUT: 'app:shell_layout',
    1874              : 
    1875              :   // Node Search Analytics
    1876              :   NODE_SEARCH: 'app:node_search',
    1877              :   NODE_SEARCH_RESULT_SELECTED: 'app:node_search_result_selected',
    1878              :   SEARCH_QUERY: 'app:search_query',
    1879              :   NODE_ADDED: 'app:node_added_to_workflow',
    1880              : 
    1881              :   // Template Filter Analytics
    1882              :   TEMPLATE_FILTER_CHANGED: 'app:template_filter_changed',
    1883              : 
    1884              :   // Settings
    1885              :   SETTING_CHANGED: 'app:setting_changed',
    1886              : 
    1887              :   // Help Center Analytics
    1888              :   HELP_CENTER_OPENED: 'app:help_center_opened',
    1889              :   HELP_RESOURCE_CLICKED: 'app:help_resource_clicked',
    1890              :   HELP_CENTER_CLOSED: 'app:help_center_closed',
    1891              : 
    1892              :   // Workflow Creation
    1893              :   WORKFLOW_CREATED: 'app:workflow_created',
    1894              :   WORKFLOW_SAVED: 'app:workflow_saved',
    1895              :   DEFAULT_VIEW_SET: 'app:default_view_set',
    1896              : 
    1897              :   // Execution Lifecycle
    1898              :   EXECUTION_START: 'execution_start',
    1899              :   EXECUTION_ERROR: 'execution_error',
    1900              :   EXECUTION_SUCCESS: 'execution_success',
    1901              :   SHARED_WORKFLOW_RUN: 'app:shared_workflow_run',
    1902              :   // Generic UI Button Click
    1903              :   UI_BUTTON_CLICKED: 'app:ui_button_clicked',
    1904              : 
    1905              :   // In-App Agent
    1906              :   AGENT_MESSAGE_FEEDBACK: 'app:agent_message_feedback',
    1907              :   AGENT_PANEL_OPENED: 'app:agent_panel_opened',
    1908              :   AGENT_PANEL_CLOSED: 'app:agent_panel_closed',
    1909              :   AGENT_PANEL_RENDER_STALLED: 'app:agent_panel_render_stalled',
    1910              :   AGENT_ENTRY_BUTTON_CLICKED: 'app:agent_entry_button_clicked',
    1911              :   AGENT_CLOSE_BUTTON_CLICKED: 'app:agent_close_button_clicked',
    1912              :   AGENT_CONSENT_SHOWN: 'app:agent_consent_shown',
    1913              :   AGENT_CONSENT_RESOLVED: 'app:agent_consent_resolved',
    1914              :   AGENT_ONBOARDING_SHOWN: 'app:agent_onboarding_shown',
    1915              :   AGENT_ONBOARDING_STEP: 'app:agent_onboarding_step',
    1916              :   AGENT_MESSAGE_SENT: 'app:agent_message_sent',
    1917              :   AGENT_STARTER_PROMPT_CLICKED: 'app:agent_starter_prompt_clicked',
    1918              :   AGENT_FREE_USE_NOTICE: 'app:agent_free_use_notice',
    1919              :   AGENT_FREE_USE_EXPOSURE: 'app:agent_free_use_exposure',
    1920              :   AGENT_CREDIT_USAGE_EXPOSURE: 'app:agent_credit_usage_exposure',
    1921              :   AGENT_CREDIT_TRANSITION_NOTICE: 'app:agent_credit_transition_notice',
    1922              :   AGENT_NODE_TAGGED: 'app:agent_node_tagged',
    1923              :   AGENT_ATTACH_BUTTON_CLICKED: 'app:agent_attach_button_clicked',
    1924              :   AGENT_WORKFLOW_APPLIED: 'app:agent_workflow_applied',
    1925              :   AGENT_GRAPH_PROJECTION: 'app:agent_graph_projection',
    1926              :   AGENT_ERROR: 'app:agent_error',
    1927              :   AGENT_STOP_CLICKED: 'app:agent_stop_clicked',
    1928              :   AGENT_WORKFLOW_BOUND: 'app:agent_workflow_bound',
    1929              :   AGENT_RUN_APPROVAL_SHOWN: 'app:agent_run_approval_shown',
    1930              :   AGENT_RUN_APPROVAL_RESOLVED: 'app:agent_run_approval_resolved',
    1931              :   AGENT_RUN_MODE_CHANGED: 'app:agent_run_mode_changed',
    1932              :   AGENT_THREAD_STARTED: 'app:agent_thread_started',
    1933              :   AGENT_CONSENT_NOT_OFFERED: 'app:agent_consent_not_offered',
    1934              :   AGENT_CONSENT_OFFER_EXITED: 'app:agent_consent_offer_exited',
    1935              :   AGENT_ONBOARDING_NOT_SHOWN: 'app:agent_onboarding_not_shown',
    1936              :   AGENT_SEND_GATED: 'app:agent_send_gated',
    1937              : 
    1938              :   // Right Side Panel Widget Favorites
    1939              :   WIDGET_FAVORITE_TOGGLED: 'app:widget_favorite_toggled',
    1940              : 
    1941              :   // Named Values Shadow Diff (Comfy.Workflow.NamedValuesRestore diagnostics)
    1942              :   NAMED_VALUES_SHADOW_DIFF_MISMATCH: 'app:named_values_shadow_diff_mismatch',
    1943              :   NAMED_VALUES_SHADOW_DIFF_SUMMARY: 'app:named_values_shadow_diff_summary',
    1944              : 
    1945              :   // Link deduplication diagnostics
    1946              :   LINK_DEDUP_DROP: 'app:link_dedup_drop',
    1947              : 
    1948              :   // Page View
    1949              :   PAGE_VIEW: 'app:page_view',
    1950              : 
    1951              :   // Network
    1952              :   FETCH_TIMEOUT: 'app:fetch_timeout',
    1953              :   FETCH_STATUS_RETRY: 'app:fetch_status_retry',
    1954              : 
    1955              :   WORKSPACE_SCOPE_MISMATCH: 'workspace_scope_mismatch'
    1956              : } as const
    1957              : 
    1958              : export type TelemetryEventName =
    1959              :   | (typeof TelemetryEvents)[keyof typeof TelemetryEvents]
    1960              :   | BillingTelemetryEventName
    1961              :   | CheckoutJourneyTelemetryEventName
    1962              :   | WebSessionTelemetryEvent['name']
    1963              : 
    1964              : export const OnboardingTourEvents: Record<
    1965              :   OnboardingTourStage,
    1966              :   TelemetryEventName
    1967              : > = {
    1968         2356 :   not_started: TelemetryEvents.ONBOARDING_TOUR_NOT_STARTED,
    1969              :   started: TelemetryEvents.ONBOARDING_TOUR_STARTED,
    1970              :   step_shown: TelemetryEvents.ONBOARDING_TOUR_STEP_SHOWN,
    1971              :   completed: TelemetryEvents.ONBOARDING_TOUR_COMPLETED,
    1972              :   skipped: TelemetryEvents.ONBOARDING_TOUR_SKIPPED,
    1973              :   nudge_shown: TelemetryEvents.ONBOARDING_TOUR_NUDGE_SHOWN,
    1974              :   explore_templates_clicked:
    1975              :     TelemetryEvents.ONBOARDING_TOUR_EXPLORE_TEMPLATES_CLICKED
    1976              : }
    1977              : 
    1978         2356 : export const CANCELLATION_STAGE_EVENTS = {
    1979              :   flow_opened: TelemetryEvents.SUBSCRIPTION_CANCEL_FLOW_OPENED,
    1980              :   confirmed: TelemetryEvents.SUBSCRIPTION_CANCEL_CONFIRMED,
    1981              :   abandoned: TelemetryEvents.SUBSCRIPTION_CANCEL_ABANDONED,
    1982              :   failed: TelemetryEvents.SUBSCRIPTION_CANCEL_FAILED
    1983              : } as const
    1984              : 
    1985         2356 : const executionTriggerSources = [
    1986              :   'button',
    1987              :   'keybinding',
    1988              :   'legacy_ui',
    1989              :   'unknown',
    1990              :   'linear',
    1991              :   'auto_queue'
    1992              : ] as const
    1993              : 
    1994              : export type ExecutionTriggerSource = (typeof executionTriggerSources)[number]
    1995              : 
    1996          193 : export function normalizeExecutionTriggerSource(
    1997              :   value: unknown
    1998              : ): ExecutionTriggerSource {
    1999          193 :   return (
    2000              :     executionTriggerSources.find((triggerSource) => triggerSource === value) ??
    2001              :     'unknown'
    2002              :   )
    2003              : }
    2004              : 
    2005              : /**
    2006              :  * Union type for all possible telemetry event properties
    2007              :  */
    2008              : export type TelemetryEventProperties =
    2009              :   | AuthMetadata
    2010              :   | OnboardingTourMetadata
    2011              :   | AuthErrorMetadata
    2012              :   | UnifiedAuthRetryMetadata
    2013              :   | UnifiedAuthRefreshMetadata
    2014              :   | WebSessionTelemetryEvent['properties']
    2015              :   | SsoTelemetryEvent['properties']
    2016              :   | ImageLoadFailureMetadata
    2017              :   | BootstrapCompleteMetadata
    2018              :   | SurveyResponses
    2019              :   | TemplateMetadata
    2020              :   | ExecutionContext
    2021              :   | RunButtonProperties
    2022              :   | ExecutionErrorMetadata
    2023              :   | ExecutionSuccessMetadata
    2024              :   | SharedWorkflowRunMetadata
    2025              :   | CreditTopupMetadata
    2026              :   | WorkflowImportMetadata
    2027              :   | TemplateLibraryMetadata
    2028              :   | TemplateLibraryClosedMetadata
    2029              :   | PageVisibilityMetadata
    2030              :   | TabCountMetadata
    2031              :   | ShellLayoutMetadata
    2032              :   | NodeSearchMetadata
    2033              :   | NodeSearchResultMetadata
    2034              :   | SearchQueryMetadata
    2035              :   | TemplateFilterMetadata
    2036              :   | SettingChangedMetadata
    2037              :   | UiButtonClickMetadata
    2038              :   | WidgetFavoriteToggledMetadata
    2039              :   | NamedValuesShadowDiffMismatchMetadata
    2040              :   | NamedValuesShadowDiffSummaryMetadata
    2041              :   | LinkDedupDropMetadata
    2042              :   | HelpCenterOpenedMetadata
    2043              :   | HelpResourceClickedMetadata
    2044              :   | HelpCenterClosedMetadata
    2045              :   | WorkflowCreatedMetadata
    2046              :   | EnterLinearMetadata
    2047              :   | ShareFlowMetadata
    2048              :   | ShareLinkOpenedMetadata
    2049              :   | WorkflowLinkOpenedMetadata
    2050              :   | WorkflowSavedMetadata
    2051              :   | DefaultViewSetMetadata
    2052              :   | SubscriptionMetadata
    2053              :   | SubscriptionSuccessMetadata
    2054              :   | WorkspaceInviteFailedMetadata
    2055              :   | BillingTelemetryEvent
    2056              :   | CheckoutJourneyTelemetryEventPayload
    2057              :   | AgentPaywallShownMetadata
    2058              :   | AgentPaywallCtaMetadata
    2059              :   | AgentCreditTransitionNoticeMetadata
    2060              :   | FetchTimeoutMetadata
    2061              :   | FetchStatusRetryMetadata
    2062              :   | WorkspaceScopeMismatchMetadata
        

Generated by: LCOV version 2.0-1