opencode-apigee 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chelayel
+
+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

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# opencode-apigee
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use **Gemini on Vertex AI behind an Apigee gateway** as a model provider in
+[OpenCode](https://opencode.ai).
+
+Many companies expose Vertex AI through an Apigee gateway that wants an OAuth
+token from its own client-credentials endpoint instead of a Google API key or
+gcloud login. OpenCode's Google providers can't do that. This plugin does: it
+gets the token with your client id and secret, keeps it fresh, and sends every
+request to the gateway with it. Everything else is OpenCode's standard Gemini
+support.
+
+## Setup
+
+**1. Add the plugin** to `~/.config/opencode/opencode.json` (or a project's
+`opencode.json`), with your gateway's details:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["opencode-apigee", {
+      "gateway": "my-gw.example.com",
+      "project": "my-gcp-project",
+      "location": "us-central1",
+      "tokenUrl": "https://auth.example.com/oauth/token",
+      "clientId": "my-client-id",
+      "models": ["gemini-3.8-flash", "gemini-3.1-pro"]
+    }]
+  ]
+}
+```
+
+**2. Store the client secret** in OpenCode's credential store:
+
+```bash
+opencode auth login
+```
+
+Pick **Gemini via Apigee** from the list (type "apigee" to filter) and paste
+the client secret where it asks for an API key.
+
+(or set `APIGEE_CLIENT_SECRET` in the environment).
+
+**3. Pick a model**: `/models` in OpenCode → **Gemini via Apigee**, or
+`opencode run --model apigee/gemini-3.8-flash "…"`.
+
+### Already using AI Relay?
+
+If you set the gateway up with [AI Relay](https://github.com/Chelayel/ai-relay)
+(`airelay gemini setup`), the plugin reads the same values from
+`~/.airelay/config.properties` — gateway, project, location, token URL, client
+id and secret, and the published models. Then step 1 is just:
+
+```json
+{ "plugin": ["opencode-apigee"] }
+```
+
+## Options
+
+Each setting comes from, in order: the secret stored with `opencode auth login`
+(secret only), the plugin options, an environment variable, then AI Relay's
+config.
+
+| Option | Environment | AI Relay key | |
+| --- | --- | --- | --- |
+| `gateway` | `APIGEE_GATEWAY` | `vertex.endpoint` | Gateway host (`https://` is assumed) or a full URL |
+| `project` | `APIGEE_PROJECT` | `vertex.project` | Google Cloud project behind the gateway |
+| `location` | `APIGEE_LOCATION` | `vertex.location` | Default `us-central1` |
+| `tokenUrl` | `APIGEE_TOKEN_URL` | `apigee.token.url` | OAuth client-credentials endpoint |
+| `clientId` | `APIGEE_CLIENT_ID` | `apigee.client.id` | |
+| `clientSecret` | `APIGEE_CLIENT_SECRET` | `apigee.client.secret` | Prefer `opencode auth login` over the config file |
+| `models` | `APIGEE_MODELS` | `apigee.agents` | Model ids the gateway publishes (array, or comma-separated) |
+| `providerId` | | | Provider id in OpenCode, default `apigee` |
+| `name` | | | Display name, default `Gemini via Apigee` |
+| `airelay` | | | `false` to ignore AI Relay's config |
+
+A model you describe yourself under `provider.apigee.models` in
+`opencode.json` keeps your description; the plugin only adds the rest.
+
+## How it works
+
+- Requests go through OpenCode's own Gemini provider (`@ai-sdk/google`) with
+  its base URL set to the gateway's Vertex path,
+  `https://<gateway>/v1/projects/<project>/locations/<location>/publishers/google`,
+  so each call lands on
+  `…/models/<model>:streamGenerateContent` — Vertex's own URL, with the same
+  request body.
+- The token comes from `POST <tokenUrl>?grant_type=client_credentials` with the
+  client id and secret as HTTP Basic auth, and is cached until a minute before
+  it expires. Concurrent requests share one token fetch.
+- Each request has the provider's API-key header replaced by
+  `Authorization: Bearer <token>`. If the gateway answers 401, the token is
+  fetched again and the request retried once.
+
+Tested with OpenCode 1.19.4, end to end against a local stand-in for the
+gateway and its token endpoint.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * Gemini on Vertex AI behind an Apigee gateway, as an OpenCode provider.
+ *
+ * The provider is `@ai-sdk/google` aimed at the gateway's Vertex publisher
+ * path: its request URL is then Vertex's own, and the body is the same
+ * `generateContent` JSON. What differs is the credential — an OAuth token from
+ * the gateway's client-credentials endpoint instead of a Google API key — and
+ * that is the whole of this plugin: a fetch that swaps the one for the other.
+ * The client secret is OpenCode's to keep (`opencode auth login` → Apigee).
+ */
+export declare const ApigeePlugin: Plugin;

