@moxxy/plugin-provider-admin 0.26.0

package/dist/store.js

@@ -0,0 +1,108 @@
+import { promises as fs } from 'node:fs';
+import { createMutex, z } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+/**
+ * User-level provider catalog. Mirrors the MCP admin storage pattern:
+ * a JSON file in ~/.moxxy/ that the admin tools mutate and the plugin's
+ * onInit hook reads back on every boot to repopulate the registry.
+ */
+export function providersConfigPath() {
+    return moxxyPath('providers.json');
+}
+/**
+ * Schema for the on-disk providers.json. Kept loose on the model
+ * descriptor (passthrough) so a richer descriptor written by a newer
+ * build round-trips through an older one without losing fields, but
+ * strict enough to discard a structurally-bogus file.
+ */
+const storedModelSchema = z
+    .object({
+    id: z.string().min(1),
+    contextWindow: z.number(),
+    // ModelDescriptor declares these as REQUIRED booleans; default them here so
+    // a hand-edited / legacy providers.json round-trips into a complete
+    // descriptor instead of reaching buildProviderDef with `undefined` (which
+    // channels treat differently from `false` for tool/streaming gating).
+    supportsTools: z.boolean().default(true),
+    supportsStreaming: z.boolean().default(true),
+})
+    .passthrough();
+const storedProviderSchema = z
+    .object({
+    kind: z.literal('openai-compat'),
+    name: z.string().min(1),
+    baseURL: z.string().min(1),
+    defaultModel: z.string().min(1),
+    models: z.array(storedModelSchema),
+    envVar: z.string().optional(),
+    createdAt: z.string().optional(),
+})
+    .passthrough();
+const storedProvidersConfigSchema = z.object({
+    providers: z.array(storedProviderSchema),
+});
+export async function readProvidersConfig(filePath = providersConfigPath()) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        // A MISSING file means "no providers yet" — start fresh. But a genuine IO /
+        // permission error (EACCES, EBUSY, EMFILE, …) must NOT be collapsed into an
+        // empty catalog: doing so makes the plugin behave as if zero providers are
+        // registered and the next read-modify-write would CLOBBER the real file.
+        // Rethrow so callers (onInit's try/catch, the admin tools) see the failure.
+        if (err?.code === 'ENOENT')
+            return { providers: [] };
+        throw err;
+    }
+    // Malformed JSON / structurally-bogus content is intentionally treated as an
+    // empty catalog (start fresh) rather than a hard failure.
+    const parsed = storedProvidersConfigSchema.safeParse(parseJsonSafe(raw));
+    if (parsed.success) {
+        // The schema is intentionally looser than StoredProvidersConfig (model
+        // descriptors are validated as id+contextWindow + passthrough, not the
+        // full ModelDescriptor) so newer/older builds round-trip without losing
+        // fields. Assert the domain type after the structural check.
+        return parsed.data;
+    }
+    return { providers: [] };
+}
+function parseJsonSafe(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeProvidersConfig(cfg, filePath = providersConfigPath()) {
+    await writeFileAtomic(filePath, JSON.stringify(cfg, null, 2) + '\n');
+}
+/**
+ * Serializes the read-modify-write mutators below. Without this, two
+ * concurrent upsert/remove calls could both read the same baseline and
+ * the second write would clobber the first.
+ */
+const writeMutex = createMutex();
+export async function upsertStoredProvider(entry, filePath = providersConfigPath()) {
+    return writeMutex.run(async () => {
+        const cfg = await readProvidersConfig(filePath);
+        const next = cfg.providers.filter((p) => p.name !== entry.name);
+        next.push(entry);
+        const updated = { providers: next };
+        await writeProvidersConfig(updated, filePath);
+        return updated;
+    });
+}
+export async function removeStoredProvider(name, filePath = providersConfigPath()) {
+    return writeMutex.run(async () => {
+        const cfg = await readProvidersConfig(filePath);
+        const next = cfg.providers.filter((p) => p.name !== name);
+        if (next.length === cfg.providers.length)
+            return false;
+        await writeProvidersConfig({ providers: next }, filePath);
+        return true;
+    });
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+import type { ModelDescriptor } from '@moxxy/sdk';
+/**
+ * Persisted entry for a user-registered LLM provider. Lives in
+ * ~/.moxxy/providers.json and is re-read on every boot to re-register
+ * the provider against the in-process registry.
+ *
+ * Phase 1 only supports `openai-compat` — i.e. vendors that speak the
+ * OpenAI Chat Completions wire protocol (z.ai, deepseek, groq,
+ * openrouter, fireworks, together, mistral, …). The host wraps the
+ * shared `@moxxy/plugin-provider-openai` client with the vendor's
+ * `baseURL`, so we don't reimplement streaming for each new vendor.
+ *
+ * Future kinds (e.g. `anthropic-compat`, native vendor SDKs) extend the
+ * discriminated union; the rest of the pipeline (store + onInit) is
+ * agnostic so they slot in without touching the persistence layer.
+ */
+export interface StoredProviderOpenAICompat {
+    readonly kind: 'openai-compat';
+    /** Provider name (slug). Becomes the registry key + canonical vault entry stem. */
+    readonly name: string;
+    /** Vendor base URL, e.g. `https://api.z.ai/api/coding/paas/v4`. */
+    readonly baseURL: string;
+    /** Model id used when the request didn't pin one explicitly. */
+    readonly defaultModel: string;
+    /** Models the vendor exposes. Powers `/model` autocomplete + the setup wizard. */
+    readonly models: ReadonlyArray<ModelDescriptor>;
+    /** Optional vendor-supplied env var name for the API key (defaults to `<NAME>_API_KEY`). */
+    readonly envVar?: string;
+    /** ISO timestamp the entry was written. Informational only. */
+    readonly createdAt?: string;
+}
+export type StoredProvider = StoredProviderOpenAICompat;
+export interface StoredProvidersConfig {
+    readonly providers: ReadonlyArray<StoredProvider>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAChD,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACnD"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@moxxy/plugin-provider-admin",
+  "version": "0.26.0",
+  "description": "Model-callable provider admin: provider_add / provider_list / provider_remove / provider_test. Persists user-registered providers to ~/.moxxy/providers.json and hot-registers them in the live session by wrapping the OpenAI-compatible client with a vendor baseURL.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "provider",
+    "admin",
+    "tools"
+  ],
+  "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-admin"
+  },
+  "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": "tools"
+    }
+  },
+  "dependencies": {
+    "openai": "^4.80.0",
+    "zod": "^3.24.0",
+    "@moxxy/plugin-provider-openai": "0.26.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "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/configure.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { MoxxyError, type ProviderDef } from '@moxxy/sdk';
+import { buildProviderAdminPluginWithApi, type ProviderRegistryLike } from './index.js';
+import { readProvidersConfig, upsertStoredProvider } from './store.js';
+import type { StoredProvider } from './types.js';
+
+class FakeRegistry implements ProviderRegistryLike {
+  defs = new Map<string, ProviderDef>();
+  register(def: ProviderDef): void {
+    if (this.defs.has(def.name)) throw new Error(`already registered: ${def.name}`);
+    this.defs.set(def.name, def);
+  }
+  replace(def: ProviderDef): void {
+    this.defs.set(def.name, def);
+  }
+  unregister(name: string): void {
+    this.defs.delete(name);
+  }
+  list(): ReadonlyArray<ProviderDef> {
+    return [...this.defs.values()];
+  }
+}
+
+let tmpDir: string;
+let cfgPath: string;
+let registry: FakeRegistry;
+
+const zaiEntry: StoredProvider = {
+  kind: 'openai-compat',
+  name: 'zai',
+  baseURL: 'https://api.z.ai/api/coding/paas/v4',
+  defaultModel: 'glm-4.6',
+  models: [
+    { id: 'glm-4.6', contextWindow: 200_000, supportsTools: true, supportsStreaming: true },
+    { id: 'glm-4.5-air', contextWindow: 128_000, supportsTools: true, supportsStreaming: true },
+  ],
+  createdAt: new Date('2026-01-01').toISOString(),
+};
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-provider-admin-configure-'));
+  cfgPath = path.join(tmpDir, 'providers.json');
+  registry = new FakeRegistry();
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+function build(reg: ProviderRegistryLike = registry) {
+  return buildProviderAdminPluginWithApi({ providerRegistry: reg, configPath: cfgPath });
+}
+
+async function seedZai(): Promise<void> {
+  await upsertStoredProvider(zaiEntry, cfgPath);
+}
+
+describe('buildProviderAdminPluginWithApi.configure', () => {
+  it('throws CONFIG_INVALID when no stored provider has that name', async () => {
+    const { api } = build();
+    const err = await api.configure('nope', { defaultModel: 'x' }).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as MoxxyError).message).toMatch(/no stored provider named "nope"/);
+  });
+
+  it('refuses to reconfigure a built-in provider (reserved name)', async () => {
+    const reg = new FakeRegistry();
+    reg.register({ name: 'openai', models: [{ id: 'gpt-x', contextWindow: 1 }] } as unknown as ProviderDef);
+    const { api } = build(reg);
+    const err = await api.configure('openai', { defaultModel: 'gpt-x' }).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as MoxxyError).message).toMatch(/built-in/i);
+  });
+
+  it('merges only the provided patch fields, leaving the rest intact', async () => {
+    await seedZai();
+    const { api } = build();
+    await api.configure('zai', { baseURL: 'https://new.example.com/v1' });
+    const cfg = await readProvidersConfig(cfgPath);
+    const stored = cfg.providers.find((p) => p.name === 'zai')!;
+    expect(stored.baseURL).toBe('https://new.example.com/v1');
+    // Untouched fields preserved.
+    expect(stored.defaultModel).toBe('glm-4.6');
+    expect(stored.models.map((m) => m.id)).toEqual(['glm-4.6', 'glm-4.5-air']);
+  });
+
+  it('throws CONFIG_INVALID when the merged defaultModel is not in the models list', async () => {
+    await seedZai();
+    const { api } = build();
+    const err = await api.configure('zai', { defaultModel: 'not-a-model' }).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as MoxxyError).message).toMatch(/not in the models list/);
+  });
+
+  it('lets defaultModel point at a model introduced by the same patch', async () => {
+    await seedZai();
+    const { api } = build();
+    await api.configure('zai', {
+      defaultModel: 'glm-4.7',
+      models: [{ id: 'glm-4.7', contextWindow: 256_000, supportsTools: true, supportsStreaming: true }],
+    });
+    const stored = (await readProvidersConfig(cfgPath)).providers.find((p) => p.name === 'zai')!;
+    expect(stored.defaultModel).toBe('glm-4.7');
+    expect(stored.models.map((m) => m.id)).toEqual(['glm-4.7']);
+  });
+
+  it('updates both the live registry def and the on-disk store on success', async () => {
+    await seedZai();
+    // Mirror the runtime: the entry is also live in the registry (onInit would
+    // have registered it). configure() must replace() it, not register().
+    const { plugin, api } = build();
+    await plugin.hooks!.onInit!({} as never);
+    expect(registry.defs.has('zai')).toBe(true);
+
+    await api.configure('zai', { defaultModel: 'glm-4.5-air' });
+    const def = registry.defs.get('zai')!;
+    expect(def.models.find((m) => m.id === 'glm-4.5-air')).toBeTruthy();
+    const stored = (await readProvidersConfig(cfgPath)).providers.find((p) => p.name === 'zai')!;
+    expect(stored.defaultModel).toBe('glm-4.5-air');
+  });
+
+  it('rolls back the live def to the prior registration when the disk write fails', async () => {
+    // The entry is readable on disk AND already live in the registry (owned by
+    // the plugin via onInit), but the write target is made unwritable so
+    // upsertStoredProvider rejects after the live replace() — driving the
+    // rollback branch (restore the prior owned def).
+    await seedZai();
+    const reg = new FakeRegistry();
+    const { plugin, api } = build(reg);
+    // onInit registers + CLAIMS OWNERSHIP of 'zai' (so configure treats it as a
+    // runtime-registered provider, not a reserved built-in).
+    await plugin.hooks!.onInit!({} as never);
+    const priorDef = reg.defs.get('zai')!;
+    expect(priorDef).toBeTruthy();
+
+    // Read still works (file present), but the dir is read-only so the atomic
+    // write's temp-file create / rename fails.
+    await fs.chmod(tmpDir, 0o500);
+    try {
+      const err = await api.configure('zai', { defaultModel: 'glm-4.5-air' }).catch((e) => e);
+      expect(err).toBeTruthy();
+      // The prior def must be restored EXACTLY (not the patched one, not deleted).
+      expect(reg.defs.get('zai')).toBe(priorDef);
+    } finally {
+      await fs.chmod(tmpDir, 0o700);
+    }
+    // Disk is unchanged: still the seeded defaultModel.
+    const stored = (await readProvidersConfig(cfgPath)).providers.find((p) => p.name === 'zai')!;
+    expect(stored.defaultModel).toBe('glm-4.6');
+  });
+});

