@mcowger/oh-my-pi-plexus 1.9.0 → 1.10.0

package/README.md

@@ -176,21 +176,21 @@ To force a model refresh:
 /plexus-refresh
 ```
 
-`PLEXUS_API_URL` / `PLEXUS_BASE_URL` / `PLEXUS_API_KEY` env vars and plugin options (`plexusBaseURL`, `suppressModels`) are also honored. Until a URL is configured, the provider shows a single `plexus-unconfigured` placeholder. Plugin logs are written to `~/.local/share/opencode/plugins/plexus/plugin.log` (the OpenCode service discards plugin stdout).
+`PLEXUS_API_URL` / `PLEXUS_BASE_URL` / `PLEXUS_API_KEY` env vars and plugin options (`plexusBaseURL`, `apiKey`, `apiKeyEnv`, `suppressModels`) are also honored. Until a URL is configured, the provider shows a single `plexus-unconfigured` placeholder. Plugin logs are written to `~/.local/share/opencode/plugins/plexus/plugin.log` (the OpenCode service discards plugin stdout).
 
 ## Configuration files
 
 ### Connection state
 
-Each adapter stores only non-secret Plexus settings in its own `config.json`:
+Pi and OMP store only non-secret Plexus settings in their own `config.json`:
 
 ```text
-<agent-dir>/extensions/plexus/config.json  # base URL and optional model suppression
+<agent-dir>/extensions/plexus/config.json  # base URL, apiKeyEnv, model suppression
 ```
 
 Credentials stay in the host credential store (`auth.json` for Pi, `agent.db` for OMP). Model catalogs stay in the host model registry/store. The extension no longer writes a second model cache, ETag file, raw API response, or default-model preference.
 
-At runtime, configuration resolves as follows:
+With `apiKeyEnv` omitted, Pi resolves configuration as follows:
 
 ```text
 base URL: PLEXUS_API_URL → PLEXUS_BASE_URL → saved Plexus base URL
@@ -199,10 +199,73 @@ catalog: host model store → live Plexus refresh
 startup model: host model-picker preference
 ```
 
-`PLEXUS_API_URL` and `PLEXUS_BASE_URL` are process-only URL overrides; `PLEXUS_API_KEY` is a process-only credential fallback. None are persisted. `/plexus status` reports the effective URL source, whether auth is available, and catalog state without exposing credentials.
+OMP uses the same URL precedence, but its registered `PLEXUS_API_KEY` environment reference is a native config-key override, ahead of saved credentials. If that variable isn't set, OMP uses its host credential resolver. OpenCode uses `PLEXUS_API_KEY` before the saved `/connect` credential and plugin `apiKey` option.
+
+`PLEXUS_API_URL` and `PLEXUS_BASE_URL` are process-only URL overrides; environment API keys aren't persisted. `/plexus status` reports the effective URL source, whether auth is available, and catalog state without exposing credentials.
 
 Plexus accepts a root URL or a `/v1` API URL. The adapter normalizes that only for the Plexus discovery request. Each model then receives its own API-specific base URL: OpenAI stays on `/v1`, Anthropic uses the root, and Google uses `/v1beta`.
 
+### Separate API-key environment variables
+
+Set `apiKeyEnv` to the **name** of an environment variable, not its value or a `$VAR` template. The default is `PLEXUS_API_KEY`; no client-specific name is built in.
+
+For Pi, edit `~/.pi/agent/extensions/plexus/config.json` (or `<agent-dir>/extensions/plexus/config.json` when using a custom agent directory):
+
+```json
+{
+  "baseUrl": "https://plexus.example.com",
+  "apiKeyEnv": "AIHOME_PI_API_KEY"
+}
+```
+
+For OMP, edit `~/.omp/agent/extensions/plexus/config.json` (under the active profile's agent directory when using profiles):
+
+```json
+{
+  "baseUrl": "https://plexus.example.com",
+  "apiKeyEnv": "AIHOME_OMP_API_KEY"
+}
+```
+
+For OpenCode V2, put `apiKeyEnv` in the plugin's `options` in `~/.config/opencode/opencode.jsonc` (or your project `opencode.jsonc`):
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@mcowger/opencode-plexus",
+      "options": {
+        "plexusBaseURL": "https://plexus.example.com",
+        "apiKeyEnv": "AIHOME_OPENCODE_API_KEY"
+      }
+    }
+  ]
+}
+```
+
+Set the named variable in the process environment that launches the client. Restart Pi/OMP after editing their config; restart the OpenCode service after editing plugin options or changing its environment.
+
+Credential precedence:
+
+| Client | `apiKeyEnv` omitted | `apiKeyEnv` explicitly set |
+|---|---|---|
+| Pi | Saved host credential, then `PLEXUS_API_KEY` fallback | Only the named environment variable, ahead of saved credentials |
+| OMP | Registered `PLEXUS_API_KEY` env override, then host credentials | Only the named environment variable, ahead of saved credentials |
+| OpenCode V2 | `PLEXUS_API_KEY`, then saved `/connect` credential, then plugin `apiKey` option | Only the named environment variable, ahead of both saved credentials and `apiKey` |
+
+An explicit setting is authoritative even when it names `PLEXUS_API_KEY`. If the selected variable is missing, empty, or whitespace-only, the plugin reports an error naming the variable without showing its value. It does not fall back to a saved key, OpenCode's `apiKey` option, or the shared `PLEXUS_API_KEY`. Saved credentials remain stored; remove `apiKeyEnv` to restore the default precedence.
+
+### Native login with `apiKeyEnv`
+
+`apiKeyEnv` changes which key authenticates requests, not the native login UI:
+
+- Pi and OMP: `/login plexus` still prompts for the base URL and API key, and saves both through the normal configuration and credential stores.
+- OpenCode V2: `/connect` still stores the Plexus base URL and API key normally.
+
+With an explicit `apiKeyEnv`, discovery and model requests use the named environment variable rather than the key entered during login. OMP's immediate post-login refresh also uses the environment key. Login remains useful for configuring the base URL, but entering a different key won't override the environment setting.
+
+If the named variable is missing or empty at startup, the plugin fails to load. Native login cannot repair that setting: set the variable in the launching process environment or remove `apiKeyEnv`, then restart. Removing the setting restores the default precedence above without deleting saved credentials.
+
 ---
 
 ## Model suppression

