@mcowger/opencode-plexus 0.1.0 → 0.7.0

package/README.md

@@ -1,142 +1,196 @@
-# @mcowger/opencode-plexus
+# plexus-agent-plugins
 
-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**.
+Exposes models from a self-hosted [Plexus](https://github.com/mcowger/plexus) AI proxy as a first-class provider inside AI coding agents. Models appear in the agent's model picker with correct wire-protocol behavior, as if they were natively supported providers.
 
-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.
+## Supported agents
 
----
+| Package | Agent | npm |
+|---|---|---|
+| `plexus-pi` | [pi](https://github.com/earendil-works/pi) | `@mcowger/pi-plexus` |
+| `plexus-opencode` | [OpenCode](https://opencode.ai) | `@mcowger/opencode-plexus` |
+
+## Prerequisites
+
+- A running Plexus instance
 
 ## Installation
 
-```bash
-opencode plugin --global @mcowger/opencode-plexus
-```
+The built dist artifact is committed to the repo, so no build step is needed for any install method.
 
 ---
 
-## Setup
+### pi
 
-### Option A — Interactive auth (recommended)
+#### Option 1 — npm (recommended)
 
-```bash
-opencode auth login --provider plexus
+```sh
+cd ~/.pi/agent/extensions
+npm install @mcowger/pi-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
+#### Option 2 — git clone into the extensions directory
 
-OpenCode will probe the URL, then persist both values in its global config so you only need to do this once.
+```sh
+git clone https://github.com/mcowger/plexus-agent-plugins ~/.pi/agent/extensions/plexus-agent-plugins
+```
 
-### Option B — Environment variables
+#### Option 3 — git clone anywhere + settings.json
 
-```bash
-export PLEXUS_BASE_URL=https://plexus.example.com
-export PLEXUS_API_KEY=sk-...
+```sh
+git clone https://github.com/mcowger/plexus-agent-plugins ~/code/plexus-agent-plugins
 ```
 
-Environment variables take precedence over the stored config.
+Then register the path in `~/.pi/agent/settings.json`:
 
-### Option C — Manual `opencode.json`
-
-```jsonc
+```json
 {
-  "provider": {
-    "plexus": {
-      "options": {
-        "baseURL": "https://plexus.example.com",
-        "apiKey": "sk-..."
-      }
-    }
-  }
+  "extensions": [
+    "~/code/plexus-agent-plugins/packages/plexus-pi"
+  ]
 }
 ```
 
 ---
 
-## How it works
+### OpenCode
 
-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.
+#### Option 1 — npm (recommended)
 
-> **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.
+```sh
+npm install -g @mcowger/opencode-plexus
+```
 
----
+Then add the plugin to your `opencode.json`:
 
-## 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` |
+```json
+{
+  "plugins": ["@mcowger/opencode-plexus"]
+}
+```
 
----
+#### Option 2 — path reference
 
-## Multi-API escape hatch
+```sh
+git clone https://github.com/mcowger/plexus-agent-plugins ~/code/plexus-agent-plugins
+```
 
-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`:
+Then reference the built artifact in `opencode.json`:
 
-```jsonc
+```json
 {
-  "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 }
-        }
-      }
-    }
-  }
+  "plugins": ["~/code/plexus-agent-plugins/packages/plexus-opencode/dist/index.js"]
 }
 ```
 
-The `plexus` provider itself only manages the OpenAI-compatible route.
+---
+
+## First-time setup
+
+### pi
+
+Run inside pi:
+
+```
+/plexus login
+```
+
+You will be prompted for:
+
+- **Plexus base URL** — e.g. `https://plexus.example.com`
+- **Plexus API key**
+- **Default model** (optional)
+
+To force a model refresh:
+
+```
+/plexus refresh
+```
+
+### OpenCode
+
+Run inside OpenCode:
+
+```
+/connect
+```
+
+Select **Plexus** and enter your base URL and API key. Models are loaded immediately and cached for fast startup on subsequent sessions.
+
+You can also pre-configure via environment variables:
+
+```sh
+export PLEXUS_BASE_URL=https://plexus.example.com
+export PLEXUS_API_KEY=your-api-key
+```
 
 ---
 
-## Troubleshooting
+## Configuration files
+
+### pi
+
+```
+~/.pi/agent/extensions/plexus/
+  config.json                  # base URL and optional default model
+  plexus-models-cache.json     # last-fetched model list (startup cache)
+  plexus-models-response.json  # raw API response (diagnostics)
+  plexus.log                   # extension activity log
+```
+
+The API key is stored in pi's own credential store (`auth.json`) — never in a separate file.
+
+### OpenCode
+
+```
+~/.local/share/opencode/plugins/plexus/
+  models-cache.json            # last-fetched model list (startup cache)
+  models-raw.json              # raw API response (diagnostics)
+```
 
-**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`.
+The API key is stored in OpenCode's own credential store — never in a separate file.
 
-**Cache location**
-The model cache lives under OpenCode's own state directory:
+---
+
+## Package layout
 
 ```
-~/.local/share/opencode/plugins/plexus/models-cache.json
-~/.local/share/opencode/plugins/plexus/models-raw.json
+packages/
+  plexus-models/        # host-agnostic data layer
+    src/
+      types.ts          # wire types (PlexusApiModel, PlexusModelDescriptor, etc.)
+      convert.ts        # model fetching, conversion, compat detection
+      index.ts          # barrel export
+  plexus-pi/            # pi host adapter
+    src/
+      extension.ts      # entry point: commands, session refresh, auth flow
+      mapper.ts         # PlexusModelDescriptor → pi ProviderModelConfig
+      config.ts         # base URL / default model config I/O
+      cache.ts          # model cache I/O
+      log.ts            # append-only log
+    package.json        # declares pi.extensions entry point
+  plexus-opencode/      # OpenCode plugin adapter
+    src/
+      plugin.ts         # Plugin export: config hook, auth handler
+      mapper.ts         # PlexusApiModel → OpenCode ConfigModel
+      cache.ts          # model cache I/O
+      config-store.ts   # resolveConfig, persistToGlobalConfig
+      log.ts            # logger via OpenCode SDK
+      constants.ts      # provider ID, env var names, timeouts
+      url.ts            # URL helpers (trimURL, apiBase, modelsUrl)
+      index.ts          # barrel export
+    package.json        # npm package manifest
+```
+
+`plexus-models` has zero imports from any agent framework. Each host adapter imports it via a relative path.
+
+## Development
+
+After cloning, install dependencies to set up the pre-commit hook:
+
+```sh
+bun install
 ```
 
-Deleting OpenCode's state directory (the documented reset path) also clears this cache.
+The pre-commit hook (via lefthook) rebuilds both dist artifacts automatically whenever source files change. After committing, reload/restart your agent.
 
-**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.
+To add support for a new host agent, see [AGENTS.md](AGENTS.md).

package/dist/index.js

@@ -9,9 +9,23 @@ 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";
 
+// ../plexus-models/src/convert.ts
+var REASONING_PARAMS = new Set(["reasoning", "include_reasoning", "reasoning_effort"]);
+async function fetchPlexusModels(apiKey, modelsUrl) {
+  const res = await fetch(modelsUrl, {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: "application/json"
+    }
+  });
+  if (!res.ok) {
+    throw new Error(`Plexus models fetch failed: ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.json();
+  return { models: raw.data ?? [], raw };
+}
 // src/cache.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { mkdir, readFile, writeFile } from "fs/promises";
@@ -155,8 +169,9 @@ function createLogger(client) {
   };
 }
 
-// src/models.ts
-var REASONING_PARAMS = new Set(["reasoning", "include_reasoning", "reasoning_effort"]);
+// src/mapper.ts
+var REASONING_PARAMS2 = new Set(["reasoning", "include_reasoning", "reasoning_effort"]);
+var DEFAULT_CONTEXT = 8192;
 function parsePrice(value) {
   if (!value)
     return 0;
@@ -235,7 +250,7 @@ function buildModels(models) {
         }
       } : {},
       ...params.includes("tools") ? { tool_call: true } : {},
-      ...params.some((p) => REASONING_PARAMS.has(p)) ? { reasoning: true } : {},
+      ...params.some((p) => REASONING_PARAMS2.has(p)) ? { reasoning: true } : {},
       ...params.includes("temperature") ? { temperature: true } : {},
       ...hasNonTextInput ? { attachment: true } : {}
     };
