pi-zengate-models 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [1.0.1] - 2026-11-04
+
+- Remove the built-in gateway URL. Every machine sets `OPENCODE2API_BASE_URL`
+  or `baseUrl` in `<agent-dir>/zengate.json`.
+- Warn once per session when no endpoint is configured, instead of guessing.
+- Add a test that fails if the extension source gains a URL or a host.
+
+## [1.0.0] - 2026-11-04
+
+- First release. Reads the ZenGate `/v1/models` catalog at startup and
+  registers the free models as Pi provider `opencode2api`.
+- Keeps limits, input modes, zero cost, reasoning flag and thinking level map
+  from the gateway metadata.
+- Sends `reasoning_effort` for every registered model, so the level you pick
+  reaches the gateway.
+- Caches the catalog in `<agent-dir>/cache/zengate-models.json` and falls back
+  to it when the gateway is unreachable.
+- Adds `/zengate` and `/zengate refresh`.
+- Reads settings from the environment or `<agent-dir>/zengate.json`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamza (ham-zax)
+
+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,112 @@
+# pi-zengate-models
+
+Pi provider extension for a ZenGate / opencode2api gateway. It reads the
+gateway's `/v1/models` catalog, registers the free models as a Pi provider, and
+keeps the metadata current on every start. No scheduler, no generated
+`models.json`, no Python, and the same file on Linux, macOS and Windows.
+
+This package ships no endpoint and no key. Each machine supplies both.
+
+## What you get
+
+- Model list, context and output limits, input modes, zero cost and reasoning
+  levels come from the gateway catalog, which reads models.dev.
+- Only free models reach Pi. The gateway marks paid models excluded, and this
+  extension also skips any model whose input, output, cache read or cache write
+  cost is not exactly `0`.
+- The thinking level map follows the levels each model declares. Pi shows only
+  those levels in `/thinking` and sends only those values.
+- A cached catalog keeps `pi --list-models` honest when the gateway is offline or
+  slow. A startup fetch has a 5 second cap.
+
+## Install
+
+```bash
+pi install npm:pi-zengate-models
+```
+
+From git, or from a local checkout:
+
+```bash
+pi install git:github.com/ham-zax/pi-zengate@v1.0.1
+pi install /path/to/pi-zengate
+```
+
+## Configure
+
+Every machine needs its own gateway URL and key. Set them in the environment:
+
+```bash
+export OPENCODE2API_BASE_URL="https://your-gateway.example/v1"
+export OPENCODE2API_API_KEY="..."          # Linux, macOS, WSL
+setx OPENCODE2API_BASE_URL "https://your-gateway.example/v1"   # Windows
+setx OPENCODE2API_API_KEY "..."                                 # Windows
+```
+
+or in `<agent-dir>/zengate.json`, which avoids environment variables:
+
+```json
+{
+  "baseUrl": "https://your-gateway.example/v1",
+  "apiKey": "..."
+}
+```
+
+`<agent-dir>` is `~/.pi/agent` by default, or `PI_CODING_AGENT_DIR` when set.
+The environment wins over the file. Without a URL the extension registers no
+provider and shows one warning per session.
+
+## Verify
+
+```bash
+pi --list-models            # opencode2api rows with limits and thinking=yes
+pi
+/zengate                    # count, base URL, key source, last catalog check
+/zengate refresh            # fetch the catalog now
+```
+
+Then set the default model in `<agent-dir>/settings.json`:
+
+```json
+{
+  "defaultProvider": "opencode2api",
+  "defaultModel": "deepseek-v4.1-flash-free"
+}
+```
+
+## Remove the old generated provider
+
+If `models.json` also defines `providers.opencode2api`, those static entries win
+over the extension by model ID, so stale limits and a stale compat block return.
+Delete that provider block, or leave `models.json` as:
+
+```json
+{ "providers": {} }
+```
+
+## Choosing a thinking level
+
+Run `/thinking`, or pass `--thinking <level>` on the command line. Pi clamps a
+level the model does not declare, which means `max` on a model without `max`
+sends the highest level that model does declare. A model that declares no levels
+sends nothing beyond `high`.
+
+The compat flag `supportsReasoningEffort` is `true` for every model this provider
+registers. When it is `false`, Pi drops the selected level before the request and
+the model always runs at its own default.
+
+## Files it writes
+
+- Cache: `<agent-dir>/cache/zengate-models.json`
+- Nothing else. The extension never edits `models.json` or `settings.json`.
+
+## Develop
+
+```bash
+npm test                                     # mapping and settings tests, no network
+pi -e ./extensions/zengate-models.ts         # load from source
+```
+
+## License
+
+MIT

package/extensions/zengate-models.ts

