@mcowger/opencode-plexus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Matt Cowger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @mcowger/opencode-plexus
+
+An [OpenCode](https://opencode.ai) plugin that exposes a self-hosted [Plexus](https://github.com/mcowger/plexus) instance as a first-class `plexus` provider with **dynamic model discovery**.
+
+Models are fetched live from your Plexus instance's `/v1/models` endpoint on every startup, and cached on-disk so OpenCode starts cleanly even when the network is unavailable.
+
+---
+
+## Installation
+
+```bash
+opencode plugin --global @mcowger/opencode-plexus
+```
+
+---
+
+## Setup
+
+### Option A — Interactive auth (recommended)
+
+```bash
+opencode auth login --provider plexus
+```
+
+You will be prompted for:
+- **Plexus base URL** — e.g. `https://plexus.example.com`
+- **API key** — the key used to authenticate chat-completion requests
+
+OpenCode will probe the URL, then persist both values in its global config so you only need to do this once.
+
+### Option B — Environment variables
+
+```bash
+export PLEXUS_BASE_URL=https://plexus.example.com
+export PLEXUS_API_KEY=sk-...
+```
+
+Environment variables take precedence over the stored config.
+
+### Option C — Manual `opencode.json`
+
+```jsonc
+{
+  "provider": {
+    "plexus": {
+      "options": {
+        "baseURL": "https://plexus.example.com",
+        "apiKey": "sk-..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## How it works
+
+1. On startup the plugin's `config` hook fires.
+2. It reads `PLEXUS_BASE_URL` / `PLEXUS_API_KEY` (or the stored options) and calls `/v1/models` on your Plexus instance.
+3. The response is transformed into OpenCode's model schema and registered under the `plexus` provider.
+4. The transformed list is cached in OpenCode's state directory (`~/.local/share/opencode/plugins/plexus/`).
+5. On the next startup the cache is loaded synchronously before the live refresh completes, so the model picker is always populated.
+
+> **Note:** `/v1/models` does not require an API key. The API key is only required for chat-completion requests. You can run the plugin without an API key if you only want to browse models.
+
+---
+
+## Model discovery details
+
+| Plexus field | OpenCode model field |
+|---|---|
+| `id` | `id` (also dict key) |
+| `name` | `name` |
+| `context_length` / `top_provider.context_length` | `limit.context` |
+| `top_provider.max_completion_tokens` | `limit.output` (fallback: `ceil(context × 0.2)`) |
+| `pricing.prompt` / `.completion` | `cost.input` / `.output` (per-million tokens) |
+| `pricing.input_cache_read` / `.input_cache_write` | `cost.cache_read` / `.cache_write` |
+| `architecture.input_modalities` | `modalities.input` (`file` → `pdf`) |
+| `architecture.output_modalities` | `modalities.output` |
+| `output_modalities` present but does not include `text` | **model skipped** (filters image-generation, embedding, TTS, and other non-chat output types) |
+| no `architecture` field and id matches `embedding`, `tts`, `whisper`, `image-*`, `dream`, etc. | **model skipped** (bare-stub non-chat models with no metadata) |
+| `supported_parameters` includes `tools` | `tool_call: true` |
+| `supported_parameters` includes `reasoning` / `include_reasoning` / `reasoning_effort` | `reasoning: true` |
+| `supported_parameters` includes `temperature` | `temperature: true` |
+| any non-text input modality | `attachment: true` |
+
+---
+
+## Multi-API escape hatch
+
+By default this plugin uses `@ai-sdk/openai-compatible` (the OpenAI-compatible route) for all models. For Plexus-proxied models that use a different API wire format (e.g. Anthropic messages), add a **sibling provider** manually in your `opencode.json`:
+
+```jsonc
+{
+  "provider": {
+    "plexus": {
+      // managed by this plugin — do not edit models here
+    },
+    "plexus-anthropic": {
+      "npm": "@ai-sdk/anthropic",
+      "options": {
+        "baseURL": "https://plexus.example.com"
+      },
+      "models": {
+        "claude-sonnet-4-6": {
+          "name": "Claude Sonnet 4.6 (via Plexus, Anthropic wire)",
+          "attachment": true,
+          "reasoning": true,
+          "tool_call": true,
+          "cost": { "input": 3.0, "output": 15.0 },
+          "limit": { "context": 1000000, "output": 128000 }
+        }
+      }
+    }
+  }
+}
+```
+
+The `plexus` provider itself only manages the OpenAI-compatible route.
+
+---
+
+## Troubleshooting
+
+**Models don't appear after setup**
+- Check that `PLEXUS_BASE_URL` is set or that you completed `opencode auth login --provider plexus`.
+- Verify reachability: `curl https://plexus.example.com/v1/models`.
+
+**Cache location**
+The model cache lives under OpenCode's own state directory:
+
+```
+~/.local/share/opencode/plugins/plexus/models-cache.json
+~/.local/share/opencode/plugins/plexus/models-raw.json
+```
+
+Deleting OpenCode's state directory (the documented reset path) also clears this cache.
+
+**API key vs base URL**
+- `PLEXUS_API_KEY` (and the stored key) is used **only** for chat-completion requests.
+- `/v1/models` is fetched without authentication, so the model picker works even if you haven't set an API key yet.

package/dist/index.js

@@ -0,0 +1,441 @@
+// @bun
+// src/constants.ts
+var PLEXUS_PROVIDER_ID = "plexus";
+var PLEXUS_PROVIDER_NAME = "Plexus";
+var PLEXUS_PLUGIN_ID = "@mcowger/opencode-plexus";
+var PLEXUS_LOG_SERVICE = "opencode-plexus";
+var OPENAI_COMPATIBLE_NPM = "@ai-sdk/openai-compatible";
+var ENV_BASE_URL = "PLEXUS_BASE_URL";
+var ENV_API_KEY = "PLEXUS_API_KEY";
+var MODELS_FETCH_TIMEOUT_MS = 1e4;
+var REFRESH_TTL_MS = 60000;
+var DEFAULT_CONTEXT = 8192;
+var PLACEHOLDER_MODEL_ID = "plexus-unconfigured";
+
+// src/cache.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var PLUGIN_SUBDIR = join("plugins", "plexus");
+var CACHE_FILE = "models-cache.json";
+var RAW_FILE = "models-raw.json";
+var resolvedDir = null;
+function fallbackDir() {
+  return join(homedir(), ".local", "share", "opencode", PLUGIN_SUBDIR);
+}
+async function getDir(client) {
+  if (resolvedDir)
+    return resolvedDir;
+  try {
+    const res = await client.path.get();
+    const data = res?.data;
+    const state = typeof data?.state === "string" && data.state ? data.state : undefined;
+    if (state) {
+      resolvedDir = join(state, PLUGIN_SUBDIR);
+      return resolvedDir;
+    }
+  } catch {}
+  resolvedDir = fallbackDir();
+  return resolvedDir;
+}
+function syncCachePath() {
+  return join(fallbackDir(), CACHE_FILE);
+}
+function readCachedModelsSync() {
+  try {
+    const path = syncCachePath();
+    if (!existsSync(path))
+      return null;
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.models === "object" && !Array.isArray(parsed.models)) {
+      return parsed.models;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function readCachedModels(client) {
+  try {
+    const dir = await getDir(client);
+    const content = await readFile(join(dir, CACHE_FILE), "utf8");
+    const parsed = JSON.parse(content);
+    if (parsed && typeof parsed.models === "object" && !Array.isArray(parsed.models)) {
+      return parsed.models;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeCache(client, models, raw) {
+  try {
+    const dir = await getDir(client);
+    await mkdir(dir, { recursive: true });
+    const cache = { models, timestamp: Date.now() };
+    await writeFile(join(dir, CACHE_FILE), JSON.stringify(cache, null, 2) + `
+`, "utf8");
+    if (raw !== undefined) {
+      await writeFile(join(dir, RAW_FILE), JSON.stringify(raw, null, 2) + `
+`, "utf8");
+    }
+    try {
+      const syncDir = fallbackDir();
+      mkdirSync(syncDir, { recursive: true });
+      writeFileSync(join(syncDir, CACHE_FILE), JSON.stringify(cache, null, 2) + `
+`, "utf8");
+    } catch {}
+  } catch {}
+}
+
+// src/config-store.ts
+import { createOpencodeClient } from "@opencode-ai/sdk/v2/client";
+
+// src/url.ts
+function trimURL(s) {
+  return s.trim().replace(/\/+$/, "");
+}
+function apiBase(baseURL) {
+  const next = trimURL(baseURL);
+  if (!next)
+    return "";
+  return next.endsWith("/v1") ? next : `${next}/v1`;
+}
+function modelsUrl(baseURL) {
+  const base = apiBase(baseURL);
+  return base ? `${base}/models` : "";
+}
+
+// src/config-store.ts
+function getV1ClientConfig(input) {
+  return input._client?.getConfig?.() ?? {};
+}
+function createV2Client(serverUrl, input) {
+  const v1Config = getV1ClientConfig(input);
+  return createOpencodeClient({
+    baseUrl: serverUrl.toString(),
+    fetch: v1Config.fetch,
+    headers: v1Config.headers,
+    throwOnError: true
+  });
+}
+function resolveConfig(provider) {
+  const envBaseURL = process.env[ENV_BASE_URL];
+  const envApiKey = process.env[ENV_API_KEY];
+  const optBaseURL = typeof provider?.options?.baseURL === "string" ? trimURL(provider.options.baseURL) : undefined;
+  const optApiKey = typeof provider?.options?.apiKey === "string" ? provider.options.apiKey.trim() : undefined;
+  const baseURL = (envBaseURL ? trimURL(envBaseURL) : undefined) || optBaseURL || undefined;
+  const apiKey = (envApiKey ? envApiKey.trim() : undefined) || optApiKey || undefined;
+  return { baseURL: baseURL || undefined, apiKey: apiKey || undefined };
+}
+async function persistToGlobalConfig(serverUrl, client, baseURL, apiKey) {
+  const v2 = createV2Client(serverUrl, client);
+  await v2.global.config.update({
+    config: {
+      provider: {
+        [PLEXUS_PROVIDER_ID]: {
+          options: { baseURL, apiKey }
+        }
+      }
+    }
+  });
+}
+
+// src/log.ts
+function createLogger(client) {
+  function log(level, message) {
+    client.app.log({ body: { service: PLEXUS_LOG_SERVICE, level, message } }).catch(() => {});
+  }
+  return {
+    info: (message) => log("info", message),
+    warn: (message) => log("warn", message),
+    error: (message) => log("error", message)
+  };
+}
+
+// src/models.ts
+var REASONING_PARAMS = new Set(["reasoning", "include_reasoning", "reasoning_effort"]);
+function parsePrice(value) {
+  if (!value)
+    return 0;
+  const n = parseFloat(value);
+  return Number.isNaN(n) ? 0 : n;
+}
+function mapModality(m) {
+  switch (m) {
+    case "text":
+      return "text";
+    case "image":
+      return "image";
+    case "audio":
+      return "audio";
+    case "video":
+      return "video";
+    case "file":
+    case "pdf":
+      return "pdf";
+    default:
+      return null;
+  }
+}
+function buildInputModalities(model) {
+  const raw = model.architecture?.input_modalities ?? [];
+  const mapped = raw.map(mapModality).filter((m) => m !== null);
+  return mapped.length > 0 ? [...new Set(mapped)] : ["text"];
+}
+var NON_CHAT_ID_PATTERN = /embedding|embed|tts|whisper|image-[0-9]|image\b.*gen|diffusion|dall-e|stable-diff|sdxl|dream/i;
+function buildOutputModalities(model) {
+  const raw = model.architecture?.output_modalities;
+  if (raw !== undefined) {
+    if (!raw.includes("text"))
+      return null;
+    const mapped = raw.map(mapModality).filter((m) => m !== null);
+    return mapped.length > 0 ? [...new Set(mapped)] : ["text"];
+  }
+  if (NON_CHAT_ID_PATTERN.test(model.id))
+    return null;
+  return ["text"];
+}
+function buildModels(models) {
+  const result = {};
+  for (const m of models) {
+    if (!m.id)
+      continue;
+    const outputModalities = buildOutputModalities(m);
+    if (outputModalities === null)
+      continue;
+    const inputModalities = buildInputModalities(m);
+    const params = m.supported_parameters ?? [];
+    const contextLength = (typeof m.context_length === "number" && m.context_length > 0 ? m.context_length : undefined) ?? (typeof m.top_provider?.context_length === "number" && m.top_provider.context_length > 0 ? m.top_provider.context_length : undefined) ?? DEFAULT_CONTEXT;
+    const maxOutput = (typeof m.top_provider?.max_completion_tokens === "number" && m.top_provider.max_completion_tokens > 0 ? m.top_provider.max_completion_tokens : undefined) ?? Math.ceil(contextLength * 0.2);
+    const promptPrice = parsePrice(m.pricing?.prompt);
+    const completionPrice = parsePrice(m.pricing?.completion);
+    const cacheReadPrice = parsePrice(m.pricing?.input_cache_read);
+    const cacheWritePrice = parsePrice(m.pricing?.input_cache_write);
+    const hasCachePricing = cacheReadPrice > 0 || cacheWritePrice > 0;
+    const hasNonTextInput = inputModalities.some((mod) => mod !== "text");
+    const entry = {
+      id: m.id,
+      name: m.name ?? m.id,
+      limit: {
+        context: contextLength,
+        output: maxOutput
+      },
+      modalities: {
+        input: inputModalities,
+        output: outputModalities
+      },
+      ...promptPrice > 0 || completionPrice > 0 ? {
+        cost: {
+          input: promptPrice,
+          output: completionPrice,
+          ...hasCachePricing ? { cache_read: cacheReadPrice, cache_write: cacheWritePrice } : {}
+        }
+      } : {},
+      ...params.includes("tools") ? { tool_call: true } : {},
+      ...params.some((p) => REASONING_PARAMS.has(p)) ? { reasoning: true } : {},
+      ...params.includes("temperature") ? { temperature: true } : {},
+      ...hasNonTextInput ? { attachment: true } : {}
+    };
+    result[m.id] = entry;
+  }
+  return result;
+}
+
+// src/plexus-client.ts
+import { z } from "zod";
+var PlexusModelArchitectureSchema = z.object({
+  modality: z.string().optional(),
+  input_modalities: z.array(z.string()).optional(),
+  output_modalities: z.array(z.string()).optional(),
+  tokenizer: z.string().optional(),
+  instruct_type: z.string().nullable().optional()
+}).passthrough();
+var PlexusModelPricingSchema = z.object({
+  prompt: z.string().optional(),
+  completion: z.string().optional(),
+  input_cache_read: z.string().optional(),
+  input_cache_write: z.string().optional()
+}).passthrough();
+var PlexusTopProviderSchema = z.object({
+  context_length: z.number().nullable().optional(),
+  max_completion_tokens: z.number().nullable().optional(),
+  is_moderated: z.boolean().optional()
+}).passthrough();
+var PlexusApiModelSchema = z.object({
+  id: z.string(),
+  object: z.string().optional(),
+  created: z.number().optional(),
+  owned_by: z.string().optional(),
+  preferred_api: z.union([z.string(), z.array(z.string())]).optional(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  context_length: z.number().nullable().optional(),
+  architecture: PlexusModelArchitectureSchema.optional(),
+  pricing: PlexusModelPricingSchema.optional(),
+  supported_parameters: z.array(z.string()).optional(),
+  top_provider: PlexusTopProviderSchema.optional(),
+  pi_provider: z.string().optional(),
+  pi_model: z.string().optional()
+}).passthrough();
+var PlexusApiResponseSchema = z.object({
+  object: z.string(),
+  data: z.array(PlexusApiModelSchema)
+});
+async function fetchPlexusModels(baseURL, apiKey) {
+  const url = modelsUrl(baseURL);
+  if (!url)
+    throw new Error("Plexus: cannot build models URL from an empty baseURL");
+  const headers = {
+    Accept: "application/json"
+  };
+  if (apiKey) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+  const response = await fetch(url, {
+    headers,
+    signal: AbortSignal.timeout(MODELS_FETCH_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    throw new Error(`Plexus models fetch failed: HTTP ${response.status} ${response.statusText} (${url})`);
+  }
+  const json = await response.json();
+  const parsed = PlexusApiResponseSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new Error(`Plexus models response did not match expected schema: ${parsed.error.message}`);
+  }
+  const raw = parsed.data;
+  return { models: raw.data ?? [], raw };
+}
+
+// src/plugin.ts
+var lastRefresh = null;
+async function refreshModels(client, baseURL, apiKey) {
+  if (lastRefresh && Date.now() - lastRefresh.at < REFRESH_TTL_MS) {
+    return lastRefresh.models;
+  }
+  const { models: apiModels, raw } = await fetchPlexusModels(baseURL, apiKey);
+  const built = buildModels(apiModels);
+  lastRefresh = { at: Date.now(), models: built };
+  writeCache(client, built, raw).catch(() => {});
+  return built;
+}
+var PlexusProviderPlugin = async (ctx) => {
+  const { client } = ctx;
+  const log = createLogger(client);
+  return {
+    config: async (cfg) => {
+      cfg.provider ??= {};
+      const existing = cfg.provider[PLEXUS_PROVIDER_ID] ?? {};
+      const existingOptions = typeof existing["options"] === "object" && existing["options"] !== null ? existing["options"] : {};
+      const existingModels = typeof existing["models"] === "object" && existing["models"] !== null ? existing["models"] : null;
+      const { baseURL, apiKey } = resolveConfig(existing);
+      const cachedSync = readCachedModelsSync();
+      const merged = {
+        ...existing,
+        name: existing["name"] ?? PLEXUS_PROVIDER_NAME,
+        npm: existing["npm"] ?? OPENAI_COMPATIBLE_NPM,
+        options: {
+          ...existingOptions,
+          ...baseURL ? { baseURL: apiBase(baseURL) } : {},
+          ...apiKey ? { apiKey } : {}
+        },
+        models: existingModels ?? cachedSync ?? {
+          [PLACEHOLDER_MODEL_ID]: {
+            id: PLACEHOLDER_MODEL_ID,
+            name: "Plexus (run /connect to configure)",
+            limit: { context: 1024, output: 1024 },
+            modalities: { input: ["text"], output: ["text"] }
+          }
+        }
+      };
+      if (baseURL) {
+        try {
+          const built = await refreshModels(client, baseURL, apiKey);
+          merged["models"] = { ...built, ...existingModels ?? {} };
+          log.info(`Loaded ${Object.keys(built).length} plexus models from ${baseURL}`);
+        } catch (e) {
+          log.warn(`Live model refresh failed, using cache: ${String(e)}`);
+          const cached = await readCachedModels(client);
+          if (cached) {
+            merged["models"] = { ...cached, ...existingModels ?? {} };
+          }
+        }
+      } else {
+        log.info("Plexus baseURL not configured; skipping live refresh");
+      }
+      cfg.provider[PLEXUS_PROVIDER_ID] = merged;
+    },
+    auth: {
+      provider: PLEXUS_PROVIDER_ID,
+      async loader(getAuth, providerInfo) {
+        const auth = await getAuth();
+        const { baseURL, apiKey } = resolveConfig(providerInfo);
+        const key = (auth?.type === "api" ? auth.key : undefined) ?? apiKey;
+        return {
+          ...baseURL ? { baseURL: apiBase(baseURL) } : {},
+          ...key ? { apiKey: key } : {}
+        };
+      },
+      methods: [
+        {
+          type: "api",
+          label: "Plexus API key",
+          prompts: [
+            {
+              type: "text",
+              key: "baseURL",
+              message: "Plexus base URL",
+              placeholder: "https://plexus.example.com",
+              validate: (v) => trimURL(v) ? undefined : "URL is required"
+            }
+          ],
+          async authorize(inputs = {}) {
+            const baseURL = trimURL(inputs["baseURL"] ?? "");
+            const apiKey = (inputs["apiKey"] ?? "").trim();
+            if (!baseURL || !apiKey)
+              return { type: "failed" };
+            try {
+              await fetchPlexusModels(baseURL);
+            } catch (e) {
+              log.error(`Plexus URL probe failed at ${baseURL}: ${String(e)}`);
+              return { type: "failed" };
+            }
+            try {
+              await persistToGlobalConfig(ctx.serverUrl, client, baseURL, apiKey);
+            } catch (e) {
+              log.error(`Failed to persist Plexus config: ${String(e)}`);
+            }
+            lastRefresh = null;
+            return { type: "success", provider: PLEXUS_PROVIDER_ID, key: apiKey };
+          }
+        }
+      ]
+    }
+  };
+};
+
+// src/index.ts
+var plugin2 = {
+  id: PLEXUS_PLUGIN_ID,
+  server: PlexusProviderPlugin
+};
+var src_default = plugin2;
+export {
+  src_default as default,
+  buildModels,
+  REFRESH_TTL_MS,
+  PlexusProviderPlugin,
+  PLEXUS_PROVIDER_NAME,
+  PLEXUS_PROVIDER_ID,
+  PLEXUS_PLUGIN_ID,
+  PLEXUS_LOG_SERVICE,
+  PLACEHOLDER_MODEL_ID,
+  OPENAI_COMPATIBLE_NPM,
+  MODELS_FETCH_TIMEOUT_MS,
+  ENV_BASE_URL,
+  ENV_API_KEY,
+  DEFAULT_CONTEXT
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mcowger/opencode-plexus",
+  "version": "0.1.0",
+  "description": "OpenCode plugin: Plexus provider with dynamic model discovery",
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/index.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir=dist --target=bun --format=esm --packages=external",
+    "watch": "bun build src/index.ts --outdir=dist --target=bun --format=esm --packages=external --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test ./tests",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.15.7",
+    "@opencode-ai/sdk": "^1.15.7",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "typescript": "^6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^6.0.3"
+  }
+}