@@ -244,79 +259,14 @@ function buildModels(models) {
   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 url = modelsUrl(baseURL);
+  const { models: apiModels, raw } = await fetchPlexusModels(apiKey ?? "", url);
   const built = buildModels(apiModels);
   lastRefresh = { at: Date.now(), models: built };
   writeCache(client, built, raw).catch(() => {});
@@ -398,7 +348,8 @@ var PlexusProviderPlugin = async (ctx) => {
             if (!baseURL || !apiKey)
               return { type: "failed" };
             try {
-              await fetchPlexusModels(baseURL);
+              const url = modelsUrl(baseURL);
+              await fetchPlexusModels("", url);
             } catch (e) {
               log.error(`Plexus URL probe failed at ${baseURL}: ${String(e)}`);
               return { type: "failed" };
@@ -436,6 +387,5 @@ export {
   OPENAI_COMPATIBLE_NPM,
   MODELS_FETCH_TIMEOUT_MS,
   ENV_BASE_URL,
-  ENV_API_KEY,
-  DEFAULT_CONTEXT
+  ENV_API_KEY
 };

package/package.json

@@ -1,36 +1,47 @@
 {
-  "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"
-  }
+	"name": "@mcowger/opencode-plexus",
+	"version": "0.7.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/index.js",
+		"package.json",
+		"README.md"
+	],
+	"keywords": [
+		"plexus",
+		"opencode",
+		"ai",
+		"coding-agent",
+		"extension",
+		"plugin"
+	],
+	"scripts": {
+		"build": "bun run build.ts"
+	},
+	"dependencies": {
+		"@opencode-ai/plugin": "^1.15.7",
+		"@opencode-ai/sdk": "^1.15.7"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/mcowger/plexus-agent-plugins.git",
+		"directory": "packages/plexus-opencode"
+	},
+	"license": "MIT"
 }

package/LICENSE

@@ -1,21 +0,0 @@
-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.