package/src/discovery.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { providerAdminPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the providers registry +
+ * credential accessor from the service registry in onInit and publishes its
+ * admin api as the 'providerAdmin' service (which Session.providerAdmin exposes),
+ * instead of the host `{ providerRegistry, resolveActiveConfig }` closure + stash.
+ */
+describe('providerAdminPlugin (discovery-loadable)', () => {
+  it('exposes the provider tools + an onInit hook', () => {
+    const names = providerAdminPlugin.tools?.map((t) => t.name) ?? [];
+    expect(names).toContain('provider_add');
+    expect(typeof providerAdminPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves providers + resolveCredentials and publishes providerAdmin', async () => {
+    const registry = {
+      list: () => [],
+      register: () => {},
+      replace: () => {},
+      unregister: () => {},
+      getActiveName: () => null,
+    };
+    const get = vi.fn((name: string) =>
+      name === 'providers' ? registry : name === 'resolveCredentials' ? () => ({}) : undefined,
+    );
+    const register = vi.fn();
+    const services = { get, register, require: () => undefined, has: () => true } as unknown as ServiceRegistry;
+
+    // The inner onInit reads ~/.moxxy/providers.json (absent on CI → caught +
+    // skipped); we only assert the service wiring here.
+    await providerAdminPlugin.hooks!.onInit!({ services } as never);
+
+    expect(get).toHaveBeenCalledWith('providers');
+    expect(get).toHaveBeenCalledWith('resolveCredentials');
+    expect(register).toHaveBeenCalledWith('providerAdmin', expect.anything());
+  });
+});

package/src/factory.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { buildProviderDef } from './factory.js';
+import type { StoredProvider } from './types.js';
+
+describe('buildProviderDef', () => {
+  it('builds an openai-compat ProviderDef wired to the vendor baseURL', () => {
+    const entry: StoredProvider = {
+      kind: 'openai-compat',
+      name: 'zai',
+      baseURL: 'https://api.z.ai/api/coding/paas/v4',
+      defaultModel: 'glm-4.6',
+      models: [
+        { id: 'glm-4.6', contextWindow: 200_000, supportsTools: true, supportsStreaming: true },
+        { id: 'glm-4.5-air', contextWindow: 128_000, supportsTools: true, supportsStreaming: true },
+      ],
+    };
+    const def = buildProviderDef(entry);
+    expect(def.name).toBe('zai');
+    expect(def.models.map((m) => m.id)).toEqual(['glm-4.6', 'glm-4.5-air']);
+    // createClient must produce something with .stream/.countTokens — the
+    // OpenAIProvider satisfies LLMProvider, we just check the shape.
+    const client = def.createClient({ apiKey: 'test-key' });
+    expect(typeof client.stream).toBe('function');
+    expect(typeof client.countTokens).toBe('function');
+    // The client reports the VENDOR's slug + catalog, not 'openai' — usage
+    // stats, provider_request/response events and error context all read
+    // these off the live client, so 'openai' here misattributed every
+    // runtime vendor and missed context-window lookups for their models.
+    expect(client.name).toBe('zai');
+    expect(client.models.map((m) => m.id)).toEqual(['glm-4.6', 'glm-4.5-air']);
+  });
+
+  it('throws for unknown kinds', () => {
+    expect(() => buildProviderDef({ kind: 'mystery' } as unknown as StoredProvider)).toThrow(/unsupported kind/);
+  });
+});

package/src/factory.ts

@@ -0,0 +1,47 @@
+import { MoxxyError, type ProviderDef } from '@moxxy/sdk';
+import { defineOpenAICompatProvider, validateOpenAICompatKey } from '@moxxy/plugin-provider-openai';
+import type { StoredProvider } from './types.js';
+
+/**
+ * Re-export the shared OpenAI-compatible key validator so existing
+ * consumers (and `index.ts`) keep a single import surface. The probe
+ * lives in `@moxxy/plugin-provider-openai` — we don't keep a local copy.
+ */
+export { validateOpenAICompatKey };
+
+/**
+ * Builder for one stored-provider `kind`. New wire-protocol families
+ * (anthropic-compat, native SDKs) register a builder here instead of growing
+ * an if/throw ladder — the rest of the pipeline (store + onInit) stays
+ * kind-agnostic, honoring the forward-compat promise in `types.ts`.
+ */
+type ProviderDefBuilder = (entry: StoredProvider) => ProviderDef;
+
+const PROVIDER_DEF_BUILDERS: Record<StoredProvider['kind'], ProviderDefBuilder> = {
+  // For `openai-compat` we delegate to the shared {@link defineOpenAICompatProvider}
+  // factory that the built-in vendor plugins (xai/zai/google/local) also use: it
+  // forces the vendor's slug + baseURL + default model + catalog onto the shared
+  // OpenAI client and wires validateKey against the same baseURL, so the
+  // setup-wizard / `moxxy doctor --check-keys` paths work end-to-end. The runtime
+  // config only carries the resolved API key, so the factory's narrow pick keeps
+  // just that and the vendor's stored baseURL/defaultModel win.
+  'openai-compat': (entry) =>
+    defineOpenAICompatProvider({
+      name: entry.name,
+      baseURL: entry.baseURL,
+      defaultModel: entry.defaultModel,
+      models: entry.models,
+    }),
+};
+
+/** Build a runtime ProviderDef from a stored entry by dispatching on `kind`. */
+export function buildProviderDef(entry: StoredProvider): ProviderDef {
+  const build = PROVIDER_DEF_BUILDERS[entry.kind];
+  if (!build) {
+    throw new MoxxyError({
+      code: 'CONFIG_INVALID',
+      message: `provider-admin: unsupported kind ${String((entry as { kind: unknown }).kind)}`,
+    });
+  }
+  return build(entry);
+}