@moxxy/plugin-provider-openai 0.1.0

package/dist/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG3D,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,UAAU,CAAC;QACjB,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/C,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,iBAAiB,EAAE,CA8E9F;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,aAAa,EAAE,CAS5E"}

package/dist/translate.js

@@ -0,0 +1,92 @@
+import { zodToJsonSchema } from '@moxxy/sdk';
+export function toOpenAIMessages(messages) {
+    const out = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            const text = msg.content.find((c) => c.type === 'text')?.text ?? '';
+            if (text)
+                out.push({ role: 'system', content: text });
+            continue;
+        }
+        if (msg.role === 'user') {
+            const hasRichPart = msg.content.some((c) => c.type === 'image' || c.type === 'document');
+            if (hasRichPart) {
+                // Vision/document user message: emit content as a parts array so
+                // base64 images and documents (PDFs) ride alongside text. Non-vision
+                // / non-document OpenAI models will 400 on this shape — callers gate
+                // by `supportsImages` / `supportsDocuments` on the model descriptor
+                // before attaching.
+                const parts = [];
+                for (const c of msg.content) {
+                    if (c.type === 'text') {
+                        parts.push({ type: 'text', text: c.text });
+                    }
+                    else if (c.type === 'image') {
+                        parts.push({
+                            type: 'image_url',
+                            image_url: { url: `data:${c.mediaType};base64,${c.data}` },
+                        });
+                    }
+                    else if (c.type === 'document') {
+                        parts.push({
+                            type: 'file',
+                            file: {
+                                ...(c.name ? { filename: c.name } : {}),
+                                file_data: `data:${c.mediaType};base64,${c.data}`,
+                            },
+                        });
+                    }
+                }
+                out.push({ role: 'user', content: parts });
+            }
+            else {
+                const text = msg.content
+                    .filter((c) => c.type === 'text')
+                    .map((c) => c.text)
+                    .join('\n');
+                out.push({ role: 'user', content: text });
+            }
+            continue;
+        }
+        if (msg.role === 'assistant') {
+            const text = msg.content
+                .filter((c) => c.type === 'text')
+                .map((c) => c.text)
+                .join('');
+            const toolUses = msg.content.filter((c) => c.type === 'tool_use');
+            const message = { role: 'assistant', content: text || null };
+            if (toolUses.length > 0) {
+                message.tool_calls = toolUses.map((u) => ({
+                    id: u.id,
+                    type: 'function',
+                    function: { name: u.name, arguments: JSON.stringify(u.input ?? {}) },
+                }));
+            }
+            out.push(message);
+            continue;
+        }
+        if (msg.role === 'tool_result') {
+            for (const block of msg.content) {
+                if (block.type === 'tool_result') {
+                    out.push({
+                        role: 'tool',
+                        tool_call_id: block.toolUseId,
+                        content: block.content,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+export function toOpenAITools(tools) {
+    return tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: (t.inputJsonSchema ?? zodToJsonSchema(t.inputSchema)),
+        },
+    }));
+}
+//# sourceMappingURL=translate.js.map

package/dist/translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.js","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"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"}

package/dist/validate.d.ts

@@ -0,0 +1,28 @@
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export interface ValidateKeyDeps {
+    /** Inject the OpenAI SDK constructor for tests. */
+    readonly client?: (apiKey: string) => {
+        models: {
+            list: () => Promise<unknown>;
+        };
+    };
+    /**
+     * Endpoint to probe. Omit for OpenAI itself; pass a vendor base URL to
+     * validate an OpenAI-compatible provider (groq, deepseek, openrouter, …)
+     * against its own `/v1/models`. Lets `@moxxy/plugin-provider-admin` reuse
+     * this validator instead of duplicating the OpenAI-compatible probe.
+     */
+    readonly baseURL?: string;
+}
+/**
+ * "Is this key accepted by the endpoint?" Lists models — free, no inference
+ * cost. Validates OpenAI by default, or an OpenAI-compatible vendor when a
+ * `baseURL` is supplied.
+ */
+export declare function validateKey(key: string, deps?: ValidateKeyDeps): Promise<ValidationResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK;QACpC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;SAAE,CAAC;KAC1C,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAYpG"}

package/dist/validate.js