package/dist/index.js

@@ -0,0 +1,71 @@
+import { baseUrl, displayName, resolveSettings } from "./settings.js";
+import { createApigeeFetch, createTokenSource } from "./token.js";
+// Only the plugin is exported: OpenCode treats exported functions as plugins.
+/** What a Gemini model on Vertex can do; a gateway id OpenCode cannot look up gets these. */
+const GEMINI_LIMITS = { context: 1_048_576, output: 65_536 };
+/**
+ * Gemini on Vertex AI behind an Apigee gateway, as an OpenCode provider.
+ *
+ * The provider is `@ai-sdk/google` aimed at the gateway's Vertex publisher
+ * path: its request URL is then Vertex's own, and the body is the same
+ * `generateContent` JSON. What differs is the credential — an OAuth token from
+ * the gateway's client-credentials endpoint instead of a Google API key — and
+ * that is the whole of this plugin: a fetch that swaps the one for the other.
+ * The client secret is OpenCode's to keep (`opencode auth login` → Apigee).
+ */
+export const ApigeePlugin = async (_input, rawOptions) => {
+    const options = (rawOptions ?? {});
+    const providerId = options.providerId?.trim() || "apigee";
+    return {
+        config: async (config) => {
+            const { settings } = resolveSettings(options);
+            const models = {};
+            for (const id of settings.models) {
+                models[id] = {
+                    name: displayName(id),
+                    tool_call: true,
+                    attachment: true,
+                    reasoning: /gemini-([3-9]|2\.5)/.test(id),
+                    limit: GEMINI_LIMITS,
+                    modalities: { input: ["text", "image", "pdf"], output: ["text"] },
+                };
+            }
+            config.provider ??= {};
+            const existing = (config.provider[providerId] ?? {});
+            config.provider[providerId] = {
+                name: options.name?.trim() || "Gemini via Apigee",
+                npm: "@ai-sdk/google",
+                ...existing,
+                // A model the user described in opencode.json keeps their description.
+                models: { ...models, ...(existing.models ?? {}) },
+                options: {
+                    ...(settings.gateway && settings.project ? { baseURL: baseUrl(settings) } : {}),
+                    ...(existing.options ?? {}),
+                },
+            };
+        },
+        auth: {
+            provider: providerId,
+            methods: [
+                {
+                    type: "api",
+                    label: "Apigee client secret",
+                },
+            ],
+            loader: async (getAuth) => {
+                const stored = await getAuth().catch(() => undefined);
+                const secret = stored && stored.type === "api" ? stored.key : undefined;
+                const { settings, missing } = resolveSettings(options, process.env, secret);
+                if (missing.length)
+                    throw new Error(`opencode-apigee: missing ${missing.join(", ")}.`);
+                const tokens = createTokenSource(settings.tokenUrl, settings.clientId, settings.clientSecret);
+                return {
+                    baseURL: baseUrl(settings),
+                    // Required by @ai-sdk/google and never sent: the fetch replaces it with the token.
+                    apiKey: "apigee",
+                    fetch: createApigeeFetch(tokens),
+                };
+            },
+        },
+    };
+};

package/dist/settings.d.ts

@@ -0,0 +1,53 @@
+/** Everything needed to reach Gemini on Vertex AI through an Apigee gateway. */
+export interface ApigeeSettings {
+    /** Gateway base, e.g. `https://my-gw.example.com`; a bare host gets `https://`. */
+    gateway: string;
+    project: string;
+    location: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Model ids the gateway publishes. */
+    models: string[];
+}
+/** Plugin options, as written in opencode.json: `["opencode-apigee", { ... }]`. */
+export interface ApigeeOptions {
+    gateway?: string;
+    project?: string;
+    location?: string;
+    tokenUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    models?: string[] | string;
+    /** Provider id in OpenCode (default `apigee`). */
+    providerId?: string;
+    /** Display name in OpenCode (default `Gemini via Apigee`). */
+    name?: string;
+    /** Read settings from AI Relay's config file when not given here (default true). */
+    airelay?: boolean;
+}
+/**
+ * Settings from, in order: the secret OpenCode stored (`opencode auth login`),
+ * plugin options, `APIGEE_*` environment variables, and AI Relay's
+ * `~/.airelay/config.properties` — so someone already set up with
+ * `airelay gemini setup` only adds the plugin.
+ */
+export declare function resolveSettings(options?: ApigeeOptions, env?: Record<string, string | undefined>, storedSecret?: string, airelay?: Record<string, string>): {
+    settings: ApigeeSettings;
+    missing: string[];
+};
+/**
+ * The Vertex publisher path on the gateway. `@ai-sdk/google` appends
+ * `/models/<id>:streamGenerateContent`, which together is Vertex's own URL.
+ */
+export declare function baseUrl(s: ApigeeSettings): string;
+/** AI Relay's config file, or nothing. Its path follows AIRELAY_CONFIG like AI Relay itself. */
+export declare function readAirelayConfig(env?: Record<string, string | undefined>): Record<string, string>;
+/**
+ * java.util.Properties text: `key=value` or `key:value`, `#`/`!` comments,
+ * backslash escapes (`https\://…` is how Java writes a URL) and line
+ * continuations.
+ */
+export declare function parseProperties(text: string): Record<string, string>;
+/** `gemini-3.1-pro-preview` → "Gemini 3.1 Pro (preview)"; anything else as it is. */
+export declare function displayName(id: string): string;

