# AGENTS.md

## WICHTIG: opencode-models-discovery ist fehlerhaft

Das existierende Plugin `opencode-models-discovery` ist **fehlfunktionell** und wurde **niemals** erfolgreich getestet. Alle bisherigen Versuche, es zu installieren und zu nutzen, schlugen fehl (AggregateError, Module Resolution Errors, etc.).

**Wir verwenden `opencode-models-discovery` NICHT.** Es muss deinstalliert und nicht mehr referenziert werden (passiert: aus `~/.opencode` entfernt, keine Config-Referenzen mehr).

## Ziel

Wir bauen ein **neues OpenCode v2 Plugin** von Grund auf (`opencode-openai-discovery`), das:
- Einen OpenAI-kompatiblen API-Endpunkt abfragt (`GET /v1/models`)
- Entdeckte Modelle automatisch in OpenCode registriert
- Sauber über die opencode v2 Plugin API (`@opencode/plugin`) funktioniert

**Status: FUNKTIONIERT** – alle 900 Gateway-Modelle erscheinen als `OmniRoute/*` in `opencode models`. Commit `511d2ea`.

## Projektstruktur

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

## 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; für globale Verfügbarkeit: `~/.opencode/plugins/` (gleiche Struktur) oder `plugins`-Array in der Config (v2-Schema: `{ "package": "..." }` Strings)
- **Config Format:** v2 verwendet `providers` (Plural), `package: "aisdk:..."`

## API-Endpunkt

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

## Erkenntnisse aus dem Debugging (kritisch für künftige Agenten)

### 1. `modelsDiscovery` existiert NICHT im v2-Schema
Das Feld `modelsDiscovery: { enabled: true }` in der Provider-Config war eine Erfindung des defekten `opencode-models-discovery`-Plugins. OpenCode v2 kennt es nicht (verifiziert am `@opencode/schema`). Konfig-Provider erscheinen im Provider-Index nur mit einem nicht-leeren `models`-Record – daher wurde OmniRoute initial nie instanziiert.

### 2. Provider-Transform läuft VOR dem Config-Provider-Load
`ctx.provider.transform(editor)` sieht nur die ~230 Katalog-Provider von models.dev, nicht die Config-Provider. `editor.models.set(providerID, ...)` auf einen nicht existierenden Provider ist ein **stilles No-Op**. Lösung: Provider per `editor.add({ info, models })` selbst erstellen, falls `editor.get(providerID)` nichts liefert.

### 3. Model.Info-Schema: alle Pflichtfelder setzen, sonst stiller Verlust
OpenCode verwirft Models OHNE Fehlermeldung aus dem Index, wenn Schema-Felder fehlen. Erforderlich pro Model:
```ts
{
  id, modelID, providerID, name,
  capabilities: { tools, input: [], output: [] },
  variants: [],
  cost: [{ input, output, cache: { read, write } }],
  limit: { context, output },
  time: { released },
  status: "active",
  enabled: true,
}
```
Beachte: `limit` (SINGULAR), nicht `limits`. Die Fehler tauchen erst client-seitig als `InvalidRequestError: Missing key at ["data"][N][...]` auf – Index-N zeigt das N. verarbeitete (fehlgeschlagene) Model an.

### 4. Plugin wird lazy geladen
Der Plugin-Load wird getriggert, sobald ein Client (CLI/TUI) das Projektverzeichnis öffnet ("location services booted"). `opencode service restart` reicht manchmal nicht – hängende Server-Prozesse cache alte Plugin-Stände: `pkill -f "opencode serve"` + neuer CLI-Aufruf.

### 5. Hot-Reload
OpenCode watcht die Plugin-`index.ts` – Änderungen werden sofort neu geladen, kein Neustart nötig. Syntaxfehler im TS zeigen als `BuildMessage: Unexpected escape sequence` o.ä. im Log.

### 6. `opencode models` CLI
Zeigt ALLE verfügbaren Modelle (nicht paginiert; die anfangs sichtbaren 10 `opencode/*`-Modelle kamen vom OpenCode-Zen-Katalog, nicht von uns). Der Server-Port steht in der Log-Datei; die API braucht Auth (nicht einfach curl-bar ohne Token).

## Plugin API (v2) – bewährtes Muster

```typescript
import { Plugin, Model } from "@opencode/plugin";

export default Plugin.define({
  id: "opencode.openai-discovery",
  async setup(ctx) {
    // 1. fetch GET /v1/models
    // 2. Modelle auf volles Model.Info-Schema mappen (siehe oben)
    // 3. Registrieren:
    ctx.provider.transform((editor) => {
      const source = editor.get("OmniRoute");
      if (source) {
        // mergen:
        editor.models.set("OmniRoute", [...existing, ...newModels]);
      } else {
        // erstellen (package MUSS "aisdk:@ai-sdk/openai-compatible" sein):
        editor.add({
          info: {
            id: "OmniRoute",
            name: "OmniRoute",
            activation: "enabled",
            package: "aisdk:@ai-sdk/openai-compatible",
            settings: { baseURL, apiKey },
          } as never,
          models,
        });
      }
    });
  },
});
```

## Verifizierung

```bash
opencode models | grep -c "^OmniRoute/"   # → 900
```