package/dist/extension.js

@@ -16414,6 +16414,29 @@ var toPlexusApiBase = (raw) => {
   const root = normalizeConfigBaseUrl(raw);
   return root ? `${root}/v1` : "";
 };
+function resolveApiKeyEnvSetting() {
+  const raw = getConfigSync().apiKeyEnv;
+  if (raw === undefined || raw === null)
+    return { name: ENV_API_KEY, explicit: false };
+  const name = typeof raw === "string" ? raw.trim() : "";
+  if (!ENV_VAR_NAME_RE.test(name)) {
+    throw new Error("Invalid apiKeyEnv: expected an environment variable name");
+  }
+  return { name, explicit: true };
+}
+function getApiKeyEnvName() {
+  return resolveApiKeyEnvSetting().name;
+}
+function resolveExplicitApiKey() {
+  const { name, explicit } = resolveApiKeyEnvSetting();
+  if (!explicit)
+    return;
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`apiKeyEnv environment variable "${name}" is missing or empty`);
+  }
+  return value;
+}
 var cachedConfig = null;
 function getConfigSync() {
   if (cachedConfig)
@@ -16452,6 +16475,12 @@ function getBaseUrlResolution() {
 function getEnvApiKey() {
   return resolveStringOption(process.env[ENV_API_KEY]) ?? null;
 }
+function resolveApiKey(storedKey) {
+  const explicit = resolveExplicitApiKey();
+  if (explicit)
+    return explicit;
+  return storedKey ?? getEnvApiKey();
+}
 function getModelsUrl() {
   const { baseUrl } = getBaseUrlResolution();
   return baseUrl ? `${toPlexusApiBase(baseUrl)}/models` : null;
@@ -23193,7 +23222,10 @@ function normalizeProviderConnectionClosed(message, providerName) {
 // src/extension.ts
 var PROVIDER_NAME = "plexus";
 function getProviderApiKeyConfig() {
-  return Bun.env[ENV_API_KEY]?.trim() ? { apiKey: ENV_API_KEY, authHeader: true } : {};
+  const explicitApiKey = resolveExplicitApiKey();
+  const envName = getApiKeyEnvName();
+  const envValue = explicitApiKey ?? getEnvApiKey();
+  return envValue ? { apiKey: envName, authHeader: true } : {};
 }
 var currentModels = [];
 var catalogSource = "none";
@@ -23211,7 +23243,15 @@ function plexusExtension(pi) {
     normalizeProviderConnectionClosed(event.message, PROVIDER_NAME);
   });
   pi.on("session_start", async (_event, ctx) => {
-    const apiKey = await ctx.modelRegistry.authStorage.getApiKey(PROVIDER_NAME) ?? getEnvApiKey();
+    let apiKey;
+    try {
+      apiKey = resolveApiKey(await ctx.modelRegistry.authStorage.getApiKey(PROVIDER_NAME));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log("session_start: api key resolution failed", { error: message });
+      ctx.ui.notify(message, "error");
+      return;
+    }
     const baseUrl = getBaseUrl();
     log("session_start", { hasApiKey: !!apiKey, baseUrl });
     if (!apiKey || !baseUrl) {
@@ -23260,7 +23300,13 @@ function createPlexusLoginProvider(pi) {
   };
 }
 async function handleRefresh(pi, ctx) {
-  const apiKey = await ctx.modelRegistry.authStorage.getApiKey(PROVIDER_NAME) ?? getEnvApiKey();
+  let apiKey;
+  try {
+    apiKey = resolveApiKey(await ctx.modelRegistry.authStorage.getApiKey(PROVIDER_NAME));
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+    return;
+  }
   if (!apiKey) {
     ctx.ui.notify("No Plexus API key configured. Run /login plexus first.", "error");
     return;
@@ -23273,14 +23319,26 @@ async function handleStatus(ctx) {
   const apiKey = await ctx.modelRegistry.authStorage.getApiKey(PROVIDER_NAME);
   ctx.ui.notify([
     `Plexus base URL: ${baseUrl.baseUrl ?? "not configured"} (${baseUrl.source})`,
-    `API key: ${apiKey ? getEnvApiKey() ? "host credential or PLEXUS_API_KEY fallback" : "host credential" : "not configured"}`,
+    `API key: ${describeApiKey(apiKey)}`,
     `Catalog: ${currentModels.length} models (${catalogSource})`,
     "Default model: managed by OMP. Use /model or /models to save the selection there."
   ].join(`
 `), "info");
 }
+function describeApiKey(savedApiKey) {
+  try {
+    const envName = getApiKeyEnvName();
+    if (resolveExplicitApiKey() !== undefined)
+      return `${envName} (apiKeyEnv)`;
+    if (getEnvApiKey())
+      return `${envName} (overrides host credential)`;
+    return savedApiKey ? "host credential" : "not configured";
+  } catch (error) {
+    return `invalid apiKeyEnv configuration (${error instanceof Error ? error.message : String(error)})`;
+  }
+}
 async function fetchPlexusModelConfigs(apiKey) {
-  const key = apiKey ?? getEnvApiKey();
+  const key = resolveApiKey(apiKey);
   const modelsUrl = getModelsUrl();
   const baseUrl = getBaseUrl();
   if (!key || !modelsUrl || !baseUrl)
@@ -23302,7 +23360,14 @@ async function doRefresh(pi, apiKey, ctx) {
     return;
   }
   try {
-    const { models: apiModels } = await fetchPlexusModels(apiKey, modelsUrl);
+    const resolvedApiKey = resolveApiKey(apiKey);
+    if (!resolvedApiKey) {
+      if (ctx)
+        ctx.ui.notify("No Plexus API key configured. Run /login plexus first.", "warning");
+      log("doRefresh: no API key configured");
+      return;
+    }
+    const { models: apiModels } = await fetchPlexusModels(resolvedApiKey, modelsUrl);
     const suppressPatterns = getSuppressedModels();
     const descriptors = convertDescriptors(apiModels, baseUrl, suppressPatterns);
     const ohMyPiModels = descriptors.map(descriptorToOhMyPiModel);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mcowger/oh-my-pi-plexus",
-	"version": "1.9.0",
+	"version": "1.10.0",
 	"description": "Plexus AI proxy plugin for the Oh My Pi coding agent",
 	"type": "module",
 	"files": [