package/dist/settings.js

@@ -0,0 +1,103 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Settings from, in order: the secret OpenCode stored (`opencode auth login`),
+ * plugin options, `APIGEE_*` environment variables, and AI Relay's
+ * `~/.airelay/config.properties` — so someone already set up with
+ * `airelay gemini setup` only adds the plugin.
+ */
+export function resolveSettings(options = {}, env = process.env, storedSecret, airelay = options.airelay === false ? {} : readAirelayConfig(env)) {
+    const pick = (opt, envKey, airelayKey) => nonBlank(opt) ?? nonBlank(env[envKey]) ?? nonBlank(airelay[airelayKey]);
+    const models = list(options.models) ?? list(env.APIGEE_MODELS) ?? list(airelay["apigee.agents"]) ?? list(airelay["gemini.model"]) ?? [];
+    const settings = {
+        gateway: pick(options.gateway, "APIGEE_GATEWAY", "vertex.endpoint") ?? "",
+        project: pick(options.project, "APIGEE_PROJECT", "vertex.project") ?? nonBlank(env.GOOGLE_CLOUD_PROJECT) ?? "",
+        location: pick(options.location, "APIGEE_LOCATION", "vertex.location") ?? "us-central1",
+        tokenUrl: pick(options.tokenUrl, "APIGEE_TOKEN_URL", "apigee.token.url") ?? "",
+        clientId: pick(options.clientId, "APIGEE_CLIENT_ID", "apigee.client.id") ?? "",
+        clientSecret: nonBlank(storedSecret) ?? pick(options.clientSecret, "APIGEE_CLIENT_SECRET", "apigee.client.secret") ?? "",
+        models,
+    };
+    const missing = [];
+    if (!settings.gateway)
+        missing.push("gateway (APIGEE_GATEWAY)");
+    if (!settings.project)
+        missing.push("project (APIGEE_PROJECT)");
+    if (!settings.tokenUrl)
+        missing.push("tokenUrl (APIGEE_TOKEN_URL)");
+    if (!settings.clientId)
+        missing.push("clientId (APIGEE_CLIENT_ID)");
+    if (!settings.clientSecret)
+        missing.push("client secret (`opencode auth login` → Apigee, or APIGEE_CLIENT_SECRET)");
+    return { settings, missing };
+}
+/**
+ * The Vertex publisher path on the gateway. `@ai-sdk/google` appends
+ * `/models/<id>:streamGenerateContent`, which together is Vertex's own URL.
+ */
+export function baseUrl(s) {
+    const gateway = /^https?:\/\//i.test(s.gateway) ? s.gateway : `https://${s.gateway}`;
+    return `${gateway.replace(/\/+$/, "")}/v1/projects/${encodeURIComponent(s.project)}/locations/${encodeURIComponent(s.location)}/publishers/google`;
+}
+/** AI Relay's config file, or nothing. Its path follows AIRELAY_CONFIG like AI Relay itself. */
+export function readAirelayConfig(env = process.env) {
+    const file = nonBlank(env.AIRELAY_CONFIG) ?? join(homedir(), ".airelay", "config.properties");
+    try {
+        return parseProperties(readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * java.util.Properties text: `key=value` or `key:value`, `#`/`!` comments,
+ * backslash escapes (`https\://…` is how Java writes a URL) and line
+ * continuations.
+ */
+export function parseProperties(text) {
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i].replace(/^\s+/, "");
+        if (!line || line.startsWith("#") || line.startsWith("!"))
+            continue;
+        while (/(^|[^\\])(\\\\)*\\$/.test(line) && i + 1 < lines.length)
+            line = line.slice(0, -1) + lines[++i].replace(/^\s+/, "");
+        let k = 0;
+        while (k < line.length && !"=: \t".includes(line[k]))
+            k += line[k] === "\\" ? 2 : 1;
+        const key = unescape(line.slice(0, k));
+        let rest = line.slice(k).replace(/^[ \t]*/, "");
+        if (rest.startsWith("=") || rest.startsWith(":"))
+            rest = rest.slice(1).replace(/^[ \t]*/, "");
+        out[key] = unescape(rest);
+    }
+    return out;
+}
+function unescape(s) {
+    return s.replace(/\\(u[0-9a-fA-F]{4}|.)/g, (_, c) => {
+        if (c.length === 5)
+            return String.fromCharCode(parseInt(c.slice(1), 16));
+        return c === "t" ? "\t" : c === "n" ? "\n" : c === "r" ? "\r" : c === "f" ? "\f" : c;
+    });
+}
+function nonBlank(s) {
+    return s && s.trim() ? s.trim() : undefined;
+}
+function list(v) {
+    const items = (Array.isArray(v) ? v : (v ?? "").split(",")).map((m) => m.trim()).filter(Boolean);
+    return items.length ? [...new Set(items)] : undefined;
+}
+/** `gemini-3.1-pro-preview` → "Gemini 3.1 Pro (preview)"; anything else as it is. */
+export function displayName(id) {
+    if (!/^gemini-/i.test(id))
+        return id;
+    const words = id.split("-");
+    const preview = words[words.length - 1].toLowerCase() === "preview";
+    const name = (preview ? words.slice(0, -1) : words)
+        .map((w) => (/^\d/.test(w) ? w : w.toLowerCase() === "lite" ? "Lite" : w[0].toUpperCase() + w.slice(1)))
+        .join(" ")
+        .replace("Flash Lite", "Flash-Lite");
+    return preview ? `${name} (preview)` : name;
+}

package/dist/token.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The Apigee OAuth token: client credentials, sent the way AI Relay sends them
+ * (`grant_type=client_credentials` on the token URL, HTTP Basic with the client
+ * id and secret, empty body), cached until a minute before it expires.
+ */
+export interface TokenSource {
+    token(): Promise<string>;
+    /** Forget the cached token, after the gateway refused it. */
+    invalidate(): void;
+}
+export declare function createTokenSource(tokenUrl: string, clientId: string, clientSecret: string, fetchImpl?: typeof fetch, now?: () => number): TokenSource;
+/**
+ * A fetch for `@ai-sdk/google` aimed at the gateway: its `x-goog-api-key`
+ * header is replaced by the Apigee bearer token. A 401 means the token went
+ * stale early (rotated, revoked): it is fetched again and the request retried
+ * once.
+ */
+export declare function createApigeeFetch(tokens: TokenSource, baseFetch?: typeof fetch): typeof fetch;

package/dist/token.js

@@ -0,0 +1,54 @@
+export function createTokenSource(tokenUrl, clientId, clientSecret, fetchImpl = fetch, now = Date.now) {
+    let cached;
+    let pending;
+    async function request() {
+        const url = tokenUrl + (tokenUrl.includes("?") ? "&" : "?") + "grant_type=client_credentials";
+        const basic = Buffer.from(`${clientId}:${clientSecret}`, "utf8").toString("base64");
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
+        });
+        if (!res.ok)
+            throw new Error(`Apigee token request failed (HTTP ${res.status}). Check the token URL, client id and secret.`);
+        const body = (await res.json().catch(() => ({})));
+        if (typeof body.access_token !== "string" || !body.access_token)
+            throw new Error("Apigee token response had no access_token.");
+        const expiresIn = Number(body.expires_in) > 0 ? Number(body.expires_in) : 3600;
+        cached = { token: body.access_token, expiresAt: now() + Math.max(30, expiresIn - 60) * 1000 };
+        return body.access_token;
+    }
+    return {
+        async token() {
+            if (cached && cached.expiresAt > now())
+                return cached.token;
+            // Concurrent requests share one token fetch rather than racing several.
+            pending ??= request().finally(() => (pending = undefined));
+            return pending;
+        },
+        invalidate() {
+            cached = undefined;
+        },
+    };
+}
+/**
+ * A fetch for `@ai-sdk/google` aimed at the gateway: its `x-goog-api-key`
+ * header is replaced by the Apigee bearer token. A 401 means the token went
+ * stale early (rotated, revoked): it is fetched again and the request retried
+ * once.
+ */
+export function createApigeeFetch(tokens, baseFetch = fetch) {
+    const send = async (input, init) => {
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        headers.delete("x-goog-api-key");
+        headers.set("Authorization", `Bearer ${await tokens.token()}`);
+        return baseFetch(input, { ...init, headers });
+    };
+    const apigeeFetch = async (input, init) => {
+        const res = await send(input, init);
+        if (res.status !== 401)
+            return res;
+        tokens.invalidate();
+        return send(input, init);
+    };
+    return apigeeFetch;
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "opencode-apigee",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenCode provider plugin: Gemini on Vertex AI behind an Apigee gateway (OAuth client credentials).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "keywords": ["opencode", "opencode-plugin", "apigee", "vertex", "gemini", "google"],
+  "author": "Chelayel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Chelayel/opencode-apigee"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.19.4",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}