## Why we need this The Duo CLI now runs Duo Developer interactively. That means the same flow is reached from two very different places: a person typing in a terminal, and GitLab running the flow on its own for a merge request or an issue. In our analytics these two are the same thing. Every session is labelled `developer/v1`, so any number we report for Duo Developer silently mixes both. That has practical consequences: - We cannot say how much the CLI is actually used, which is the first question anyone asks about a new surface. - We cannot report on remote Duo Developer without CLI traffic distorting the trend, and CLI adoption is expected to grow. - The DAP adoption dashboards that leadership reads ask exactly this question — "how is usage trending across surfaces: web, IDE, CLI" (see [&21281](https://gitlab.com/groups/gitlab-org/-/epics/21281)) — and today we cannot answer it. We are not looking for anything elaborate. We want to count sessions per surface, and we want it visible in the existing dashboards rather than in a hand-written query. ## What we can and cannot see today Sessions do carry an environment, but it only separates local from remote: both the CLI and the IDE extensions report `ide`. Nothing says which of the two it was. We do run a different flow configuration in the CLI (`2.0.0-interactive` instead of `2.0.0`), and we store that on the session record in `duo_workflows_workflows.flow_metadata_json`. But it never reaches an analytics event, and the column is not replicated to Snowflake, so today it is only visible in the production database. ## Proposal: reuse `source` In 19.3 we added a `source` property to the [`agent_platform_session_created`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/events/agent_platform_session_created.yml) event ([#605256](https://gitlab.com/gitlab-org/gitlab/-/work_items/605256)). It exists for exactly this kind of problem: several features run on the Duo Developer flow, and `source` records which entry point started the session. Values such as `merge_request_code_conflict` are already in use. The session id travels on the same event, so a source can be joined to that session's usage in the warehouse. An interactive CLI session is simply another entry point. So instead of inventing a mechanism, we add a value to the existing one. Note that this does not affect CI runs of Duo Developer. Those sessions are created by GitLab, not by the CLI, and already carry their own source values. ## What needs to happen **1. Agree the value.** One value for the CLI, or two so that interactive and scripted (`duo flow run`) runs are separate? Worth a short conversation with @jpcyiza, who built the `source` mechanism, before writing code. The list of allowed values is deliberately closed (see [#591519](https://gitlab.com/gitlab-org/gitlab/-/work_items/591519)), so this is a deliberate vocabulary decision rather than a free-text field. **2. GitLab: accept the value.** Add it to `WORKFLOW_ACTIONS_SOURCE` in [`ee/lib/api/ai/duo_workflows/workflows.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/ai/duo_workflows/workflows.rb) and describe it in the event definition. `CreateWorkflowService` already passes `source` through to the event, so nothing else changes. **3. Duo CLI: send the value.** Add `source` to the request that creates a session (`packages/lib_workflow_executor/src/api/workflow_rails_service.ts` in `gitlab-org/gitlab-lsp`). One thing to be careful about: the API validates `source` against the allowed list, so a value an instance does not recognise returns 400 and the session fails to start. The CLI must therefore only send the value to instances new enough to know it, the way it already gates other newer fields with `ifVersionGte`. Worth deciding here as well: that code path is shared with the IDE extensions. If they send their own value, we get the IDE-versus-CLI split at the same time, at almost no extra cost. Needs a word with editor extensions. **4. Data: make it visible.** This is the part that is genuinely missing. `source` is not extracted in our dbt models (`prep_snowplow_unnested_events_all.sql` in `gitlab-data/analytics` pulls out `agent_name`, `workflow_type`, `workflow_id`, token fields and `request_id`, but not `source`). So the attribution from #605256 currently lives only inside a raw JSON blob in Snowflake — queryable by hand, invisible in Tableau. The field needs to be surfaced properly before any of this shows up on a dashboard. Since #605256 needs the same change, it makes sense to raise it once for both. ## Known limits, stated up front - Self-managed and Dedicated customers can switch off event-level data, so coverage will be incomplete. This was raised at the end of #605256 and never fully settled; the same limitation applies here. - CLI versions older than the release that adds this send nothing, so early data will have a tail of unattributed sessions. - `source` tells us where a session came from, not which flow configuration ran. That is good enough for the question in this issue; see below for the rest. ## Not in this issue **Billing.** The CLI will likely become its own billable feature, which needs a change in CustomersDot and product decisions about naming, unit and timing. To be tracked separately. For context and reassurance: the interactive CLI and the older chat-based CLI are charged the same way, one request per turn or approval pause. The only thing that moved is which bucket the usage lands in, from `chat` to `developer`. Nothing is charged twice and nothing became free. CLI usage sitting inside the Duo Developer numbers is acceptable for now — this issue is what makes it possible to take it back out. **Flow versions in events.** Recording which flow configuration ran (`2.0.0-interactive` versus `2.0.0`) is a second, complementary dimension. The cleanest place to emit it is the Duo Workflow Service, which already knows the resolved version and already attaches an AI context to its events. That overlaps with [#580010](https://gitlab.com/gitlab-org/gitlab/-/work_items/580010), so it belongs there rather than here. **Renaming or splitting `workflow_definition`** ([#599841](https://gitlab.com/gitlab-org/gitlab/-/work_items/599841)). Nothing here conflicts with that work. ## Done when - We can report Duo Developer sessions split by surface for a chosen period. - The DAP adoption dashboard can show or exclude CLI sessions. - The event definition documents the new value and the internal-events checks pass. ## Related - [&21281](https://gitlab.com/groups/gitlab-org/-/epics/21281) — DAP usage visibility, which asks the surface question - [#605256](https://gitlab.com/gitlab-org/gitlab/-/work_items/605256) — where `source` came from - [#580010](https://gitlab.com/gitlab-org/gitlab/-/work_items/580010) — flow version and agent-level properties, the natural home for the follow-up - [#599841](https://gitlab.com/gitlab-org/gitlab/-/work_items/599841) — untangling `workflow_definition`