@@ -0,0 +1,281 @@
+/**
+ * ZenGate (opencode2api) model discovery for Pi.
+ *
+ * The gateway's /v1/models catalog is the authority for which free models
+ * exist and what they accept, cost and support. This extension registers the
+ * provider, reads that catalog at startup, and caches it, so every OS gets
+ * current models and metadata with no scheduled job and no generated
+ * models.json.
+ *
+ * The mapping mirrors scripts/sync-client-models.py in the gateway repository:
+ * `metadata` carries the models.dev values, non-free or non-text models are
+ * skipped, and Pi keeps only text and image inputs.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const PROVIDER_ID = "opencode2api";
+export const PROVIDER_NAME = "ZenGate";
+export const KEY_ENV = "OPENCODE2API_API_KEY";
+export const BASE_URL_ENV = "OPENCODE2API_BASE_URL";
+
+const FETCH_TIMEOUT_MS = 5000;
+const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+type Inputs = ("text" | "image")[];
+export type PiModel = {
+  id: string;
+  name: string;
+  api: "openai-completions" | "openai-responses";
+  reasoning: boolean;
+  input: Inputs;
+  contextWindow: number;
+  maxTokens: number;
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  thinkingLevelMap?: Record<string, string | null>;
+  compat: {
+    supportsStore: boolean;
+    supportsDeveloperRole: boolean;
+    supportsReasoningEffort: boolean;
+    supportsUsageInStreaming: boolean;
+  };
+};
+
+type Meta = {
+  name?: unknown;
+  limit?: { context?: unknown; output?: unknown };
+  modalities?: { input?: unknown; output?: unknown };
+  reasoning?: unknown;
+  cost?: { input?: unknown; output?: unknown; cache_read?: unknown; cache_write?: unknown };
+  reasoning_options?: unknown;
+};
+type CatalogRecord = { id?: unknown; endpoint?: unknown; metadata?: Meta };
+
+/**
+ * Pi sends reasoning_effort only when this is true. Every model in the current
+ * free catalog accepts the field, and the thinking level map decides which
+ * values Pi may send.
+ */
+const COMPAT = {
+  supportsStore: false,
+  supportsDeveloperRole: false,
+  supportsReasoningEffort: true,
+  supportsUsageInStreaming: true,
+};
+
+const isText = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const isCount = (value: unknown): value is number => Number.isInteger(value) && (value as number) > 0;
+const isFree = (value: unknown): value is number => typeof value === "number" && value === 0;
+
+/** Upstream effort levels for one model; empty when it has no graded control. */
+export function effortValues(meta: Meta): string[] {
+  if (!Array.isArray(meta.reasoning_options)) return [];
+  for (const option of meta.reasoning_options) {
+    if (!option || typeof option !== "object") continue;
+    const { type, values } = option as { type?: unknown; values?: unknown };
+    if (type === "effort" && Array.isArray(values) && values.length > 0 && values.every(isText)) {
+      return [...values];
+    }
+  }
+  return [];
+}
+
+/**
+ * A supported level sends its own name. A level the model does not declare maps
+ * to null, so Pi hides it and never sends it.
+ */
+export function thinkingLevelMap(values: string[]): Record<string, string | null> {
+  const map: Record<string, string | null> = {};
+  for (const level of LEVELS) {
+    if (level === "off") map[level] = values.includes("none") ? "none" : null;
+    else map[level] = values.includes(level) ? level : null;
+  }
+  return map;
+}
+
+/** Map one gateway catalog payload to Pi model configs. */
+export function toPiModels(payload: unknown): PiModel[] {
+  const data = (payload as { data?: unknown } | null)?.data;
+  if (!Array.isArray(data)) throw new Error("gateway catalog has no data array");
+
+  const models: PiModel[] = [];
+  for (const record of data as CatalogRecord[]) {
+    const meta = record?.metadata;
+    if (!meta || !isText(record.id) || !isText(meta.name)) continue;
+    const contextWindow = meta.limit?.context;
+    const maxTokens = meta.limit?.output;
+    if (!isCount(contextWindow) || !isCount(maxTokens)) continue;
+    const outputs = meta.modalities?.output;
+    if (!Array.isArray(outputs) || !outputs.includes("text")) continue;
+    const cost = meta.cost;
+    if (!cost || !isFree(cost.input) || !isFree(cost.output)) continue;
+    if (!isFree(cost.cache_read ?? 0) || !isFree(cost.cache_write ?? 0)) continue;
+    const declared = Array.isArray(meta.modalities?.input) ? meta.modalities.input : [];
+    const input = ["text", "image"].filter((mode) => declared.includes(mode)) as Inputs;
+    if (input.length === 0) continue;
+    const efforts = effortValues(meta);
+    models.push({
+      id: record.id,
+      name: meta.name,
+      api: record.endpoint === "responses" ? "openai-responses" : "openai-completions",
+      reasoning: meta.reasoning === true,
+      input,
+      contextWindow,
+      maxTokens,
+      cost: {
+        input: cost.input,
+        output: cost.output,
+        cacheRead: cost.cache_read ?? 0,
+        cacheWrite: cost.cache_write ?? 0,
+      },
+      ...(efforts.length > 0 ? { thinkingLevelMap: thinkingLevelMap(efforts) } : {}),
+      compat: COMPAT,
+    });
+  }
+  if (models.length === 0) throw new Error("gateway catalog has no usable free models");
+  return models;
+}
+
+/** Pi config directory, honouring PI_CODING_AGENT_DIR. */
+export function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+export function configPath(): string {
+  return join(agentDir(), "zengate.json");
+}
+
+export function cachePath(): string {
+  return join(agentDir(), "cache", "zengate-models.json");
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeBaseUrl(value: string): string {
+  return value.trim().replace(/\/+$/, "");
+}
+
+/**
+ * Settings precedence: environment, then <agent-dir>/zengate.json.
+ * The config file lets a machine skip environment variables. This package ships
+ * no endpoint: every machine supplies its own.
+ */
+export function readSettings(): { baseUrl?: string; apiKey?: string; keySource: string } {
+  const file = readJson(configPath()) ?? {};
+  const fileBase = typeof file.baseUrl === "string" && file.baseUrl.trim() ? file.baseUrl : undefined;
+  const fileKey = typeof file.apiKey === "string" && file.apiKey.trim() ? file.apiKey.trim() : undefined;
+  const envBase = process.env[BASE_URL_ENV];
+  const envKey = process.env[KEY_ENV]?.trim();
+  const base = envBase || fileBase;
+  return {
+    baseUrl: base ? normalizeBaseUrl(base) : undefined,
+    apiKey: envKey || fileKey,
+    keySource: envKey ? KEY_ENV : fileKey ? "zengate.json" : "none",
+  };
+}
+
+const configureHint = (): string => `Set ${BASE_URL_ENV} or baseUrl in ${configPath()} to your gateway /v1 URL.`;
+
+export default async function (pi: ExtensionAPI) {
+  const settings = readSettings();
+  const key = settings.apiKey;
+  const cacheFile = cachePath();
+
+  // Without an endpoint there is nothing to discover. Say so once per session
+  // and leave the model list untouched.
+  if (!settings.baseUrl) {
+    pi.on("session_start", async (_event, ctx) => {
+      ctx.ui.notify(`${PROVIDER_NAME}: ${configureHint()}`, "warning");
+    });
+    return;
+  }
+  const baseUrl = settings.baseUrl;
+
+  const readCache = (): PiModel[] => {
+    const saved = readJson(cacheFile);
+    return Array.isArray(saved?.models) ? (saved.models as PiModel[]) : [];
+  };
+  const writeCache = (models: PiModel[]) => {
+    try {
+      mkdirSync(dirname(cacheFile), { recursive: true });
+      writeFileSync(
+        cacheFile,
+        `${JSON.stringify({ baseUrl, checkedAt: Date.now(), models }, null, 2)}\n`,
+      );
+    } catch {
+      // A read-only agent directory must not break model loading.
+    }
+  };
+
+  let latest = readCache();
+  let checkedAt = readJson(cacheFile)?.checkedAt as number | undefined;
+
+  const refresh = async (signal?: AbortSignal): Promise<PiModel[]> => {
+    const deadline = AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    const combined = signal && "any" in AbortSignal ? AbortSignal.any([signal, deadline]) : deadline;
+    const response = await fetch(`${baseUrl}/models`, {
+      headers: { accept: "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
+      signal: combined,
+    });
+    if (!response.ok) throw new Error(`gateway catalog returned HTTP ${response.status}`);
+    latest = toPiModels(await response.json());
+    checkedAt = Date.now();
+    writeCache(latest);
+    return latest;
+  };
+
+  // Fetch before registering, so `pi --list-models` and every startup see the
+  // current catalog. `--list-models` runs offline-only, so it never refreshes.
+  if (key) {
+    try {
+      await refresh();
+    } catch {
+      // Offline or a gateway fault: the cached catalog above is still usable.
+    }
+  }
+
+  pi.registerProvider(PROVIDER_ID, {
+    name: PROVIDER_NAME,
+    baseUrl,
+    apiKey: key ?? `\${${KEY_ENV}}`,
+    api: "openai-completions",
+    models: latest,
+    async refreshModels(context) {
+      if (!context.allowNetwork) return latest;
+      const credential = context.credential?.type === "api_key" ? context.credential.key : undefined;
+      if (!credential && !key) return latest;
+      try {
+        return await refresh(context.signal);
+      } catch {
+        return latest;
+      }
+    },
+  });
+
+  pi.registerCommand("zengate", {
+    description: "Show or refresh the ZenGate model catalog",
+    handler: async (args, ctx) => {
+      if ((args ?? "").trim() === "refresh") {
+        try {
+          const models = await refresh();
+          ctx.ui.notify(`ZenGate: refreshed ${models.length} models from ${baseUrl}`, "info");
+        } catch (error) {
+          ctx.ui.notify(`ZenGate refresh failed: ${(error as Error).message}`, "error");
+        }
+        return;
+      }
+      const stamp = checkedAt ? new Date(checkedAt).toISOString() : "never";
+      const line = `${PROVIDER_NAME}: ${latest.length} models, ${baseUrl}, key ${settings.keySource}, catalog ${stamp}`;
+      ctx.ui.notify(line, "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-zengate-models",
+  "version": "1.0.1",
+  "description": "Pi provider extension that discovers free models and their metadata from an OpenAI-compatible gateway catalog, with a local cache and no scheduler.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "opencode2api",
+    "zengate",
+    "openai-compatible"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/zengate-models.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/mapping.test.mjs"
+  }
+}