@moxxy/plugin-provider-google 0.21.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+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/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { geminiModels } from './models.js';
+export { geminiModels };
+/**
+ * Model used when a request didn't pin one. MUST exist in {@link geminiModels}:
+ * the descriptor for the default model drives the default request's
+ * context-window/capability budget, so a default id absent from the catalog
+ * would silently fall back to the host's generic miss-path budget (exactly the
+ * unlisted-id trap the catalog docstring warns about) for every default call.
+ * The exported constant lets the package's own tests pin that invariant.
+ */
+export declare const GEMINI_DEFAULT_MODEL = "gemini-2.5-flash";
+/**
+ * Google Gemini, served via Gemini's OpenAI-compatibility endpoint so it
+ * reuses the shared {@link defineOpenAICompatProvider} with the `google` slug +
+ * base URL + Gemini catalog forced on (so usage stats, provider events and
+ * error context attribute to `google`, not `openai`). The canonical key is
+ * `GOOGLE_API_KEY`.
+ */
+export declare const googleProviderDef: import("@moxxy/sdk").ProviderDef;
+export declare const googlePlugin: import("@moxxy/sdk").Plugin;
+export default googlePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,CAAC;AAKxB;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,kCAc5B,CAAC;AAKH,eAAO,MAAM,YAAY,6BAGvB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { definePlugin } from '@moxxy/sdk';
+import { defineOpenAICompatProvider } from '@moxxy/plugin-provider-openai';
+import { geminiModels } from './models.js';
+export { geminiModels };
+/** Gemini's OpenAI-compatibility endpoint (trailing slash matters for the SDK). */
+const GEMINI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta/openai/';
+/**
+ * Model used when a request didn't pin one. MUST exist in {@link geminiModels}:
+ * the descriptor for the default model drives the default request's
+ * context-window/capability budget, so a default id absent from the catalog
+ * would silently fall back to the host's generic miss-path budget (exactly the
+ * unlisted-id trap the catalog docstring warns about) for every default call.
+ * The exported constant lets the package's own tests pin that invariant.
+ */
+export const GEMINI_DEFAULT_MODEL = 'gemini-2.5-flash';
+/**
+ * Google Gemini, served via Gemini's OpenAI-compatibility endpoint so it
+ * reuses the shared {@link defineOpenAICompatProvider} with the `google` slug +
+ * base URL + Gemini catalog forced on (so usage stats, provider events and
+ * error context attribute to `google`, not `openai`). The canonical key is
+ * `GOOGLE_API_KEY`.
+ */
+export const googleProviderDef = defineOpenAICompatProvider({
+    name: 'google',
+    baseURL: GEMINI_BASE_URL,
+    defaultModel: GEMINI_DEFAULT_MODEL,
+    models: geminiModels,
+    auth: {
+        kind: 'apiKey',
+        // Pin the env var explicitly: Google's own docs hand users GEMINI_API_KEY,
+        // but moxxy resolves credentials under the canonical GOOGLE_API_KEY. Naming
+        // it here (instead of relying on name-inference) keeps the setup hint and
+        // the resolver in agreement.
+        envVar: 'GOOGLE_API_KEY',
+        hint: 'Google AI Studio (Gemini) API key from https://aistudio.google.com/apikey (set GOOGLE_API_KEY)',
+    },
+});
+// `version` is intentionally omitted — definePlugin defaults it; a hardcoded
+// literal here would permanently diverge from package.json and masquerade as a
+// real version in diagnostics.
+export const googlePlugin = definePlugin({
+    name: '@moxxy/plugin-provider-google',
+    providers: [googleProviderDef],
+});
+export default googlePlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,mFAAmF;AACnF,MAAM,eAAe,GAAG,0DAA0D,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;IAC1D,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,eAAe;IACxB,YAAY,EAAE,oBAAoB;IAClC,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,2EAA2E;QAC3E,4EAA4E;QAC5E,0EAA0E;QAC1E,6BAA6B;QAC7B,MAAM,EAAE,gBAAgB;QACxB,IAAI,EAAE,gGAAgG;KACvG;CACF,CAAC,CAAC;AAEH,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC;IACvC,IAAI,EAAE,+BAA+B;IACrC,SAAS,EAAE,CAAC,iBAAiB,CAAC;CAC/B,CAAC,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,25 @@
+import type { ModelDescriptor } from '@moxxy/sdk';
+/**
+ * Google Gemini model catalog, as of 2026-06 (verify against
+ * https://ai.google.dev/gemini-api/docs/models). Served here via Gemini's
+ * OpenAI-compatibility endpoint, so these stream through the shared
+ * {@link import('@moxxy/plugin-provider-openai').OpenAIProvider}. The Gemini 3
+ * and 2.5 families all carry a 1M-token context window and are natively
+ * multimodal (image input).
+ *
+ * An unlisted model id still works for raw inference — it's passed straight
+ * through to the endpoint — but it loses Gemini-correct budgeting: the
+ * descriptor lookup misses, so context-window/capability gating falls back to
+ * the host's miss-path default instead of the 1M window asserted here.
+ *
+ * supportsDocuments is intentionally NOT set: although Gemini natively accepts
+ * PDFs on its own API (via `inline_data`), the OpenAI-compatibility surface
+ * does not honor the OpenAI `file`/`file_data` content part the shared
+ * translate layer emits for `document` blocks. Asserting it would make the
+ * desktop ship raw PDF bytes the endpoint rejects/ignores — losing the
+ * document entirely with no fallback. Leaving it unset keeps the safe
+ * extracted-text path. Images ride `image_url` data URLs, which the compat
+ * endpoint does accept, so supportsImages stays true.
+ */
+export declare const geminiModels: ReadonlyArray<ModelDescriptor>;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,eAAe,CAUvD,CAAC"}

