<!-- mcp-tool-guidance-callout --> > [!note] > **Before picking up this work:** this issue adds an MCP tool. Please follow the [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance first. That includes creating an MCP Tool Proposal, using `verb_object` naming (`get_` / `list_` / `save_` / `delete_`), and the shared resource-identification input base classes. ## Problem Statement / Use Case Agents that start a Duo flow with `trigger_duo_flow` (or `ask_duo_agent`) need a way to check whether the session has finished, is still running, or is paused waiting for approval — and to retrieve the agent's final answer when it is done. `get_duo_session` is the polling companion to `trigger_duo_flow`: given a `workflow_id`, it returns the current status, the latest progress update while running, or the final answer when the session reaches a terminal or turn-complete state. **Naming:** the tool reads a single session object, so it belongs to the `get_` verb class (like `get_project`, `get_work_item`). The MCP name is `get_duo_session` A similar tool has been added to the Duo Workflow service in https://gitlab.com/gitlab-org/gitlab/-/work_items/594326, and should be superseded by this new tool. ## Scope and Non-Goals - **In scope:** poll a single Duo workflow session by `workflow_id`; return status, progress, final answer, or approval guidance; register `get_duo_workflow_status` as a backward-compat alias. - **Non-goals:** starting sessions (`trigger_duo_flow`, `ask_duo_agent`), listing sessions (`list_sessions` — see companion issue), approving tool calls (`approve_duo_agent_action`), approving flow plans (`approve_duo_flow`). - **Follow-ups:** none — the companion `list_sessions` issue covers the collection reader. ## Data Shape and Context Engineering Each response returns both a human-readable `text` content block and a structured JSON metadata object. The text block carries the agent's answer or progress; the JSON object carries machine-readable fields for programmatic use. ### Input schema ```json { "tool": "get_duo_session", "description": "Check the status of a Duo agent session (started by trigger_duo_flow or ask_duo_agent). While running, returns compact progress and a poll_after_seconds hint - wait that long, then call again. \"finished\" or \"input required\" both mean the current turn is complete and include the agent's answer (\"input required\" is the normal resting state of chat-style sessions). Approval-required statuses will not progress by polling - use approve_duo_agent_action instead.", "parameters": { "workflow_id": "integer (required; workflow ID returned by trigger_duo_flow or ask_duo_agent)" } } ``` ### Output schema (JSON metadata object examples) Running: ```json { "workflow_id": 42, "status": "running", "web_url": "https://gitlab.com/group/project/-/duo_workflows/42", "poll_after_seconds": 30 } ``` Text content: `"Status: running. Latest agent update: <truncated to 500 chars>. Poll again in 30 seconds."` Finished: ```json { "workflow_id": 42, "status": "finished", "web_url": "https://gitlab.com/group/project/-/duo_workflows/42" } ``` Text content: the agent's final answer (extracted from the last agent message in `latestCheckpoint.lastDuoMessage`), or `"Session finished, but no final answer was produced."` if none is found. Turn complete (`"input required"` — normal resting state of chat-style sessions): ```json { "workflow_id": 42, "status": "input required", "turn_complete": true, "web_url": "https://gitlab.com/group/project/-/duo_workflows/42" } ``` Text content: the agent's latest answer, or `"The last turn completed, but no agent answer was found."`. Awaiting approval (`tool_call_approval_required` or `plan_approval_required`): ```json { "workflow_id": 42, "status": "tool_call_approval_required", "awaiting_approval": true, "web_url": "https://gitlab.com/group/project/-/duo_workflows/42" } ``` Text content: `"Session is paused: <status>. Polling will NOT move it forward. To proceed, call approve_duo_agent_action with workflow_id=42 and decision=\"approve\" (or \"reject\")."` (prepended with the latest agent message if one exists). Other terminal statuses (failed, stopped, completed): ```json { "workflow_id": 42, "status": "failed", "web_url": "https://gitlab.com/group/project/-/duo_workflows/42" } ``` Text content: `"Session failed. See <web_url> for details."` ## Resources - Existing GraphQL query: `Query.duoWorkflowWorkflows(workflowId:)` (`Resolvers::Ai::DuoWorkflows::WorkflowsResolver#resolve_single_workflow`) — returns one `WorkflowType`, raising a GraphQL-native not-found/permission error (`raise_resource_not_available_error!`) when the workflow doesn't exist or the user lacks `read_duo_workflow`. - Final-answer/progress extraction: `WorkflowType#latest_checkpoint { lastDuoMessage { content } }` (`ee/app/graphql/types/ai/duo_workflows/workflow_event_type.rb`, `duo_message_type.rb`) — added after the prototype MR below was written, covers what the prototype hand-rolls from raw `checkpoint.ui_chat_log`. - Prototype MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246597 — `ee/app/services/mcp/tools/duo_workflows/get_duo_session_status_service.rb` - Companion issues: `start_flow` / `trigger_duo_flow` MCP tool (#607619), `list_sessions` MCP tool (#607635) - MCP dev guidelines: `doc/development/duo_agent_platform/mcp/_index.md`; `gitlab-mcp-tool-builder` skill's build recipe — verify a GraphQL field exists before writing a custom one. ## Implementation Plan 1. Two classes: `Mcp::Tools::DuoWorkflows::GetDuoSessionTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::DuoWorkflows::GetDuoSessionService < Base::GraphqlService`. 2. Operation file: `ee/app/graphql/queries/mcp/duo_workflows/get_duo_session.query.graphql`, querying `duoWorkflowWorkflows(workflowId:)`, selecting `id`, `statusName`, `statusGroup`, `project { webUrl }`, `latestCheckpoint { lastDuoMessage { content role } }`. `operation_name: 'duoWorkflowWorkflows'`; read the single node from `nodes[0]`. 3. `workflow_id` → `workflowId`: convert the plain integer to a GID before sending — the resolver's `find_object` does `GitlabSchema.find_by_gid(id)`. 4. `status`: `statusName` returns the underscored enum name (e.g. `input_required`). Confirm whether the output's space-separated form (`"input required"`) is a hard requirement or just this issue's shorthand; format client-side if needed. 5. `turn_complete`/`awaiting_approval`: derive client-side from `statusName`/`statusGroup` (`input_required` → `turn_complete: true`; `tool_call_approval_required`/`plan_approval_required` → `awaiting_approval: true`). 6. Progress/final-answer text: `latestCheckpoint.lastDuoMessage.content`. Verify `lastDuoMessage` is reliably agent-authored before relying on it as-is; fall back to the fuller `duoMessages` list filtered by role if the last logged entry can be a user/tool-call message. 7. `web_url`: build client-side from `project.webUrl` + `/-/automate/agent-sessions/<numeric id>` — no schema change needed. 8. Annotations: `readOnlyHint: true`. 9. Register in `EE_GRAPHQL_TOOLS` in `ee/app/services/ee/mcp/tools/manager.rb`; register `get_duo_workflow_status` as a `tool_aliases` entry. 10. Specs: cover running / finished / input-required / awaiting-approval / other-terminal branches, plus not-found and permission-denied (via the resolver's native error path).