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)
- Model and status service:
state :idle, value: 9(no migration:statusis asmallintwith no constraint),event :idle(running → idle),idlein theresume/drop/stopsources,TARGET_STATUSES,COUNTED_TRANSITIONS,BILLABLE_STATUSES, thecompletedstatus group,progress_status→:completed, and the functional-verification hook. Theidleevent resolves an open input-required to-do and creates none. - Capability:
idle_status_eventincompute_server_capabilitiesandAi::FlowsMetadataService. Workhorse letsidle_status_event(server) andidle_status(client) through. - Status lists:
Ai::Governance::Sessionstatus enum,get_duo_session(turn_complete: true, likeinput_required),FlowTriggerRunSummaryLoader::RUN_STATUSES. - Frontend constants: icon, inbox label, session list group, automation run status.
- Docs: REST, MCP tools, regenerated GraphQL reference.
- Branch resume: a retry's other attempt resumes from its deepest
input_requiredoridlecheckpoint (GRAPH_STATUSES_SETTLED). - GraphQL introspection schemas regenerated.
References
- Issue: #633285 (closed)
- Epic: gitlab-org#24022
- Prototype this MR takes parts from: !261434 (closed)
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 # => 0In /-/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
completedstatus 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: COMPLETEDreturns idle sessions, andorder_by_statussorts them right after finished ones. This keeps the publicDuoWorkflowStatusGroupenum unchanged: splitting idle out later is an additive enum value, while removing a group would need a deprecation. TheDuoWorkflowStatusenum does getIDLE. - No cancel button on idle sessions: nothing runs while a session is idle, and stopping it would count a finished turn as canceled. The
stopanddroptransitions fromidlestay 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 foridle(not terminal, not active, by design: a new status counts as waiting).Ai::Messaging::CallbackWorkertherefore delivers nothing when a CI job ends while idle. Delivering idle turns is #633286, a prerequisite of the flag #633281.progress_status→:completedforidle: 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 listsidle_status_event. Its static list mirrorscompute_server_capabilities, and it is meant to replace that list.- Workhorse: the client capability
idle_statussits with the client constants and the server capabilityidle_status_eventwith the server constants. - Governance spec: the existing "mirrors
Workflowstate_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 asidle, notnil. FlowTriggerRunSummaryLoader::RUN_STATUSES: mapsidle: :succeeded. Without an entry,fetchraises. The frontend mirrorWORKFLOW_STATUS_TO_AUTOMATION_RUN_STATUSgetsIDLE: '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: excludesIDLE(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, andWORKFLOW_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 againstINPUT_REQUIREDfor chat and CLI flows, which only get idle once their client declaresidle_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:
idleis added to the hand-written status lists indoc/api/duo_agent_platform_flows.mdand to thestatusesparameter oflist_duo_sessionsindoc/user/model_context_protocol/mcp_server_tools.md. That tool builds its enums from the model, so it now acceptsidle. - Branch resume treats
idleas settled:branch_fork_thread_tsused to treat onlyinput_requiredas the place a retry's other attempt resumes from. Chat engine turns rest asidle, so their branches would have resumed from the tip.
Compatibility and rollout
- Ships first and alone: the AI Gateway sends
idleonly to instances that advertiseidle_status_event, which this MR adds. Older instances keep gettinginput_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 status9would read back as an unknown state, so stop the flow first. - Older IDEs read the stored status through GraphQL
workflowStatusand unlock input only onINPUT_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
idlestatus filter until glql!573 (merged) is released, sodap_impact_spec.rbleavesidleout 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?, thesource_typeprivacy change, the session page reply box, andee/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 addidleto 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.