<!-- 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 Duo flows with `trigger_duo_flow` or agent turns with `ask_duo_agent` need a way to discover their existing sessions — for example, to resume a session after a context reset, to check which flows are still running, or to surface recent sessions to the user. `list_sessions` (MCP name: `list_duo_sessions`) returns the caller's Duo workflow sessions, optionally filtered by project and/or status, with pagination to bound large result sets. **Naming:** the tool returns a *collection* of sessions, so it belongs to the `list_` verb class (like `list_work_items`, `list_branches`, `list_commits`), not `get_` (single-object reads). The companion single-object reader is `get_duo_session` / `get_duo_session_status` (see companion issue #607634). ## Scope and Non-Goals - **In scope:** list the authenticated user's Duo workflow sessions; filter by `project_id` and/or `status`; cursor-based pagination (`first`/`after`); return compact session metadata (id, status, goal, flow, web_url, created_at). - **Non-goals:** reading a single session's full details or final answer (`get_session` / `get_duo_session_status`), starting sessions (`trigger_duo_flow`, `ask_duo_agent`), approving tool calls (`approve_duo_agent_action`), listing available agents/flows (`list_duo_agents`). - **Follow-ups:** none — the companion `get_session` issue covers the single-object reader. ## Data Shape and Context Engineering Session lists can grow large for active users, so pagination (`first`/`after`, capped at 100 per page) plus optional `project_id` and `status` filters are the saturation guards. Each entry is metadata-only (id, status, goal truncated to 160 chars, flow reference, web_url, created_at) — never full checkpoint or trace content. - Input schema (example): ```json { "tool": "list_duo_sessions", "description": "List the authenticated user's Duo agent sessions, optionally filtered by project and/or status.", "parameters": { "url": "string (optional; full GitLab URL encoding project path, e.g. https://gitlab.com/group/project)", "project_id": "int | string (optional; numeric ID or URL-encoded path such as 'gitlab-org%2Fgitlab'; filters to sessions in that project)", "status": "string (optional; filter by status group: 'running', 'finished', 'failed', 'awaiting_approval')", "first": "integer (optional, 1-100, default: 20)", "after": "string (optional; cursor from the previous response's page_info.end_cursor)" } } ``` - Output schema (JSON example): ```json { "sessions": [ { "id": 42, "status": "finished", "goal": "Fix the flaky spec in issue #1234 and open an MR", "flow": "developer/v1", "web_url": "https://gitlab.com/group/project/-/duo_workflows/42", "created_at": "2026-07-31T10:00:00Z" }, { "id": 43, "status": "running", "goal": "Review MR !99 for security issues", "flow": "security_review/v1", "web_url": "https://gitlab.com/group/project/-/duo_workflows/43", "created_at": "2026-07-31T11:00:00Z" } ], "page_info": { "has_next_page": false, "end_cursor": null } } ``` ## Resources - Existing GraphQL query: `Query.duoWorkflowWorkflows` (`ee/app/graphql/ee/types/query_type.rb`) — `Resolvers::Ai::DuoWorkflows::WorkflowsResolver` → `Ai::DuoWorkflows::WorkflowsFinder`. Already supports `project_path`, `status_group`, search, sort, and cursor pagination, authorized via `WorkflowType#authorize :read_duo_workflow`. - Status filtering: `running`/`finished`/`failed` map cleanly onto `statusGroup: ACTIVE`/`COMPLETED`/`FAILED` (`Types::Ai::DuoWorkflows::WorkflowStatusGroupEnum`) — keep this issue's original status vocabulary, it matches the REST API's own `status_name`-as-`status` convention (`ee/lib/api/entities/ai/duo_workflows/workflow.rb`), don't switch to the six raw group names. `awaiting_approval` is `plan_approval_required`+`tool_call_approval_required` specifically, not the model's broader `awaiting_input` group (which also includes `input_required`, a different "waiting for a chat reply" state) — `status_group` can't express that narrower set, so this depends on #608884 adding a `statuses:` (exact-state) argument to the resolver first. - Companion issues: `start_flow` / `trigger_duo_flow` MCP tool (#607619), `get_session` / `get_duo_session_status` MCP tool (#607634) - Reference shape: `list_merge_requests` (`app/services/mcp/tools/merge_requests/list_merge_requests_{tool,service}.rb`) — closest existing GraphQL-backed list tool with a `url`/`project_id` resource filter and cursor pagination. - 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, not one: - `Mcp::Tools::DuoWorkflows::ListDuoSessionsTool < Mcp::Tools::Base::GraphqlTool` - `Mcp::Tools::DuoWorkflows::ListDuoSessionsService < Base::GraphqlService` 2. Operation file: `ee/app/graphql/queries/mcp/duo_workflows/list_duo_sessions.query.graphql`, querying `duoWorkflowWorkflows(projectPath:, statusGroup:, first:, after:)`, selecting `id`, `statusName`, `goal`, `workflowDefinition`, `createdAt`, and `project { webUrl }`. 3. `url`/`project_id` → `projectPath`: resolve in the `Tool` class via `find_parent_by_id_or_path!(:project, identifier)` (from `Mcp::Tools::Concerns::ResourceFinder`, already mixed into `GraphqlTool`). No hand-written project lookup or `Ability.allowed?` — `GitlabSchema.execute` runs as `current_user` and the finder's own `current_user.can?(:duo_workflow, project)` check applies automatically. 4. `status`: keep the tool's existing vocabulary. `running`/`finished`/`failed` → `statusGroup: ACTIVE`/`COMPLETED`/`FAILED`. `awaiting_approval` → the new `statuses: [PLAN_APPROVAL_REQUIRED, TOOL_CALL_APPROVAL_REQUIRED]` argument from #608884 (blocks this issue) — do not substitute `statusGroup: AWAITING_INPUT`, it also matches `input_required` sessions that don't need an approval decision. 5. Pagination: `first`/`after`, returning `page_info.has_next_page`/`end_cursor` from the connection's `pageInfo`. 6. `goal` truncation (160 chars) and `web_url` construction (`"#{project_web_url}/-/automate/agent-sessions/#{numeric_id}"`, unwrapping the numeric id from the GraphQL `id` GID) happen client-side in `ListDuoSessionsTool#process_result`. 7. Register in `EE_GRAPHQL_TOOLS` (not `EE_CUSTOM_TOOLS`) in `ee/app/services/ee/mcp/tools/manager.rb`. 8. Specs: `spec/graphql/all_queries_spec.rb` coverage comes free from the committed `.graphql` file; add Tool/Service specs mirroring `list_merge_requests_{tool,service}_spec.rb` — no filter, project filter, status filter, pagination, empty result.