# AGENTS.md

## Status

**FUNKTIONIERT** — das Plugin `opencode-openai-compatible-model-discovery` discovered ~900 Gateway-Modelle und registriert sie als `OmniRoute/*` in OpenCode.

## Ziel

OpenCode v2 Plugin (`opencode-openai-compatible-model-discovery`), das:
- Einen OpenAI-kompatiblen API-Endpunkt abfragt (`GET /v1/models`)
- Entdeckte Modelle automatisch in OpenCode registriert
- **Autark funktioniert — keine Config-Datei nötig**

## Projektstruktur

```
.
├── AGENTS.md                       # Diese Datei
├── README.md                       # Doku für Menschen (Installation)
└── .opencode/plugins/
    └── opencode-openai-compatible-model-discovery/
        ├── index.ts                # Plugin-Code (TypeScript, ESM)
        ├── package.json            # Plugin Package-Metadata
        └── tsconfig.json           # TypeScript-Konfiguration
```

> **Keine `opencode.jsonc` nötig!** Das Plugin ist selbstständig — es erstellt den `OmniRoute`-Provider per `editor.add()` selbst.

## Wichtige Infos

- **OpenCode Version:** v2.0.32
- **Plugin API:** `@opencode/plugin` (v2.x) — NICHT `@opencode-ai/plugin` (v1)
- **Plugin Discovery:** Projektlokale Plugins in `.opencode/plugins/` werden automatisch geladen. Global: `~/.opencode/plugins/` (gleiche Struktur).
- **Keine Config nötig:** Das Plugin erstellt den Provider selbst — weder lokale noch globale `opencode.jsonc` wird benötigt.

## API-Endpunkt

```
BASE_URL: http://localhost:20128/v1
API_KEY:  sk-e9ac58c0b78cd2bc-f17d3e-f6beea67
MODELS:   GET /v1/models   → 900 Modelle
```

## Erkenntnisse (kritisch für künftige Agenten)

### 1. Provider selbst erstellen, nicht transformieren
`ctx.provider.transform(editor)` mit `editor.models.set()` auf einem nicht-existierenden Provider ist ein **stilles No-Op**. Immer `editor.add({ info, models })` verwenden — das Plugin erstellt den `OmniRoute`-Provider selbst.

### 2. Model.Info-Schema: alle Pflichtfelder setzen, sonst stiller Verlust
OpenCode verwirft Models OHNE Fehlermeldung aus dem Index, wenn Schema-Felder fehlen.

```
{
  id, modelID, providerID, name,
  capabilities: { tools, input: [], output: [] },
  variants: [],
  cost: [{ input, output, cache: { read, write } }],
  limit: { context, output },
  time: { released },
  status: "active",
  enabled: true,
}
```

Wichtig: `limit` (SINGULAR), nicht `limits`. Fehler erscheinen client-seitig als `InvalidRequestError: Missing key at ["data"][N][...]` — der Index N zeigt das fehlgeschlagene Model.

### 3. Plugin-Reload
Der Plugin-Load wird getriggert, sobald ein Client das Projektverzeichnis öffnet. Bei Änderungen: `pkill -f opencode` (Server killen) + CLI-Aufruf. Syntaxfehler im TS zeigen als `BuildMessage` im Log.

### 4. Hot-Reload
OpenCode watcht die Plugin-`index.ts` — Änderungen werden sofort neu geladen.

## Plugin API (v2)

Das Muster steht in `.opencode/plugins/opencode-openai-compatible-model-discovery/index.ts`.

Kernlogik:
1. `fetch(\`${BASE_URL}/models\`)` — Modellliste vom Gateway holen
2. Auf **volles Model.Info-Schema** mappen (→ Punkt 2)
3. **`editor.add()`** aufrufen, falls `editor.get("OmniRoute")` null ist — das Plugin erstellt den Provider selbst
4. Falls der Provider bereits existiert, merget es die Modelle

## Verifizierung

```bash
opencode plugin list    # → opencode.openai-compatible-model-discovery  local
opencode models | grep -c "^OmniRoute/"   # → ~900
```