@@ -0,0 +1,24 @@
+import OpenAI from 'openai';
+/**
+ * "Is this key accepted by the endpoint?" Lists models — free, no inference
+ * cost. Validates OpenAI by default, or an OpenAI-compatible vendor when a
+ * `baseURL` is supplied.
+ */
+export async function validateKey(key, deps = {}) {
+    if (!key || key.trim().length < 8) {
+        return { ok: false, message: 'key looks too short' };
+    }
+    const make = deps.client ?? ((k) => defaultMaker(k, deps.baseURL));
+    try {
+        const client = make(key);
+        await client.models.list();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+}
+function defaultMaker(apiKey, baseURL) {
+    return new OpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) });
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAkB5B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,OAAwB,EAAE;IACvE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAClF,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,OAAgB;IACpD,OAAO,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAE5D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@moxxy/plugin-provider-openai",
+  "version": "0.1.0",
+  "description": "OpenAI (and OpenAI-compatible: z.ai, xAI, Google, Ollama/local) LLMProvider plugin for moxxy. Streams Chat Completions with tool_calls; translates moxxy ProviderRequest/Event ↔ the OpenAI wire shape. Register it into an @moxxy/core Session to route turns to OpenAI-compatible models.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "provider",
+    "openai",
+    "llm",
+    "tool-calls"
+  ],
+  "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-openai"
+  },
+  "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": {
+    "openai": "^4.80.0",
+    "@moxxy/sdk": "0.15.0"
+  },
+  "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/compat.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import type { ModelDescriptor } from '@moxxy/sdk';
+import {
+  defineOpenAICompatProvider,
+  pickOpenAICompatConfig,
+} from './compat.js';
+
+const TEST_MODELS: ReadonlyArray<ModelDescriptor> = [
+  { id: 'vendor-flagship', contextWindow: 1_000_000, supportsTools: true, supportsStreaming: true },
+  { id: 'vendor-mini', contextWindow: 128_000, supportsTools: true, supportsStreaming: true },
+];
+
+describe('pickOpenAICompatConfig', () => {
+  it('keeps only string apiKey/baseURL/defaultModel and drops everything else', () => {
+    const picked = pickOpenAICompatConfig({
+      apiKey: 'k',
+      baseURL: 'https://vendor/v1',
+      defaultModel: 'vendor-mini',
+      extraneous: 'ignored',
+    });
+    expect(picked).toEqual({ apiKey: 'k', baseURL: 'https://vendor/v1', defaultModel: 'vendor-mini' });
+  });
+
+  it('drops wrong-typed fields (falls back to undefined) instead of smuggling them through', () => {
+    const picked = pickOpenAICompatConfig({
+      apiKey: 'k',
+      baseURL: { not: 'a string' },
+      defaultModel: ['nope'],
+    });
+    expect(picked).toEqual({ apiKey: 'k', baseURL: undefined, defaultModel: undefined });
+  });
+});
+
+describe('defineOpenAICompatProvider', () => {
+  const def = defineOpenAICompatProvider({
+    name: 'vendor',
+    baseURL: 'https://vendor.example/v1',
+    defaultModel: 'vendor-flagship',
+    models: TEST_MODELS,
+    auth: { kind: 'apiKey', hint: 'vendor key' },
+  });
+
+  it('stamps the vendor slug onto the def and the built client (not openai)', () => {
+    expect(def.name).toBe('vendor');
+    const client = def.createClient({ apiKey: 'test-key' });
+    expect(client.name).toBe('vendor');
+  });
+
+  it('forces the vendor catalog onto the def and the built client', () => {
+    expect(def.models).toEqual(TEST_MODELS);
+    const client = def.createClient({ apiKey: 'test-key' });
+    expect(client.models).toEqual(TEST_MODELS);
+  });
+
+  it('returns a fresh copy of the catalog (not the caller-owned array)', () => {
+    expect(def.models).not.toBe(TEST_MODELS);
+  });
+
+  it('narrows the untyped registry config — wrong-typed fields do not crash createClient', () => {
+    const messy: Record<string, unknown> = {
+      apiKey: 'test-key',
+      baseURL: { not: 'a string' },
+      defaultModel: ['nope'],
+      extraneous: 'ignored',
+    };
+    const client = def.createClient(messy);
+    expect(client.name).toBe('vendor');
+    expect(client.models).toEqual(TEST_MODELS);
+    expect(typeof client.stream).toBe('function');
+  });
+
+  it('passes the auth descriptor straight through', () => {
+    expect(def.auth).toEqual({ kind: 'apiKey', hint: 'vendor key' });
+  });
+
+  it('omits auth when none is supplied', () => {
+    const noAuth = defineOpenAICompatProvider({
+      name: 'vendor',
+      baseURL: 'https://vendor.example/v1',
+      defaultModel: 'vendor-flagship',
+      models: TEST_MODELS,
+    });
+    expect(noAuth.auth).toBeUndefined();
+  });
+
+  it('wires validateKey by default and short-circuits a too-short key without a network call', async () => {
+    expect(def.validateKey).toBeDefined();
+    // The real validateOpenAICompatKey rejects keys < 8 chars before any probe,
+    // proving the def is wired to the shared validator (no network needed).
+    await expect(def.validateKey?.('')).resolves.toEqual({ ok: false, message: 'key looks too short' });
+  });
+
+  it('omits validateKey entirely when validate: false (local servers do not authenticate)', () => {
+    const local = defineOpenAICompatProvider({
+      name: 'local',
+      baseURL: 'http://localhost:11434/v1',
+      defaultModel: 'llama3.3',
+      models: TEST_MODELS,
+      validate: false,
+    });
+    expect(local.validateKey).toBeUndefined();
+  });
+
+  it('uses resolveApiKey / resolveBaseURL hooks for per-call credential fallback', () => {
+    const seen: Array<{ apiKey?: string; baseURL?: string }> = [];
+    const def2 = defineOpenAICompatProvider({
+      name: 'local',
+      baseURL: 'http://localhost:11434/v1',
+      defaultModel: 'llama3.3',
+      models: TEST_MODELS,
+      validate: false,
+      resolveApiKey: (cfg) => {
+        seen.push({ apiKey: cfg.apiKey });
+        return cfg.apiKey ?? 'placeholder';
+      },
+      resolveBaseURL: (cfg) => {
+        seen.push({ baseURL: cfg.baseURL });
+        return cfg.baseURL ?? 'http://fallback/v1';
+      },
+    });
+    const client = def2.createClient({});
+    expect(client.name).toBe('local');
+    // Both hooks ran (per-call) against the narrowed config.
+    expect(seen).toContainEqual({ apiKey: undefined });
+    expect(seen).toContainEqual({ baseURL: undefined });
+  });
+});

