opencode-gitlab-dap 1.0.0 → 1.1.0

package/README.md

@@ -1,235 +1,132 @@
 # opencode-gitlab-dap
 
-OpenCode plugin for GitLab Duo Agent Platform (DAP) workflow model discovery and selection.
+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.
 
----
+## Requirements
 
-## Overview
-
-This plugin connects OpenCode to the GitLab Duo Agent Platform so users can discover and select workflow models configured for their GitLab namespace. It detects the current GitLab project, queries the DAP API for available models, caches the user's choice per project, and surfaces a TUI selection prompt when multiple models are available.
-
----
-
-## Architecture
-
-```mermaid
-sequenceDiagram
-    participant TUI as OpenCode TUI
-    participant Server as OpenCode Server
-    participant Plugin as gitlab-dap Plugin
-    participant Cache as GitLabModelCache
-    participant API as GitLab DAP API
-
-    TUI->>Server: POST /plugin/gitlab/discover
-    Server->>Plugin: route handler
-    Plugin->>Cache: check cached selection
-    alt cache hit
-        Plugin-->>Server: { status: "cached", model }
-    else no cache
-        Plugin->>API: detect project + discover models
-        API-->>Plugin: DiscoveredModels
-        alt pinned model
-            Plugin-->>Server: { status: "pinned", model }
-        else multiple models
-            Plugin->>Server: askUser via plugin-select bus
-            Server->>TUI: render selection prompt
-            TUI-->>Server: user picks model
-            Server-->>Plugin: selected ref
-            Plugin->>Cache: save selection
-            Plugin-->>Server: { status: "selected", model }
-        else default only
-            Plugin-->>Server: { status: "default", model }
-        end
-    end
-    Server-->>TUI: JSON response
-```
-
----
+- 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)
 
 ## Install
 
-This plugin is bundled internally with OpenCode. It is not installed as a standalone package. The plugin entry is registered automatically and exposes routes under the `/plugin/gitlab/` prefix.
-
----
-
-## Configure
-
-Authentication is resolved in this order:
-
-1. Request headers (`x-plugin-auth-token`, `x-plugin-auth-instance`)
-2. OpenCode auth store via `input.getAuth("gitlab")` (OAuth or API key)
-3. Environment variables as fallback
-
-| Variable                 | Description                                             | Default              |
-| ------------------------ | ------------------------------------------------------- | -------------------- |
-| `GITLAB_INSTANCE_URL`    | Base URL of your GitLab instance                        | `https://gitlab.com` |
-| `GITLAB_TOKEN`           | Personal or project access token (when not using OAuth) | --                   |
-| `GITLAB_OAUTH_CLIENT_ID` | OAuth application ID for the OAuth flow                 | --                   |
-
-The plugin also reads `x-plugin-directory` from request headers to scope cache and project detection to a specific working directory.
-
----
-
-## Routes
-
-All routes are prefixed with `/plugin/gitlab`.
-
-### POST /discover
-
-Detect the GitLab project, query DAP for available models, and return the resolved model or prompt the user to pick one.
-
-**Request:**
-
-```json
-{ "fresh": true }
-```
-
-Set `fresh: true` to clear the cache and re-discover. The body is optional.
-
-**Response (pinned):**
+Add to your `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "status": "pinned",
-  "model": { "name": "Claude 4", "ref": "claude_4" }
+  "plugin": ["/path/to/opencode-gitlab-dap"]
 }
 ```
 
-**Response (asked then selected):**
+Or once published to npm:
 
