Run catalog flow starts and resumes through ExecuteRunService

What does this MR do and why?

The problem. GitLab Duo can run a flow in two places: in a CI job, or directly through Workhorse with no CI job and no repository checkout. Several features start flows, and most of them still do their own CI setup instead of using the shared entry point (Ai::DuoWorkflows::ExecuteRunService) that picks the runtime and does the setup once. One of them is Ai::Catalog::ExecuteWorkflowService. It starts:

  • custom flows from the AI Catalog when you mention or assign them
  • @GitLabDuo questions on merge requests
  • catalog sessions resumed through the REST API

This causes two problems:

  1. Every change has to be made twice. A new runtime, or a change to tokens or identity, has to go into this service and into the shared entry point.
  2. Sessions can't stay on Workhorse. Flows that don't need a repository (coding_environment: none, for example Recommend Reviewers or workplan) are moving to Workhorse to skip the clone and the custom-image problems in #635674. This service can start them there, but resumes them in a CI job.

The fix. ExecuteWorkflowService now hands every start and resume to the shared entry point. It still validates the request and creates the session. The entry point picks the runtime from the flow, and a resume continues on the runtime the session started on.

What users see. Mentions, triggers, @GitLabDuo and API resumes work as before. What this enables: once a catalog flow runs on Workhorse, resuming it keeps it on Workhorse. A few edge cases change, for example the wording of token errors; they're listed in the details below.

This is step 2 of #629005, which moves every way of starting a Duo flow onto one entry point.

Decisions worth a look

  • Adding the flow's service account to the project. Enabling a flow already adds its service account to the project. Some callers also re-add it on every run, others don't. This MR keeps that behaviour exactly as it is: the runtime adds the account only when the caller asks (provision_membership: true). As a result, a trigger or API resume never re-adds an account that a maintainer removed. Deciding this from the session instead of per caller is a follow-up.
  • Turning a user's answer into a resume event (RunEvent.for_resume). It decides by the kind of pause, not by the runtime. A flow's question routes on the decision (approve, reject, or reject with a message, which is the reply), so it gets the decision on both runtimes. Only a chat agent waiting for its next message gets the reply as input. It replaces the mapping in ExecuteWorkflowService and in the REST route's Workhorse branch. The route's CI chat branch (foundational_resume_decision) keeps its own mapping until it moves too.
Details for reviewers and review agents