package/dist/models.js

@@ -0,0 +1,33 @@
+/**
+ * Google Gemini model catalog, as of 2026-06 (verify against
+ * https://ai.google.dev/gemini-api/docs/models). Served here via Gemini's
+ * OpenAI-compatibility endpoint, so these stream through the shared
+ * {@link import('@moxxy/plugin-provider-openai').OpenAIProvider}. The Gemini 3
+ * and 2.5 families all carry a 1M-token context window and are natively
+ * multimodal (image input).
+ *
+ * An unlisted model id still works for raw inference — it's passed straight
+ * through to the endpoint — but it loses Gemini-correct budgeting: the
+ * descriptor lookup misses, so context-window/capability gating falls back to
+ * the host's miss-path default instead of the 1M window asserted here.
+ *
+ * supportsDocuments is intentionally NOT set: although Gemini natively accepts
+ * PDFs on its own API (via `inline_data`), the OpenAI-compatibility surface
+ * does not honor the OpenAI `file`/`file_data` content part the shared
+ * translate layer emits for `document` blocks. Asserting it would make the
+ * desktop ship raw PDF bytes the endpoint rejects/ignores — losing the
+ * document entirely with no fallback. Leaving it unset keeps the safe
+ * extracted-text path. Images ride `image_url` data URLs, which the compat
+ * endpoint does accept, so supportsImages stays true.
+ */
+export const geminiModels = [
+    // Gemini 3 family: current frontier. Reasoning models.
+    { id: 'gemini-3-pro', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+    { id: 'gemini-3-flash', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+    // Gemini 2.5 family: widely available, strong price/performance. pro/flash
+    // are reasoning models.
+    { id: 'gemini-2.5-pro', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+    { id: 'gemini-2.5-flash', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+    { id: 'gemini-2.5-flash-lite', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true },
+];
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmC;IAC1D,uDAAuD;IACvD,EAAE,EAAE,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACtK,EAAE,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IAExK,2EAA2E;IAC3E,wBAAwB;IACxB,EAAE,EAAE,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IACxK,EAAE,EAAE,EAAE,kBAAkB,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE;IAC1K,EAAE,EAAE,EAAE,uBAAuB,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;CACvJ,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@moxxy/plugin-provider-google",
+  "version": "0.21.1",
+  "description": "Google Gemini LLMProvider plugin for moxxy. Streams the Gemini OpenAI-compatible endpoint (generativelanguage.googleapis.com/v1beta/openai).",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "provider",
+    "google",
+    "gemini",
+    "llm"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-provider-google"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "provider"
+    }
+  },
+  "dependencies": {
+    "@moxxy/plugin-provider-openai": "0.21.1",
+    "@moxxy/sdk": "0.21.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+import { googlePlugin, googleProviderDef, geminiModels, GEMINI_DEFAULT_MODEL } from './index.js';
+
+describe('@moxxy/plugin-provider-google', () => {
+  it('registers the google provider', () => {
+    expect(googlePlugin.providers?.map((p) => p.name)).toEqual(['google']);
+  });
+
+  it('advertises the Gemini catalog (1M-context, vision-capable)', () => {
+    expect(googleProviderDef.models).toEqual(geminiModels);
+    expect(geminiModels.find((m) => m.id === 'gemini-3-pro')).toMatchObject({
+      contextWindow: 1_000_000,
+      supportsImages: true,
+    });
+  });
+
+  it('createClient stamps the google slug so usage/errors attribute to Gemini, not openai', () => {
+    const client = googleProviderDef.createClient({ apiKey: 'test-key' });
+    expect(client.name).toBe('google');
+    expect(client.models).toEqual(geminiModels);
+  });
+
+  it('exposes an apiKey auth descriptor pinned to the canonical GOOGLE_API_KEY env var', () => {
+    expect(googleProviderDef.auth).toMatchObject({ kind: 'apiKey', envVar: 'GOOGLE_API_KEY' });
+  });
+
+  it('every Gemini model advertises supportsImages (image_url data URLs are honored by the compat endpoint)', () => {
+    for (const m of geminiModels) {
+      expect(m.supportsImages, `${m.id} supportsImages`).toBe(true);
+    }
+  });
+
+  it('no Gemini model over-claims supportsDocuments (the OpenAI-compat endpoint rejects the file part)', () => {
+    // Worst case if this regresses: the desktop ships raw PDF bytes as an
+    // OpenAI `file`/`file_data` part the Gemini compat endpoint does not honor,
+    // so the document is dropped/400s with no fallback. Keeping the flag unset
+    // preserves the safe extracted-text path.
+    for (const m of geminiModels) {
+      expect(m.supportsDocuments, `${m.id} supportsDocuments`).toBeFalsy();
+    }
+  });
+
+  it('the reasoning-tier Gemini models advertise supportsReasoning', () => {
+    // Reasoning gating (reasoning_effort + reasoning-stream surfacing) keys off
+    // this flag; the pro/flash tiers are reasoning models.
+    const reasoningIds = ['gemini-3-pro', 'gemini-3-flash', 'gemini-2.5-pro', 'gemini-2.5-flash'];
+    for (const id of reasoningIds) {
+      expect(geminiModels.find((m) => m.id === id)?.supportsReasoning, id).toBe(true);
+    }
+  });
+
+  it('the default model exists in the catalog (else every default request gets a wrong budget)', () => {
+    // Worst case if this regresses: a request that pins no model falls through
+    // to GEMINI_DEFAULT_MODEL, whose descriptor lookup then MISSES, so the
+    // default call silently inherits the host's generic miss-path
+    // context-window/capability budget instead of Gemini's 1M window — the exact
+    // unlisted-id trap the catalog docstring warns about, now hitting the
+    // package's OWN configured default.
+    expect(geminiModels.find((m) => m.id === GEMINI_DEFAULT_MODEL), GEMINI_DEFAULT_MODEL).toBeDefined();
+  });
+
+  it('the catalog is non-empty and free of duplicate ids', () => {
+    // An empty catalog would defeat all context/capability gating; a duplicate
+    // id makes descriptor lookup order-dependent (a stale/wrong descriptor can
+    // shadow the intended one). Both are silent-correctness hazards a careless
+    // future edit could introduce.
+    expect(geminiModels.length).toBeGreaterThan(0);
+    const ids = geminiModels.map((m) => m.id);
+    expect(new Set(ids).size, `duplicate model id in catalog: ${ids.join(', ')}`).toBe(ids.length);
+  });
+
+  it('every catalog entry carries a sane, positive context/output budget', () => {
+    // A zero/negative/NaN window or output cap would corrupt compaction/elision
+    // budgeting downstream (e.g. premature compaction or unbounded asks). Assert
+    // the worst case never ships from this catalog.
+    for (const m of geminiModels) {
+      expect(Number.isFinite(m.contextWindow) && m.contextWindow > 0, `${m.id} contextWindow`).toBe(true);
+      if (m.maxOutputTokens !== undefined) {
+        expect(
+          Number.isFinite(m.maxOutputTokens) && m.maxOutputTokens > 0,
+          `${m.id} maxOutputTokens`,
+        ).toBe(true);
+        // The output cap can never exceed the total context window.
+        expect(m.maxOutputTokens, `${m.id} maxOutputTokens <= contextWindow`).toBeLessThanOrEqual(
+          m.contextWindow,
+        );
+      }
+    }
+  });
+
+  it('wires validateKey so a bad Gemini key is caught at setup, not first inference', () => {
+    // defineOpenAICompatProvider defaults validation ON (probes the base URL's
+    // /models). Dropping it would let an invalid key sail through setup and only
+    // fail — opaquely — on the first real turn. Pin that it stays wired.
+    expect(typeof googleProviderDef.validateKey).toBe('function');
+  });
+
+  it('createClient narrows away hostile/wrong-typed config fields without crashing', () => {
+    // The registry hands createClient an untyped Record<string, unknown>. A
+    // wrong-typed baseURL/defaultModel (number/object/null) plus unknown junk
+    // must be narrowed away and fall back to vendor defaults — they must NOT
+    // smuggle a bad value into the client or crash construction. A valid apiKey
+    // is always present in practice (the registry resolves it before calling),
+    // so we supply one and stress only the other fields.
+    const hostile: Record<string, unknown> = {
+      apiKey: 'test-key',
+      baseURL: { evil: true } as unknown as string,
+      defaultModel: 12345 as unknown as string,
+      extraJunk: 'ignored',
+      __proto__pollution: 'ignored',
+    };
+    expect(() => googleProviderDef.createClient(hostile)).not.toThrow();
+    const client = googleProviderDef.createClient(hostile);
+    // Slug attribution and catalog must survive the hostile config.
+    expect(client.name).toBe('google');
+    expect(client.models).toEqual(geminiModels);
+  });
+
+  it('createClient surfaces a clear error (never a silently-broken client) when no key resolves', () => {
+    // In practice the registry only calls createClient with a resolved key. If
+    // it ever didn't, the underlying OpenAI SDK constructor must FAIL LOUDLY
+    // (no key) rather than hand back a half-constructed client that 401s opaquely
+    // on the first turn. Pin that the keyless path throws synchronously here.
+    // The OpenAI SDK falls back to process.env.OPENAI_API_KEY, so clear it for
+    // the assertion to keep this deterministic regardless of the runner's env.
+    const saved = process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    try {
+      expect(() => googleProviderDef.createClient({})).toThrow();
+    } finally {
+      if (saved !== undefined) process.env.OPENAI_API_KEY = saved;
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,51 @@
+import { definePlugin } from '@moxxy/sdk';
+import { defineOpenAICompatProvider } from '@moxxy/plugin-provider-openai';
+import { geminiModels } from './models.js';
+
+export { geminiModels };
+
+/** Gemini's OpenAI-compatibility endpoint (trailing slash matters for the SDK). */
+const GEMINI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta/openai/';
+
+/**
+ * Model used when a request didn't pin one. MUST exist in {@link geminiModels}:
+ * the descriptor for the default model drives the default request's
+ * context-window/capability budget, so a default id absent from the catalog
+ * would silently fall back to the host's generic miss-path budget (exactly the
+ * unlisted-id trap the catalog docstring warns about) for every default call.
+ * The exported constant lets the package's own tests pin that invariant.
+ */
+export const GEMINI_DEFAULT_MODEL = 'gemini-2.5-flash';
+
+/**
+ * Google Gemini, served via Gemini's OpenAI-compatibility endpoint so it
+ * reuses the shared {@link defineOpenAICompatProvider} with the `google` slug +
+ * base URL + Gemini catalog forced on (so usage stats, provider events and
+ * error context attribute to `google`, not `openai`). The canonical key is
+ * `GOOGLE_API_KEY`.
+ */
+export const googleProviderDef = defineOpenAICompatProvider({
+  name: 'google',
+  baseURL: GEMINI_BASE_URL,
+  defaultModel: GEMINI_DEFAULT_MODEL,
+  models: geminiModels,
+  auth: {
+    kind: 'apiKey',
+    // Pin the env var explicitly: Google's own docs hand users GEMINI_API_KEY,
+    // but moxxy resolves credentials under the canonical GOOGLE_API_KEY. Naming
+    // it here (instead of relying on name-inference) keeps the setup hint and
+    // the resolver in agreement.
+    envVar: 'GOOGLE_API_KEY',
+    hint: 'Google AI Studio (Gemini) API key from https://aistudio.google.com/apikey (set GOOGLE_API_KEY)',
+  },
+});
+
+// `version` is intentionally omitted — definePlugin defaults it; a hardcoded
+// literal here would permanently diverge from package.json and masquerade as a
+// real version in diagnostics.
+export const googlePlugin = definePlugin({
+  name: '@moxxy/plugin-provider-google',
+  providers: [googleProviderDef],
+});
+
+export default googlePlugin;

package/src/models.ts

@@ -0,0 +1,35 @@
+import type { ModelDescriptor } from '@moxxy/sdk';
+
+/**
+ * Google Gemini model catalog, as of 2026-06 (verify against
+ * https://ai.google.dev/gemini-api/docs/models). Served here via Gemini's
+ * OpenAI-compatibility endpoint, so these stream through the shared
+ * {@link import('@moxxy/plugin-provider-openai').OpenAIProvider}. The Gemini 3
+ * and 2.5 families all carry a 1M-token context window and are natively
+ * multimodal (image input).
+ *
+ * An unlisted model id still works for raw inference — it's passed straight
+ * through to the endpoint — but it loses Gemini-correct budgeting: the
+ * descriptor lookup misses, so context-window/capability gating falls back to
+ * the host's miss-path default instead of the 1M window asserted here.
+ *
+ * supportsDocuments is intentionally NOT set: although Gemini natively accepts
+ * PDFs on its own API (via `inline_data`), the OpenAI-compatibility surface
+ * does not honor the OpenAI `file`/`file_data` content part the shared
+ * translate layer emits for `document` blocks. Asserting it would make the
+ * desktop ship raw PDF bytes the endpoint rejects/ignores — losing the
+ * document entirely with no fallback. Leaving it unset keeps the safe
+ * extracted-text path. Images ride `image_url` data URLs, which the compat
+ * endpoint does accept, so supportsImages stays true.
+ */
+export const geminiModels: ReadonlyArray<ModelDescriptor> = [
+  // Gemini 3 family: current frontier. Reasoning models.
+  { id: 'gemini-3-pro', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+  { id: 'gemini-3-flash', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+
+  // Gemini 2.5 family: widely available, strong price/performance. pro/flash
+  // are reasoning models.
+  { id: 'gemini-2.5-pro', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+  { id: 'gemini-2.5-flash', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsReasoning: true },
+  { id: 'gemini-2.5-flash-lite', contextWindow: 1_000_000, maxOutputTokens: 65_536, supportsTools: true, supportsStreaming: true, supportsImages: true },
+];