Store the resolved flow config id and version on a Duo Agent Platform session and send them on every resume

Why

Rails re-resolves workflowDefinition on every request today. When engine_owned_chat_environment (!250286 (closed)) flips, a chat session that started on legacy chat.Workflow would resume on the new chat engine, classify as a new turn, and read its history under the wrong key. The gateway guards against that with a user-facing error to start a new chat, but the clean fix is a pin: Rails stores the resolved config_id and version at session creation and sends them on every resume, so a session in flight finishes on the engine it started on.

Today

FoundationalChatAgent stores reference and version; plain chat stores the bare string chat. The token already carries a flow_config_id claim (contract.proto:341, server.py:433-438). Candidate homes: a column or flow_metadata_json, sent through the claim or the start request.

Scope

  • Persist the resolved id and version at creation.
  • Send them on every resume. The gateway routes by the pin; that half is part of the cutover item under Phase 3.
  • Whether old threads become read-only after the cutover or get a converter is product's call.

Precondition for the cutover in !250286 (closed). Design: chat_engine.md, Sessions in flight. Tracked under &19647, Phase 3 (&23674).

Owner: thomas-schmidt (group::agent developer), agreed with the chat engine owners in ADR-001: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7419 (merged). First user: continued Duo Developer sessions (gitlab-org#24022).

Plan (Rails half)

  • Reuse what is stored. The gateway already reports the resolved flow identity with the first checkpoint (ResolvedFlow.tracking_fields: flow_id, schema_version, flow_version), and Rails stores it once in flow_metadata_json (create_checkpoint_service.rb). GraphQL exposes it as flowMetadataVersion, and the Duo CLI already resumes from it. One reader on the model (for example Workflow#pinned_flow_params) turns it into start params. A column only if more logic needs it.
  • Every resume uses the pin. Runtimes::Ci mints the workflow token and sets DUO_WORKFLOW_FLOW_VERSION (and the schema) from the pin, not from FoundationalFlowStartParamsResolver. The Workhorse path sends it with the start request. Today a CI resume re-resolves the version for the token (runtimes/ci.rb) but keeps the previous job's version variable (resume_workflow_service.rb); since the token is bound to the version (!260255 (merged)), a flag change between two turns likely makes the resume fail.
  • Fallback: a session without a recorded identity (created before the first checkpoint, or before flow_metadata_json existed) resolves as today.
  • Custom catalog flows keep their item version (custom_flow_config_params), unchanged.

The gateway half (routing chat sessions by the pin at the engine cutover) stays with the cutover item.

Done when

  • A session started on developer/4.0.0 resumes on 4.0.0 after a newer 4.x is listed, and after the flag that selected it turns off.
  • The token and the CI variables of a resume always name the same version (spec).
Edited by 🤖 GitLab Bot 🤖