What changes, by class

  • Ai::Catalog::ExecuteWorkflowService:
    • no longer mints tokens or picks StartWorkflowService / ResumeWorkflowService
    • calls ExecuteRunService with the caller's runtime override as given, so an override it doesn't know fails with runtime_unknown. For its own "Allow flow execution" check it resolves the runtime with the same rule (ExecuteRunService.runtime_for_session)
    • the separate Workhorse branch from !265182 (merged) (workhorse_run? / start_workhorse_run) is gone
    • checks "Allow flow execution" (execute_duo_workflow_in_ci) for every Workhorse start and resume; on CI, StartWorkflowService / ResumeWorkflowService check it as before
    • a failed start returns its workflow, so the messaging adapter can claim the delivery and the stuck-session cleanup doesn't report the failure a second time
  • Runtimes::Ci:
    • reads the flow from the session (!263585 (merged)); there are no per-run flow config parameters
    • passes trigger_source
    • takes provision_membership: (default false)
  • provision_membership: true is passed by the callers that re-added membership before: the messaging adapter (through ExecuteWorkflowService), CreateAndStartWorkflowService and ResolveToolApprovalService.
  • Adapters::Base#trigger no longer provisions. Its Workhorse pre-check uses ExecuteRunService.supports?, the single runtime/coding-environment matrix.
  • RunEvent.for_resume is used by ExecuteWorkflowService and the REST route's workhorse_resume_event. RunEvent#valid_for? accepts an approval on input_required, because a flow's question takes the decision. In DWS, a rejection with a message is the gate's MODIFY route.
  • RunEvent#approval_with_message? and ExecuteRunService refuse an approval that carries a message (reason approval_with_message), on both runtimes. The gateway's approval has no message field, so CI failed the job and Workhorse dropped the message. This replaces the guard in the REST route's Workhorse branch. The route's CI chat branch (foundational_resume_decision) keeps its guard, because it doesn't go through ExecuteRunService yet.
  • ExecuteRunService.runtime_for_session is the one rule for which runtime a session's next run uses: the caller's override, else the flow's default for a first run, else the last runtime. ExecuteWorkflowService uses it so its "Allow flow execution" check and the run agree.
  • A resume no longer passes the flow config (Flows::ExecuteService#resolved_foundational_flow_params returns {}) or the consumer's service account from the REST route. Only a new session uses them.
  • An API resume now goes through the turn-start hook (reset_messaging_turn!). This does nothing at these pauses: on CI, delivered_at isn't claimed at a pause.

Behaviour changes

  1. Token failures on these paths return Could not obtain authentication token / Could not obtain Duo Workflow token instead of OAuth token creation failed / Workflow token creation failed. The REST resume route shows them with bad_request!.
  2. CI resumes of scheduled or system sessions request the autonomous token, as their start already did.
  3. An API resume of a catalog session on CI:
    • runs as the session's service account (workflow.service_account), not the flow's current one (consumer.active_service_account)
    • defaults source_branch to the MR's source branch, not the default branch
    • returns invalid_event for a session still in created
    • builds the token and metadata for the session's user, as the start does. Only the session's user, or a composite-identity service account acting for them, may resume, so this differs from master only for that service account
  4. Approving a flow's question with a message through the REST API returns 400 with human_message cannot be sent with human_approval=true. .... Before, a catalog session on CI returned 201 and the job then failed ("--rejection-reason" can only be used with "--approval false"). The endpoint is experimental. Approving without a message, rejecting, and rejecting with a message work as before.
  5. A Code Review start through the catalog with additional_context asking for depth: standard gets a standard review: the session records the standard flow and the token uses the standard model setting. On master both ignored the requested depth and ran deep (with duo_code_review_deep_flow on). Only Code Review reads additional_context to pick its flow or model; no in-tree caller sends it on this path today.

Known limits and follow-ups (tracked on #629005)

  • A provisioning failure on Slack or @GitLabDuo now leaves a created session until the stuck-session cleanup drops it, because the session now exists before provisioning. Dropping it in ExecuteWorkflowService would race the adapter's delivery claim. The race-free place is with_lifecycle_hooks.
  • Membership is a per-caller flag. The end state is Runtimes::Ci deciding from the session.
  • "Allow flow execution" lives in two places. It can't simply move into ExecuteRunService, because Slack's Workhorse runs go through it too and don't require the project's remote-flows setting.
  • The adapter still pins runtime: :ci and creates Workhorse sessions itself.
  • Catalog resumes on Workhorse don't take the TurnClaim that MCP resumes take. Not reachable until a catalog flow runs on Workhorse.
  • A resume of a catalog session that ran on Workhorse continues on Workhorse inside ExecuteRunService, but the REST API can't reach it yet: the resume_duo_workflow policy needs a finished CI workload (resumable?, workflow.rb:1253-1256), and a Workhorse run has none, so it returns 403. Same on master. Only MCP chat sessions have an exception (workflow_policy.rb:150-157). Until the follow-up, service specs are the only coverage for that resume branch. No catalog flow on this path declares none yet, so nobody hits this today. Follow-up: one "can the user answer now?" rule for every runtime, built on a record per run.
  • ExecuteWorkflowService still requires json_config and returns it as flow_config. On a resume it's the config of the session's version, because Flows::ExecuteService already resolves that version (flows/execute_service.rb:35-38), so the response and the run agree. Removing the requirement is a cleanup follow-up.
  • AGENT_PRIVILEGES (the fixed privileges of custom catalog flows) stays. Removing it needs a product decision on where custom flows get their privileges.
  • Interaction with !267496: it starts a new messaging turn only for input events. On CI, an approval can answer an input_required pause, and after this MR a reply to a flow's question is an approval event on both runtimes. Whichever MR merges second should gate the new turn on the pause type (continuation? && !workflow.awaiting_approval?), not the event type.

References

Screenshots or screen recordings

Not applicable: backend only.

How to set up and validate locally

The tests cover the four paths this MR moves: a custom flow started by a mention, the same session resumed through the REST API, a @GitLabDuo question, and a @GitLabDuo review. The last test checks that a run doesn't re-add a service account a maintainer removed. I ran all of them on GDK.

Before you start
  1. Check out the branch and restart Rails and Sidekiq:

    git fetch origin duo/refactor/629005-catalog-execute-run
    git checkout duo/refactor/629005-catalog-execute-run
    gdk restart rails-web rails-background-jobs
  2. Use a project in a GitLab Duo-enabled group with a GDK runner for Duo Agent Platform jobs, an issue and an open MR. Turn on the Code Review flow for the project.

  3. In the AI Catalog, create a custom flow with this definition, then enable it in the project with a mention trigger. It asks one question and then waits for an answer:

    version: "v1"
    environment: ambient
    components:
      - name: "ask_agent"
        type: AgentComponent
        prompt_id: "ask_prompt"
        inputs: ["context:goal"]
        toolset: []
        ui_log_events: ["on_agent_final_answer"]
      - name: "human_input"
        type: HumanInputComponent
        sends_response_to: "ask_agent"
        interaction_type: "input"
        message_template: "Which colour should I use for the answer? Reply with one word."
        ui_log_events: ["on_user_input_prompt", "on_user_response"]
      - name: "answer_agent"
        type: AgentComponent
        prompt_id: "answer_prompt"
        inputs: [{ from: "context:ask_agent.final_answer", as: "draft" }]
        toolset: []
        ui_log_events: ["on_agent_final_answer"]
    prompts:
      - prompt_id: "ask_prompt"
        name: "HITL ask"
        prompt_template:
          system: |
          user: |
            {{goal}}
          placeholder: history
        unit_primitives: []
        params: { timeout: 180 }
      - prompt_id: "answer_prompt"
        name: "HITL answer"
        prompt_template:
          system: |
            You are a test agent. Reply in one sentence that repeats the draft below. No tools.
          user: |
            Draft: {{draft}}
          placeholder: history
        unit_primitives: []
        params: { timeout: 180 }
    routers:
      - from: "ask_agent"
        to: "human_input"
      - from: "human_input"
        condition:
          input: "context:human_input.approval"
          routes: { "modify": "ask_agent", "reject": "end", "approve": "answer_agent", "default_route": "answer_agent" }
      - from: "answer_agent"
        to: "end"
    flow:
      entry_point: "ask_agent"
  4. Create a personal access token with the api scope.

  5. In bin/rails console, define this helper. It shows where each run of a session ran and with which flow:

    def runs(id)
      w = Ai::DuoWorkflows::Workflow.find(id)
      puts "#{w.workflow_definition}: #{w.status_name}, runtime #{w.last_runtime}, flow #{w.flow_metadata_json}"
      w.workloads.order(:id).each do |workload|
        vars = workload.pipeline.builds.first.yaml_variables.to_h { |v| [v[:key].to_s, v[:value]] }
        puts "  job #{workload.id}: #{workload.pipeline.status}, runs as #{workload.pipeline.user.username}, " \
             "flow_config_id=#{vars['DUO_WORKFLOW_FLOW_CONFIG_ID'].inspect}"
      end
    end

    Find a session's ID under Automate > Sessions (newest entry).

# Do Expect
1 On the issue, comment @<custom flow service account> Summarize this issue in one sentence. The flow comments that it started. runs(<id>) shows one CI job that succeeded, run as the flow's service account, and the session is Input required with the colour question.
2 Answer through the API with a reply: curl --request POST --header "PRIVATE-TOKEN: <token>" --data "human_approval=false" --data-urlencode "human_message=Blue" "http://gdk.test:3000/api/v4/ai/duo_workflows/workflows/<id>/resume" HTTP 201. runs(<id>) shows a second CI job run as the flow's service account, the session log has Blue as your message, and the flow asks its question again (its modify route).
2b Start two more sessions as in test 1. Resume one with human_approval=true and the other with human_approval=false, both without a message Both 201. The approved one runs answer_agent and finishes. The rejected one logs Action rejected. and finishes.
2c Start one more session as in test 1. Resume it with human_approval=true and human_message=Blue HTTP 400 with human_message cannot be sent with human_approval=true, and no new job starts. On master it returns 201 and the job fails. Covered by request and service specs; not run on GDK.
3 On the MR, comment @GitLabDuo In one sentence, what does this MR change? GitLab Duo replies once. runs(<id>) shows code_review/v1, finished, flow_config_id="gitlab_duo_mention_assistant", and the flow gitlab_duo_mention_assistant recorded on the session.
4 On the MR, comment @GitLabDuo review The review is posted. runs(<id>) shows flow_config_id="code_review".
5 Edge case: remove the custom flow's service account from the project (Manage > Members), then repeat test 1 The run fails with Insufficient permissions to create a new pipeline, and the account is not a member again afterwards. Same result as on master. Add the account back as Developer when you're done.

| 6 | Edge case: remove the Code Review flow's service account, then repeat test 3 | GitLab Duo replies once, and the account is a Developer again afterwards: the @GitLabDuo path keeps adding it. | | 7 | Edge case: turn off Allow flow execution for the project, then repeat test 1 | The flow replies Could not start processing due to this error: Can not execute workflow in CI, and no job starts. Turn the setting back on. |

Not covered here: resuming a catalog session that ran on Workhorse. No catalog flow on this path declares coding_environment: none yet, so the specs cover that case.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Merge request reports

Loading
Loading