Store the idle status for Duo agent sessions

What does this MR do and why?

Today a Duo agent session shows "Input required" in two different situations: when the agent is blocked and needs you (a question, a plan to approve), and when it simply finished its turn and you may follow up. GitLab can't tell them apart, so every finished turn lands in "needs attention" and can send a to-do and an email. Once Duo Developer sessions stay open after each answer (gitlab-org#24022), every mention would notify someone for nothing.

This MR teaches GitLab a new session status, idle: "done for now, reply to keep going". An idle session counts as completed: it stays out of "needs attention", creates no to-do or email, closes an open "input required" to-do, and offers no cancel button. GitLab also tells the AI Gateway that it accepts idle, so the gateway only sends it to instances that understand it. Nothing sends idle yet, so this ships without a feature flag and changes nothing for users today.

Design: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7419 (merged). AI Gateway side: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7518 (merged).

What changes, by commit (for reviewers)
  1. Model and status service: state :idle, value: 9 (no migration: status is a smallint with no constraint), event :idle (running → idle), idle in the resume/drop/stop sources, TARGET_STATUSES, COUNTED_TRANSITIONS, BILLABLE_STATUSES, the completed status group, progress_status → :completed, and the functional-verification hook. The idle event resolves an open input-required to-do and creates none.
  2. Capability: idle_status_event in compute_server_capabilities and Ai::FlowsMetadataService. Workhorse lets idle_status_event (server) and idle_status (client) through.
  3. Status lists: Ai::Governance::Session status enum, get_duo_session (turn_complete: true, like input_required), FlowTriggerRunSummaryLoader::RUN_STATUSES.
  4. Frontend constants: icon, inbox label, session list group, automation run status.
  5. Docs: REST, MCP tools, regenerated GraphQL reference.
  6. Branch resume: a retry's other attempt resumes from its deepest input_required or idle checkpoint (GRAPH_STATUSES_SETTLED).
  7. GraphQL introspection schemas regenerated.

References

How to set up and validate locally

Rails only (about 2 minutes). In a GDK with Duo Agent Platform, check out this branch and open gdk rails c:

user = User.find_by_username('root')
project = Project.find_by_full_path('gitlab-duo/test')
update = ->(workflow, event) do
  Ai::DuoWorkflows::UpdateWorkflowStatusService.new(workflow: workflow, status_event: event, current_user: user).execute
end

workflow = Ai::DuoWorkflows::Workflow.create!(
  user: user, project: project, goal: 'Try the idle status',
  workflow_definition: 'software_development', environment: :ambient,
  agent_privileges: [1], pre_approved_agent_privileges: []
)
workflow.start!

update.(workflow, 'idle')
workflow.reload.status_name  # => :idle
workflow.status_group        # => :completed (not :awaiting_input)
workflow.resumable?          # => false
Todo.where(target: workflow, action: Todo::DUO_WORKFLOW_INPUT_REQUIRED).count # => 0

update.(workflow, 'resume')
workflow.reload.status_name  # => :running

# An open "input required" to-do is closed when the session goes idle:
update.(workflow, 'require_input'); update.(workflow, 'resume')
TodoService.new.duo_workflow_input_required(workflow)
update.(workflow, 'idle')
Todo.where(target: workflow, action: Todo::DUO_WORKFLOW_INPUT_REQUIRED).pending.count # => 0

In /-/graphql-explorer, the session reads status: IDLE and is listed under statusGroup: COMPLETED:

query {
  duoWorkflowWorkflows(projectPath: "gitlab-duo/test", statusGroup: COMPLETED) {
    nodes { id status }
  }
}

End to end with the AI Gateway (optional, about 10 minutes): follow the GDK steps in gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7518 (merged). A Support Assistant chat then ends its turn as idle in this instance. Rebuild Workhorse after checking out this branch (make -C workhorse gitlab-workhorse, then gdk restart gitlab-workhorse). A stale binary drops idle_status_event, and the gateway falls back to input_required.