package/src/compat.ts

@@ -0,0 +1,105 @@
+import { defineProvider, type ModelDescriptor, type ProviderAuthDescriptor, type ProviderDef } from '@moxxy/sdk';
+import { OpenAIProvider, type OpenAIProviderConfig } from './provider.js';
+import { validateKey as validateOpenAICompatKey } from './validate.js';
+
+/**
+ * The slice of the registry's untyped `Record<string, unknown>` config that an
+ * OpenAI-compatible vendor actually forwards. The provider registry hands
+ * `createClient` a `Record<string, unknown>` (resolved credentials + any
+ * persisted provider config); only these three optional strings are ever
+ * meaningful to the underlying {@link OpenAIProvider}, so we narrow to them.
+ */
+export interface OpenAICompatConfig {
+  readonly apiKey?: string;
+  readonly baseURL?: string;
+  readonly defaultModel?: string;
+}
+
+/**
+ * Narrow the registry's untyped config down to the handful of optional string
+ * fields an OpenAI-compatible vendor forwards (`apiKey`/`baseURL`/`defaultModel`).
+ * A blanket `config as OpenAIProviderConfig` cast would silently smuggle any
+ * wrong-typed field straight through to the client; this pick keeps only
+ * known-good strings so a bad value falls back to the vendor defaults instead.
+ */
+export function pickOpenAICompatConfig(config: Record<string, unknown>): OpenAICompatConfig {
+  const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
+  return {
+    apiKey: str(config.apiKey),
+    baseURL: str(config.baseURL),
+    defaultModel: str(config.defaultModel),
+  };
+}
+
+export interface DefineOpenAICompatProviderSpec {
+  /**
+   * Vendor slug (e.g. `xai`, `zai`, `google`, `local`). Stamped onto the
+   * underlying client so usage stats, provider_request/response events and
+   * error context attribute to the vendor, NOT `openai`.
+   */
+  readonly name: string;
+  /** Vendor base URL. Config may override it (narrow string pick); else this default is used. */
+  readonly baseURL: string;
+  /** Default model when a request didn't pin one. Config may override it (narrow string pick). */
+  readonly defaultModel: string;
+  /** The vendor's model catalog, forced onto the client (so context-window/capability lookups hit the vendor's models). */
+  readonly models: ReadonlyArray<ModelDescriptor>;
+  /** Auth descriptor surfaced to the setup wizard / `moxxy login`. */
+  readonly auth?: ProviderAuthDescriptor;
+  /**
+   * Key validation. When `true` (the default), wire `validateOpenAICompatKey`
+   * to probe `baseURL`'s `/models`. When `false`, omit `validateKey` entirely
+   * (local servers don't authenticate, so probing a possibly-offline box would
+   * surface confusing setup errors).
+   */
+  readonly validate?: boolean;
+  /**
+   * Optional override for resolving the API key from the narrowed config.
+   * Defaults to `config.apiKey`. The `local` provider uses this to fall back to
+   * an env var + placeholder, since the OpenAI SDK requires a non-empty key but
+   * local servers don't authenticate.
+   */
+  readonly resolveApiKey?: (config: OpenAICompatConfig) => string | undefined;
+  /**
+   * Optional override for resolving the base URL from the narrowed config.
+   * Defaults to `config.baseURL ?? baseURL`. The `local` provider uses this to
+   * insert an env-var fallback (`LOCAL_MODEL_BASE_URL`) between the config and
+   * the static default, read per-call.
+   */
+  readonly resolveBaseURL?: (config: OpenAICompatConfig) => string;
+}
+
+/**
+ * Build a {@link ProviderDef} for any vendor that speaks the OpenAI Chat
+ * Completions wire protocol. Centralizes the construction shared by xai / zai /
+ * google / local and the runtime-registered (`provider-admin`) vendors: it
+ * reuses the shared {@link OpenAIProvider} with the vendor slug + base URL +
+ * default model + catalog forced on, and (unless `validate: false`) wires
+ * `validateOpenAICompatKey` against the vendor's base URL.
+ *
+ * The per-vendor file becomes a single declarative call carrying only the
+ * vendor's constants; the cfg-narrowing + slug-forcing + validate wiring live
+ * here once.
+ */
+export function defineOpenAICompatProvider(spec: DefineOpenAICompatProviderSpec): ProviderDef {
+  const resolveApiKey = spec.resolveApiKey ?? ((cfg: OpenAICompatConfig) => cfg.apiKey);
+  const resolveBaseURL = spec.resolveBaseURL ?? ((cfg: OpenAICompatConfig) => cfg.baseURL ?? spec.baseURL);
+  return defineProvider({
+    name: spec.name,
+    models: [...spec.models],
+    createClient: (config) => {
+      const cfg = pickOpenAICompatConfig(config);
+      return new OpenAIProvider({
+        apiKey: resolveApiKey(cfg),
+        name: spec.name,
+        baseURL: resolveBaseURL(cfg),
+        defaultModel: cfg.defaultModel ?? spec.defaultModel,
+        models: spec.models,
+      } satisfies OpenAIProviderConfig);
+    },
+    ...(spec.validate === false
+      ? {}
+      : { validateKey: (key: string) => validateOpenAICompatKey(key, { baseURL: spec.baseURL }) }),
+    ...(spec.auth ? { auth: spec.auth } : {}),
+  });
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+import { defineProvider, definePlugin } from '@moxxy/sdk';
+import { OpenAIProvider, openAIModels, type OpenAIProviderConfig } from './provider.js';
+
+export { OpenAIProvider, openAIModels };
+export type { OpenAIProviderConfig };
+export { toOpenAIMessages, toOpenAITools } from './translate.js';
+export { validateKey, type ValidateKeyDeps, type ValidationResult } from './validate.js';
+// DI-friendly alias: any OpenAI-compatible vendor (same `models.list` probe)
+// can reuse this validator. Re-exported under a vendor-neutral name so other
+// packages don't couple to the OpenAI-specific `validateKey` symbol.
+export { validateKey as validateOpenAICompatKey } from './validate.js';
+// Shared factory for OpenAI-Chat-Completions-compatible vendors (xai/zai/google/
+// local + runtime provider-admin entries). Captures the slug-forcing client
+// construction + config narrowing + validateKey wiring in one place.
+export {
+  defineOpenAICompatProvider,
+  pickOpenAICompatConfig,
+  type DefineOpenAICompatProviderSpec,
+  type OpenAICompatConfig,
+} from './compat.js';
+
+import { validateKey as validateOpenAIKey } from './validate.js';
+
+export const openaiProviderDef = defineProvider({
+  name: 'openai',
+  models: [...openAIModels],
+  createClient: (config) => new OpenAIProvider(config as OpenAIProviderConfig),
+  validateKey: (key) => validateOpenAIKey(key),
+});
+
+export const openaiPlugin = definePlugin({
+  name: '@moxxy/plugin-provider-openai',
+  version: '0.0.0',
+  providers: [openaiProviderDef],
+});
+
+export default openaiPlugin;