-```json
-{
-  "status": "selected",
-  "model": { "name": "GPT-5", "ref": "gpt_5" }
-}
+```bash
+opencode plugin opencode-gitlab-dap
 ```
 
-**Response (no auth):**
-
-```json
-{
-  "status": "no_provider",
-  "error": "No auth token found"
-}
-```
+No further configuration needed. The plugin reads GitLab auth and model cache automatically.
 
-Possible `status` values: `pinned`, `cached`, `default`, `selected`, `dismissed`, `no_provider`, `no_models`, `error`.
+## How it works
 
----
+On every opencode startup the plugin:
 
-### POST /reply
+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
 
-Save a model selection directly, bypassing the interactive prompt.
+## Agent types
 
-**Request:**
+### Foundational agents
 
-```json
-{ "ref": "claude_4" }
-```
+Built-in GitLab agents available based on your project's Duo Workflow license:
 
-**Response:**
+| Agent            | Description                     |
+| ---------------- | ------------------------------- |
+| GitLab Duo       | General-purpose agentic chat    |
+| Planner          | Issue and project planning      |
+| Data Analyst     | GitLab data analysis (GLQL)     |
+| Security Analyst | Security vulnerability analysis |
 
-```json
-{ "ref": "claude_4", "name": "Claude 4" }
-```
+These are fetched via `aiFoundationalChatAgents` and are scoped to what's enabled for your project.
 
----
+### Custom agents
 
-### POST /clear
+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.
 
-Clear the cached discovery and selection for the current project.
+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>/`).
 
-**Response:**
+## Agent picker UX
 
-```json
-true
-```
+Agents appear in:
 
----
+- **`/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
 
-### GET /models
+## Self-hosted GitLab
 
-Return the current discovery state without triggering a new discovery.
+For OAuth-based auth, the `enterpriseUrl` from `opencode-gitlab-auth` is used automatically.
 
-**Response:**
+For PAT-based auth on self-hosted instances, set:
 
-```json
-{
-  "models": [
-    { "name": "Claude 4", "ref": "claude_4" },
-    { "name": "GPT-5", "ref": "gpt_5" }
-  ],
-  "pinned": null,
-  "default": { "name": "Claude 4", "ref": "claude_4" },
-  "switching": true
-}
+```bash
+export GITLAB_INSTANCE_URL=https://your-instance.com
 ```
 
----
-
-## Discovery flow
-
-The `discover` function resolves models through a priority chain:
-
-1. **No token** -- returns `no_provider` immediately.
-2. **Project detection** -- uses `GitLabProjectDetector` to find the namespace from the working directory. Fails with `no_provider` if no project is found.
-3. **DAP query** -- calls `GitLabModelDiscovery.discover()` with the namespace GID. Returns `no_models` if the API returns nothing.
-4. **Pinned** -- if the namespace has a pinned model, it is saved to cache and returned.
-5. **Cached** -- if a previous selection exists in `GitLabModelCache`, it is returned.
-6. **Asked** -- if selectable models exist and nothing is cached, the list is returned with `status: "asked"` so the route handler can prompt the user.
-7. **Default** -- if only a default model exists (no selectable list), it is saved and returned.
-8. **No models** -- fallthrough when none of the above match.
-
----
+## Logging
 
-## Selection flow
+The plugin writes debug logs to:
 
-When discovery returns `status: "asked"`, the route handler triggers an interactive prompt:
-
-1. The `/discover` route calls `askUser()` with the list of models.
-2. `askUser` sends a `POST` to the internal `plugin-select/ask` endpoint on the OpenCode server.
-3. The server forwards the selection prompt to the TUI.
-4. When the user picks a model, the response flows back through the same path.
-5. The selected `ref` is saved via `saveSelection()` into `GitLabModelCache`.
-6. Subsequent `/discover` calls return `status: "cached"` without prompting again.
-
-If the user dismisses the prompt, the response is `{ "status": "dismissed" }`.
-
----
+```
+~/.local/share/opencode/log/gitlab-dap.log
+```
 
-## Develop
+Useful for debugging agent discovery issues.
 
-### Build
+## Architecture
 
-```sh
-npm run build
+```
+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
 ```
 
-Uses [tsup](https://tsup.egoist.dev) to produce CJS, ESM, and `.d.ts` outputs in `dist/`.
+## Development
 
-### Test
+```bash
+# Install dependencies
+bun install
 
-```sh
+# Run tests
 npm test
-```
-
-Runs [Vitest](https://vitest.dev) against `test/`. Watch mode is available with `npm run test:watch`.
 
-### Lint and type-check
+# Build dist
+npm run build
 
-```sh
-npm run lint
+# Type check
 npm run type-check
 ```
 
-### Clean
-
-```sh
-npm run clean
-```
-
----
-
 ## License
 
-[MIT](./LICENSE)
+MIT