Decisions worth a look
  • Idle is in the completed status group, not a group of its own: an idle session is done for now and only differs from a finished one in that it takes new input. statusGroup: COMPLETED returns idle sessions, and order_by_status sorts them right after finished ones. This keeps the public DuoWorkflowStatusGroup enum unchanged: splitting idle out later is an additive enum value, while removing a group would need a deprecation. The DuoWorkflowStatus enum does get IDLE.
  • No cancel button on idle sessions: nothing runs while a session is idle, and stopping it would count a finished turn as canceled. The stop and drop transitions from idle stay for the API and for errors. Closing a session for good, as finished rather than canceled, belongs with what "session finished" means for sessions that stay open: #633375.
  • awaiting_user?: left as it is, so it is true for idle (not terminal, not active, by design: a new status counts as waiting). Ai::Messaging::CallbackWorker therefore delivers nothing when a CI job ends while idle. Delivering idle turns is #633286, a prerequisite of the flag #633281.
  • progress_status → :completed for idle: idle is not terminal, so without this line it would report :generating. The work item's agent plan widget shows an idle session's work as completed.
  • Ai::FlowsMetadataService: also lists idle_status_event. Its static list mirrors compute_server_capabilities, and it is meant to replace that list.
  • Workhorse: the client capability idle_status sits with the client constants and the server capability idle_status_event with the server constants.
  • Governance spec: the existing "mirrors Workflow state_machine :status exactly" spec already fails for any state missing from the enum, so it covers "every state is known". I added a sync spec showing an idle workflow reads back as idle, not nil.
  • FlowTriggerRunSummaryLoader::RUN_STATUSES: maps idle: :succeeded. Without an entry, fetch raises. The frontend mirror WORKFLOW_STATUS_TO_AUTOMATION_RUN_STATUS gets IDLE: 'SUCCEEDED' too. Because idle is not terminal, the recent runs table shows no duration.
  • send_duo_session_input_service.rb: unchanged. Its descriptions list the statuses the resume endpoint accepts, and idle is not resumable.
  • Frontend lists, decided per list:
    • AGENT_PLATFORM_STATUS_ICON.IDLE: status-success / subtle.
    • AGENT_PLATFORM_CANCELABLE_STATUSES: excludes IDLE (see above).
    • AGENT_PLATFORM_STATUS_IDLE: added.
    • Inbox label: "Idle".
    • Session list: an "Idle" group in SESSION_OTHER_GROUPS, after "Running". It groups by status, so it is independent of the backend status group.
    • WORKFLOW_AWAITING_INPUT_STATUSES / SESSION_INPUT_REQUIRED_STATUSES, the awaiting-input group, and WORKFLOW_TERMINAL_STATUSES: unchanged, because idle is neither awaiting input nor terminal.
    • DUO_WORKFLOW_ATTACHED_STATUSES (ee/app/assets/javascripts/ai/constants.js): unchanged. Unknown statuses already free the lock by design.
    • Agentic chat state managers, chat_turn_run.js, session_pills_bar.vue, cli_sessions.js: unchanged. They compare against INPUT_REQUIRED for chat and CLI flows, which only get idle once their client declares idle_status.
    • note_session_bar.vue: unchanged. An idle session shows the bar with no phrase and no icon. That doesn't break anything, and hiding it like a finished session belongs with the turn-ended work.
  • Docs: idle is added to the hand-written status lists in doc/api/duo_agent_platform_flows.md and to the statuses parameter of list_duo_sessions in doc/user/model_context_protocol/mcp_server_tools.md. That tool builds its enums from the model, so it now accepts idle.
  • Branch resume treats idle as settled: branch_fork_thread_ts used to treat only input_required as the place a retry's other attempt resumes from. Chat engine turns rest as idle, so their branches would have resumed from the tip.
Compatibility and rollout
  • Ships first and alone: the AI Gateway sends idle only to instances that advertise idle_status_event, which this MR adds. Older instances keep getting input_required.
  • Rolling deploys: when a flow starts sending idle (gitlab-org/modelops/applied-ml/code-suggestions/ai-assist#3173), this MR must be fully deployed on GitLab.com, canary and main. An older pod answers the unknown event with a 400.
  • Rollback: reverting this MR is safe until something writes idle. After that, sessions with status 9 would read back as an unknown state, so stop the flow first.
  • Older IDEs read the stored status through GraphQL workflowStatus and unlock input only on INPUT_REQUIRED. That's acceptable for Duo Developer (CI sessions viewed in the web UI). The by-hand check with a released IDE is still open (see "Not in this MR").
Not in this MR
  • Idle on the DAP Impact dashboard: GLQL rejects an idle status filter until glql!573 (merged) is released, so dap_impact_spec.rb leaves idle out of the Completed group in its "same groups as the session list" check. Counting idle sessions as Completed there, plus the GLQL bump, is #634550 (closed).
  • The older-IDE check from the issue. It needs a released IDE and will be done by hand later.
  • Closing an idle session as finished: #633375.
  • The prototype's turn-ended event, MessageAdmission, messageInput, flow_environment, runtime_reachable?, the source_type privacy change, the session page reply box, and ee/app/workers/ai/messaging/ changes. These belong to other issues of the epic.
  • doc/user/glql/data_sources/duo_workflows.md: the GLQL status filter's accepted values are not defined in this repository, so I didn't add idle to that list.

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.

Edited by Thomas Schmidt

Merge request reports

Loading
Loading