opencode-gitlab-dap 1.1.1 → 1.2.0

package/README.md

@@ -1,15 +1,16 @@
 # opencode-gitlab-dap
 
-An [opencode](https://opencode.ai) plugin that discovers GitLab foundational and custom agents
-from the [GitLab AI Catalog](https://docs.gitlab.com/ee/user/ai_catalog/) and injects them as
-native agents into the opencode agent picker.
+An [opencode](https://opencode.ai) plugin for the [GitLab Duo Agent Platform (DAP)](https://docs.gitlab.com/user/duo_agent_platform/).
+Discovers agents and flows from the GitLab AI Catalog, injects them into opencode,
+and provides tools for managing and executing DAP workflows.
 
 ## Requirements
 
 - opencode with the `gitlab` provider configured and Duo Workflow (DWS) enabled
 - GitLab OAuth or PAT authentication (via `opencode-gitlab-auth` or manual config)
-- GitLab project with AI Catalog agents enabled
-- `gitlab-ai-provider` >= 6.2.0 (peer dependency, bundled with opencode's gitlab provider)
+- GitLab project with AI Catalog agents/flows enabled
+- `gitlab-ai-provider` >= 6.3.0 (peer dependency, bundled with opencode's gitlab provider)
+- `@opencode-ai/plugin` >= 1.2.24
 
 ## Install
 
@@ -27,102 +28,152 @@ Or add to your `~/.config/opencode/opencode.json`:
 
 No further configuration needed. The plugin reads GitLab auth and model cache automatically.
 
-## How it works
+## Features
 
-On every opencode startup the plugin:
+### Agent & Flow Discovery
 
-1. Reads the GitLab auth token from `~/.local/share/opencode/auth.json`
-2. Reads the already-cached GitLab workflow model from `gitlab-ai-provider`'s model cache (no extra network call)
-3. Queries two GitLab GraphQL APIs in parallel:
-   - `aiFoundationalChatAgents` — project-scoped foundational agents (Planner, Data Analyst, Security Analyst, GitLab Duo, etc.)
-   - `aiCatalogConfiguredItems` — custom agents explicitly enabled for the project
-4. Injects all discovered agents into opencode's config via the `config` hook — they appear in the `/agents` dialog and the Tab agent picker
-5. Each agent runs through GitLab Duo Agent Platform (DWS), with tool actions executed locally by opencode
+On startup, the plugin discovers all agents and flows enabled for your project:
 
-## Agent types
+- **Foundational agents** (Planner, Data Analyst, Security Analyst, etc.) via `aiFoundationalChatAgents`
+- **Custom agents** and **flows** via `aiCatalogConfiguredItems`
+- Agents appear in `/agents` dialog and Tab agent picker
+- Flows appear in the `@` mention menu as subagents
 
-### Foundational agents
+### Flow Execution via `@` Menu
 
-Built-in GitLab agents available based on your project's Duo Workflow license:
+Type `@Flow Name` followed by your goal to execute a flow:
 
-| Agent            | Description                     |
-| ---------------- | ------------------------------- |
-| GitLab Duo       | General-purpose agentic chat    |
-| Planner          | Issue and project planning      |
-| Data Analyst     | GitLab data analysis (GLQL)     |
-| Security Analyst | Security vulnerability analysis |
+```
+@Fix CI/CD Pipeline fix the failing pipeline for MR !12
+```
 
-These are fetched via `aiFoundationalChatAgents` and are scoped to what's enabled for your project.
+The plugin:
 
-### Custom agents
+1. Intercepts the `@` mention via `chat.message` hook
+2. Dispatches a subagent that fetches the flow definition
+3. Gathers required inputs using available GitLab tools
+4. Executes the flow via `POST /api/v4/ai/duo_workflows/workflows`
+5. Monitors workflow status until it starts running
+6. Reports the workflow URL for tracking in GitLab UI
 
-User-defined agents created in the [GitLab AI Catalog](https://docs.gitlab.com/ee/user/ai_catalog/).
-Custom agents must be explicitly enabled for the project to appear.
+### 13 DAP Tools
 
-Custom agents run with their full `flowConfig` (system prompt, tools, routing) sent directly to DWS.
-Their sessions are linked to the correct agent page in the GitLab UI (`/automate/agents/<id>/`).
+| Tool                           | Description                                |
+| ------------------------------ | ------------------------------------------ |
+| `gitlab_list_agents`           | Search agents in the global AI Catalog     |
+| `gitlab_get_agent`             | Get agent details by ID                    |
+| `gitlab_list_project_agents`   | List agents enabled for a project          |
+| `gitlab_enable_project_agent`  | Enable an agent in a project               |
+| `gitlab_disable_project_agent` | Disable an agent in a project              |
+| `gitlab_list_flows`            | Search flows in the global AI Catalog      |
+| `gitlab_get_flow`              | Get flow details by ID                     |
+| `gitlab_list_project_flows`    | List flows enabled for a project           |
+| `gitlab_enable_project_flow`   | Enable a flow in a project                 |
+| `gitlab_disable_project_flow`  | Disable a flow in a project                |
+| `gitlab_execute_project_flow`  | Execute a flow via DWS REST API            |
+| `gitlab_get_flow_definition`   | Get flow YAML config (inputs, components)  |
+| `gitlab_get_workflow_status`   | Monitor workflow execution status and logs |
 
-## Agent picker UX
+### Dynamic Refresh
 
-Agents appear in:
+After enabling or disabling an agent/flow, the plugin automatically refreshes the
+agent list. Restart opencode to update the `@` menu.
 
-- **`/agents` slash command** — shows all agents with `[GitLab Foundational Agent]` or `[GitLab Custom Agent]` labels
-- **Tab agent switcher** — switch the active agent for the current session
-- **Session header** — shows the active agent name
+### Vendored Foundational Flow Configs
 
-## Self-hosted GitLab
+Foundational flow definitions (from `gitlab-org/modelops/applied-ml/code-suggestions/ai-assist`)
+are vendored and embedded at build time. This provides flow input schemas for
+foundational flows whose configs are not available via the GitLab API.
 
-For OAuth-based auth, the `enterpriseUrl` from `opencode-gitlab-auth` is used automatically.
+## Agent Types
 
-For PAT-based auth on self-hosted instances, set:
+### Foundational Agents
 
-```bash
-export GITLAB_INSTANCE_URL=https://your-instance.com
-```
+Built-in GitLab agents. Appear in `/agents` with `[GitLab Foundational Agent]` label.
 
-## Logging
+### Custom Agents
 
-The plugin writes debug logs to:
+User-defined agents from the AI Catalog. Appear in `/agents` with `[GitLab Custom Agent]` label.
 
-```
-~/.local/share/opencode/log/gitlab-dap.log
-```
+### Flows (Foundational & Custom)
 
-Useful for debugging agent discovery issues.
+Multi-step workflows. Appear in `@` menu with `[GitLab Flow]` label. Executed via subagent dispatch.
 
-## Architecture
+### External Agents
 
-```
-Plugin init
-  └─ readAuth()          reads ~/.local/share/opencode/auth.json
-  └─ GitLabModelCache    reads ~/.cache/opencode/gitlab-workflow-model-cache.json
-  └─ fetchCatalogAgents()
-       ├─ aiFoundationalChatAgents (GraphQL) → foundational agents
-       └─ aiCatalogConfiguredItems (GraphQL) → custom agents
-            └─ aiCatalogAgentFlowConfig (GraphQL) → per-agent flow config YAML
-  └─ config hook         mutates cfg.agent in-place
-       └─ Agent.Service reads the same config object → agents appear in picker
-
-Per prompt (via gitlab-ai-provider):
-  └─ providerOptions.gitlab.workflowDefinition → DWS workflow type
-  └─ providerOptions.gitlab.flowConfig         → custom agent flow config
-  └─ providerOptions.gitlab.aiCatalogItemVersionId → links session in GitLab UI
+Third-party agents (Claude Code, Codex, etc.) are excluded — they work via CI/CD triggers,
+not through opencode.
+
+## Flow Definition Lookup
+
+The plugin uses a 3-tier strategy to fetch flow YAML configs:
+
+| Tier | Source                                          | Used For           |
+| ---- | ----------------------------------------------- | ------------------ |
+| 1    | Vendored configs (`vendor/foundational-flows/`) | Foundational flows |
+| 2    | `FlowVersion.definition` GraphQL field          | Custom flows       |
+| 3    | `aiCatalogAgentFlowConfig` GraphQL query        | Custom agents      |
+
+## Self-Hosted GitLab
+
+For OAuth-based auth, the `enterpriseUrl` from `opencode-gitlab-auth` is used automatically.
+
+For PAT-based auth:
+
+```bash
+export GITLAB_INSTANCE_URL=https://your-instance.com
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
-bun install
+npm install
+npm test          # Run tests (48 tests)
+npm run build     # Build (auto-runs vendor:generate)
+npm run type-check
+```
+
+### Vendor Scripts
 
-# Run tests
-npm test
+```bash
+npm run vendor:update    # Fetch flow configs from gitlab.com API
+npm run vendor:generate  # Generate TypeScript from vendored YAMLs
+npm run vendor           # Both: update + generate
+```
 
-# Build dist
+To update vendored configs when DWS releases new flow versions:
+
+```bash
+npm run vendor
 npm run build
+git add vendor/ src/generated/
+git commit -m "chore: update vendored foundational flow definitions"
+```
 
-# Type check
-npm run type-check
+## Architecture
+
+```
+Plugin init
+  ├─ readAuth()              reads ~/.local/share/opencode/auth.json
+  ├─ GitLabModelCache        reads model cache (no network call)
+  ├─ fetchCatalogAgents()
+  │    ├─ aiFoundationalChatAgents (GraphQL) → foundational agents
+  │    └─ aiCatalogConfiguredItems (GraphQL) → custom agents + flows
+  │         └─ aiCatalogAgentFlowConfig (GraphQL) → flow config YAML
+  ├─ config hook             injects agents (primary) + flows (subagent)
+  ├─ chat.message hook       intercepts @flow mentions → subagent dispatch
+  └─ tool hook               13 DAP tools
+
+Flow execution (@FlowName):
+  ├─ chat.message hook       replaces AgentPart with subagent instructions
+  ├─ Primary agent           dispatches Task subagent
+  ├─ Subagent Step 1         gitlab_get_flow_definition → read inputs
+  ├─ Subagent Step 2         GitLab tools → gather input values
+  ├─ Subagent Step 3         gitlab_execute_project_flow → POST to DWS
+  └─ Subagent Step 4         gitlab_get_workflow_status → confirm started
+
+Enable/disable:
+  └─ refreshAgents()         clears cache, re-fetches, updates cfg.agent
 ```
 
 ## License