@wengine-ai/llms 2.3.2414 → 2.3.2415

package/dist/provider-plugins/host.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The canonical POST-/api-config runtime reload sequence, owned by the core
+ * and handed to plugins via PluginContext.host.reloadRuntime. Before this
+ * existed, every managed subscription provider carried its own
+ * copy — the plugin API exists to end exactly that kind of duplication.
+ */
+export declare function reloadProviderRuntime(server: any, config: any, log: {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}): void;

package/dist/provider-plugins/loader.d.ts

@@ -0,0 +1,33 @@
+import { dirname } from "node:path";
+import { type PluginRegistry } from "./registry";
+export interface PluginLoadResult {
+    loaded: string[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/** Reject symlinked directories, not just lexical traversal. */
+export declare function resolvePluginDir(configDir: string, name: string): string | null;
+/** Resolve the subscription-plugin dispatcher for one server instance: the
+ *  explicit SUBSCRIPTION_PROXY_URL from the live config when a server/config
+ *  service exists, else the initConfig env mirror (host-less loaders). Exported
+ *  for tests — this is the exact closure the plugin host hands out. */
+export declare function resolveSubscriptionDispatcher(server: unknown): unknown;
+export declare function loadInstalledPlugins(deps: {
+    configDir: string;
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+    getServer: () => any;
+    registry?: PluginRegistry;
+}): Promise<PluginLoadResult>;
+/** Production must pass the host registry; default retained only for isolated loader tests. */
+export declare function describeInstalledPlugins(configDir: string, registry?: PluginRegistry): Array<Record<string, unknown>>;
+export { dirname };

package/dist/provider-plugins/registry.d.ts

@@ -0,0 +1,39 @@
+import { type FastifyInstance } from "fastify";
+import type { TransformerService } from "../services/transformer";
+import type { LoadedPluginInfo, ManagedRuntime, PluginClassifiedError, PluginContext, PluginHostCapabilities, PluginManifest } from "./types";
+import { PLUGIN_CORE_API } from "./types";
+type PluginLog = PluginContext["log"];
+/** One registry per Server. No production lookup falls back to the test registry. */
+export declare class PluginRegistry {
+    private plugins;
+    private transformerServices;
+    private disposed;
+    private revision;
+    attachTransformerService(service: TransformerService): void;
+    beginActivation(manifest: PluginManifest, log: PluginLog, host: PluginHostCapabilities, directory?: string): {
+        context: PluginContext;
+        commit: (card?: Buffer, routeHost?: FastifyInstance) => Promise<void>;
+        readonly cardPath: string | undefined;
+        abort: () => void;
+    };
+    getManagedRuntimeFor(provider: any): ManagedRuntime | undefined;
+    getRegisteredRuntimes(): ManagedRuntime[];
+    applyConfigProtectors(next: any, prev: any): void;
+    listLoadedPlugins(): LoadedPluginInfo[];
+    getPublicCard(name: string, file: string): Buffer | undefined;
+    private prepareRoutes;
+    registerAllRoutes(app: FastifyInstance): Promise<void>;
+    dispose(): void;
+    private assertOpen;
+}
+export declare const getTestPluginRegistry: () => PluginRegistry;
+export declare function clearPluginRegistry(): void;
+export declare const getManagedRuntimeFor: (provider: any, registry?: PluginRegistry) => ManagedRuntime | undefined;
+export declare const getRegisteredRuntimes: () => ManagedRuntime[];
+export declare const listLoadedPlugins: () => LoadedPluginInfo[];
+export declare const applyPluginConfigProtectors: (next: any, prev: any) => void;
+export declare const registerAllPluginRoutes: (app: FastifyInstance) => Promise<void>;
+/** Build the core-side thrown error from a plugin classification. */
+export declare function pluginErrorFrom(runtimeName: string, info: PluginClassifiedError): Error & Record<string, any>;
+export declare function isPluginClassifiedError(error: any): boolean;
+export { PLUGIN_CORE_API };

package/dist/provider-plugins/transformer-hook.d.ts

@@ -0,0 +1,3 @@
+import type { PluginContext } from "./types";
+/** Explicit activation context; never a process-wide pointer to a live server. */
+export declare function registerTransformerFromPlugin(context: PluginContext, cls: new () => any): void;

package/dist/provider-plugins/types.d.ts

@@ -0,0 +1,182 @@
+import type { FastifyInstance } from "fastify";
+import type { LLMProvider } from "../types/llm";
+/**
+ * Provider plugin API (docs/design/provider-plugins.md).
+ *
+ * A plugin ships subscription-provider code out of the main package: a
+ * transformer, a managed runtime (upstream lock, token injection, error
+ * taxonomy), admin routes, a config protector and a UI card. The core only
+ * knows this interface — never the provider internals.
+ *
+ * Lives in `src/provider-plugins/` deliberately: `src/plugins/` is the older
+ * output-plugin system (token-speed) and must not mix namespaces.
+ *
+ * `coreApi` is a semver-ish compatibility marker. The core refuses plugins
+ * whose major does not match its own, so the public contract can evolve
+ * without silently breaking third parties.
+ */
+export declare const PLUGIN_CORE_API = "1";
+export interface PluginManifest {
+    name: string;
+    version: string;
+    coreApi: string;
+    description?: string;
+}
+/** A classified upstream error, shared shape across providers (contract §1.6). */
+export interface PluginClassifiedError {
+    code: string;
+    message: string;
+    httpStatus: number;
+    cooldownMs?: number;
+    validationUrl?: string;
+    retryable?: boolean;
+}
+/**
+ * Input for a runtime-owned bounded dispatch wrapper (`dispatchRequest`). The
+ * core supplies its ordinary single-attempt dispatch as `attempt()` — every
+ * generic seam (ensureUsable/lockUpstream/signRequest/classifyError/
+ * noteUpstreamError, the 401-once refresh budget, response-error
+ * confidentiality) runs INSIDE each attempt; the wrapper only owns the loop
+ * around it (e.g. rotating local credentials). The generic same-model retry
+ * and fallback chains stay in the core and are never re-implemented by a
+ * wrapper.
+ */
+export interface PluginDispatchInput {
+    /** One ordinary core dispatch attempt. May be called several times, always
+     *  within the runtime's own hard bound (≤ its credential count and ≤ a
+     *  constant cap). */
+    attempt(): Promise<Response>;
+    /** Finalized request body (body-derived account selection works). */
+    requestBody: any;
+    /** The per-provider request config; a wrapper may attach per-attempt state
+     *  that lockUpstream/signRequest read back on the same object. */
+    config: any;
+    provider: LLMProvider;
+    /** The originating request object (shared identity across retry/fallback
+     *  spreads) for per-request wrapper state. */
+    req?: any;
+}
+/**
+ * Managed-subscription semantics for one provider family. Everything the data
+ * plane needs to talk to a subscription upstream without the core knowing it:
+ * fixed upstream, token injection, error taxonomy, cooling circuit breaker.
+ */
+export interface ManagedRuntime {
+    /** Provider family name, e.g. "codex". Used for logging and 401 bookkeeping keys. */
+    name: string;
+    isManaged(provider: LLMProvider): boolean;
+    /** Circuit breaker before any network touch (Gemini lesson: must run BEFORE token refresh). */
+    ensureUsable?(): Promise<void>;
+    /** Lock the upstream: mutate config.url / redirect / dispatcher. Runs once per attempt. */
+    lockUpstream?(config: any, provider: LLMProvider): Promise<void>;
+    /**
+     * Final header injection — called AFTER the request body is finalized, so
+     * body-derived headers (e.g. Codex session-id from prompt_cache_key) work.
+     * Returns the headers object to send. `config` is the per-attempt request
+     * config (optional for backward compatibility): a dispatch wrapper can
+     * select per-attempt credential material on it and the final header
+     * injection reads it back; hosts that predate the field leave wrappers to
+     * their own lockUpstream-saved state.
+     */
+    signRequest(input: {
+        headers: Record<string, string>;
+        requestBody: any;
+        provider: LLMProvider;
+        config?: any;
+    }): Promise<Record<string, string>>;
+    /**
+     * Classify an upstream failure into the shared taxonomy. Return null to let
+     * the next handler (built-in branches, then generic) deal with it.
+     */
+    classifyError?(status: number, body: unknown, systemText: string): PluginClassifiedError | null;
+    /** Persist a classified error (cooldown, lastError). Must never throw into the response path. */
+    noteUpstreamError?(info: PluginClassifiedError): Promise<void>;
+    /**
+     * Generic HTTP-200 hidden-error-envelope detector. When present, the core
+     * runs it against every parsed JSON 200 body and throws through the shared
+     * classification seam when it returns true — BEFORE the generic `error`
+     * field check, because some upstreams carry `{code,msg,data}` envelopes
+     * without an `error` key. This is a SECONDARY safety net for runtimes with
+     * a dispatch wrapper: rotation on such envelopes must happen inside the
+     * wrapper (before the response is returned); this hook only catches bodies
+     * a wrapper has already returned.
+     */
+    isErrorEnvelope?(body: unknown): boolean;
+    /**
+     * Optional bounded multi-attempt dispatcher (see PluginDispatchInput). When
+     * present the core calls it instead of performing its single attempt and
+     * forwards the returned response to the client. The wrapper MUST enforce a
+     * hard attempt bound and must never swallow client aborts.
+     */
+    dispatchRequest?(input: PluginDispatchInput): Promise<Response>;
+    /**
+     * Opt-in 401 handling: when set, the core performs ONE forced refresh and
+     * re-dispatch on 401 before classifying. `refresh` must persist rotated
+     * refresh tokens before the in-memory identity switches.
+     */
+    authRefresh?: {
+        forceRefresh(): Promise<void>;
+    };
+    /** Suppress the request/response debug logs for this provider (token hygiene). */
+    suppressDebugLog?: boolean;
+}
+/**
+ * Host capabilities handed to a plugin at activation. Plugins must use THESE
+ * for anything stateful (config reads/writes, runtime reload, directories) —
+ * bundling a copy of a core module would fork its in-process state.
+ */
+export interface PluginHostCapabilities {
+    /** CCR config dir ($CCR_CONFIG_DIR), for the plugin's private credential file. */
+    configDir: string;
+    readConfig(): Promise<any>;
+    writeConfig(next: any): Promise<void>;
+    /**
+     * Read config WITHOUT env-var interpolation. Managed providers must do their
+     * read-modify-write against this: `readConfig` interpolates $VAR placeholders,
+     * so writing it back would bake env values into config.json. Optional for
+     * backward compatibility; hosts that predate it only offer `readConfig`.
+     */
+    readRawConfig?(): Promise<any>;
+    /**
+     * Re-resolve providers/transformers after a config write (server reload).
+     * The config argument is the JUST-WRITTEN config; passing it avoids a reread
+     * race between write and reload. Optional parameter for backward compat.
+     */
+    reloadRuntime(config?: any): Promise<void>;
+    /** undici Agent that bypasses CCR/proxy env routing (for fixed subscription origins). */
+    getDirectDispatcher(): unknown;
+    /**
+     * Dispatcher for fixed subscription origins honoring the explicit
+     * SUBSCRIPTION_PROXY_URL opt-in: the direct agent when unset, a ProxyAgent
+     * for the configured URL otherwise. Optional for backward compatibility —
+     * hosts that predate it only offer getDirectDispatcher (fully direct).
+     */
+    getSubscriptionDispatcher?(): unknown;
+}
+export interface PluginContext {
+    readonly manifest: PluginManifest;
+    readonly log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+    readonly host: PluginHostCapabilities;
+    registerTransformer(cls: new () => any): void;
+    registerManagedRuntime(rt: ManagedRuntime): void;
+    registerAdminRoutes(fn: (app: FastifyInstance) => void): void;
+    registerConfigProtector(fn: (next: any, prev: any) => void): void;
+    /** Path to the prebuilt card chunk, relative to the plugin directory. */
+    registerUiCard(def: {
+        cardPath: string;
+    }): void;
+    registerLocales(bundle: Record<string, Record<string, unknown>>): void;
+}
+export interface LoadedPluginInfo {
+    name: string;
+    version: string;
+    enabled: true;
+    /** Served by the core at this URL for the UI to dynamic-import. */
+    cardUrl?: string;
+    locales?: Record<string, Record<string, unknown>>;
+    error?: string;
+}

package/dist/server.d.ts

@@ -6,6 +6,7 @@ import { TokenizerService } from "./services/tokenizer";
 import { router, calculateTokenCount, searchProjectBySession } from "./utils/router";
 import { sessionUsageCache } from "./utils/cache";
 import { ActiveProbeService } from "./services/active-probe";
+import { PluginRegistry } from "./provider-plugins/registry";
 import type { CcrPreHandlerCallbacks } from "./ccr/request-pipeline";
 declare module "fastify" {
     interface FastifyRequest {
@@ -27,11 +28,18 @@ export interface ServerOptions extends FastifyServerOptions {
 }
 declare class Server {
     app: FastifyInstance;
+    readonly pluginRegistry: PluginRegistry;
+    private namespaceProviders;
+    /** Reload in place: registered namespaces must not retain stale provider maps. */
+    reloadProviders(config: any): void;
+    /** Explicit namespace-owned config update; never merge root provider authority. */
+    reloadNamespaceProviders(name: string, providers: any[]): void;
     configService: ConfigService;
     providerService: ProviderService;
     transformerService: TransformerService;
     tokenizerService: TokenizerService;
     activeProbeService?: ActiveProbeService;
+    /** Gemini OAuth (Antigravity) managed-provider auth service. */
     recordUsage?: (data: any) => void;
     private readonly readiness;
     private mainNamespaceRegistered;

package/dist/services/active-probe.d.ts

@@ -20,7 +20,7 @@ export interface ActiveProbeConfig {
     /** Providers to exclude from active probing (e.g., providers without models endpoint) */
     excludeProviders?: string[];
 }
-export type ProviderProbeStatus = 'healthy' | 'slow' | 'error' | 'timeout';
+export type ProviderProbeStatus = 'healthy' | 'slow' | 'error' | 'timeout' | 'skipped';
 export type ProviderProbeErrorKind = 'timeout' | 'network' | 'http';
 export type ProviderProbeSource = 'health' | 'manual' | 'rate-limit-headers';
 export interface ProviderProbeTelemetry {
@@ -36,6 +36,7 @@ export interface ProviderProbeTelemetry {
 }
 export interface ManualProbeResult {
     success: boolean;
+    skipped?: boolean;
     latencyMs: number;
     status: ProviderProbeStatus;
     isSlow: boolean;

package/dist/services/provider-health.d.ts

@@ -62,7 +62,7 @@ export declare class ProviderHealthStore {
      * Check if a provider/model is available for routing
      * closed = available, half-open = available (lower priority), open = unavailable
      */
-    isAvailable(provider: string, model: string): boolean;
+    isAvailable(provider: string, model: string, allowRecoveryProbe?: boolean): boolean;
     /**
      * Get health status priority for sorting
      * Returns: 0 = closed (best), 1 = half-open (ok), 2 = open (worst)

package/dist/services/provider.d.ts

@@ -8,6 +8,8 @@ export declare class ProviderService {
     private providers;
     private modelRoutes;
     constructor(configService: ConfigService, transformerService: TransformerService, logger: any);
+    /** Preserve the object decorated into every Fastify namespace. */
+    reload(): void;
     private initializeCustomProviders;
     private initializeFromProvidersArray;
     registerProvider(request: RegisterProviderRequest): LLMProvider;

package/dist/services/proxy.d.ts

@@ -1,10 +1,16 @@
-import { ProxyAgent } from "undici";
+import { Agent, ProxyAgent } from "undici";
 import type { ConfigService } from "./config";
 export interface ProxyAwareProvider {
     proxyEnabled?: boolean;
     proxy_enabled?: boolean;
 }
 export declare const PROXY_URL_KEYS: readonly ["HTTPS_PROXY", "https_proxy", "httpsProxy", "PROXY_URL"];
+/** Explicit opt-in proxy for the subscription plugins' fixed origins (codex,
+ *  gemini-oauth). Unlike PROXY_URL this is never applied implicitly and never
+ *  read from the environment: unset keeps those plugins fully direct (the
+ *  supported no-config deployment is an OS-level transparent proxy, e.g. TUN
+ *  mode). Same http(s)-only contract as PROXY_URL. */
+export declare const SUBSCRIPTION_PROXY_URL_KEY = "SUBSCRIPTION_PROXY_URL";
 export type ProxyUrlValidation = {
     ok: true;
 } | {
@@ -34,6 +40,18 @@ export declare function findInvalidProxyUrls(config: Record<string, unknown>): A
     key: string;
     error: string;
 }>;
+/** A process-wide direct dispatcher, used by fixed-origin providers that must ignore configured proxies. */
+export declare function getDirectDispatcher(): Agent;
+/** Resolve the explicit subscription-proxy opt-in from live config. Only a
+ *  string value counts: non-string config values (hand-edited booleans,
+ *  numbers) mean "unset" — they must never become garbage proxy URLs. */
+export declare function getSubscriptionProxyUrl(configService: Pick<ConfigService, "get">): string | undefined;
+/** Dispatcher for the subscription plugins' fixed-origin calls: the shared
+ *  direct agent when SUBSCRIPTION_PROXY_URL is unset, else the cached
+ *  ProxyAgent for it. Unsupported protocols throw (same contract as
+ *  getProxyDispatcher) so a typo fails loudly instead of silently sending
+ *  subscription traffic directly. */
+export declare function getSubscriptionDispatcher(proxyUrl: string | undefined): Agent | ProxyAgent;
 /**
  * Resolve the configured proxy URL using the compatibility key priority.
  */

package/dist/services/transformer.d.ts

@@ -5,6 +5,8 @@ export declare class TransformerService {
     private readonly logger;
     private transformers;
     constructor(configService: ConfigService, logger: any);
+    /** Construct without mutation so plugin activation can validate every service first. */
+    preparePluginTransformer(cls: new () => any): Transformer | TransformerConstructor;
     registerTransformer(name: string, transformer: Transformer): void;
     getTransformer(name: string): Transformer | TransformerConstructor | undefined;
     getAllTransformers(): Map<string, Transformer | TransformerConstructor>;

package/dist/transformer/openai.responses.transformer.d.ts

@@ -10,12 +10,6 @@ export declare class OpenAIResponsesTransformer implements Transformer {
     transformResponseOut(response: Response): Promise<Response>;
     private normalizeRequestContent;
     transformResponseIn(response: Response, context?: any): Promise<Response>;
-    /**
-     * Prepend a string chunk to the beginning of an existing ReadableStream.
-     * Used when we've peeked at the first chunk and need to feed it back into
-     * the converter along with the rest of the stream.
-     */
-    private prependToStream;
     /**
      * Convert an OpenAI Chat SSE stream to Responses API SSE events.
      * Handles choices[0].delta.content, choices[0].delta.tool_calls, and finish_reason.

package/dist/types/llm.d.ts

@@ -199,6 +199,10 @@ export interface LLMProvider {
     wakeupEnabled?: boolean;
     wakeupTime?: string;
     wakeupModel?: string;
+    /** Set for CCR-managed subscription providers (config `ccr_managed`) so
+     *  provider plugins can recognize their managed entries as one of their
+     *  managed-provider signals (fixed upstream lock, own auth headers). */
+    pluginManaged?: boolean;
 }
 export type RegisterProviderRequest = LLMProvider;
 export interface ModelRoute {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wengine-ai/llms",
-  "version": "2.3.2414",
+  "version": "2.3.2415",
   "description": "A universal LLM API transformation server",
   "main": "dist/cjs/server.cjs",
   "module": "dist/esm/server.mjs",
@@ -64,7 +64,7 @@
     "uuid": "^11.1.0",
     "@fastify/multipart": "^9.0.0",
     "@fastify/static": "^8.2.0",
-    "@wengine-ai/claude-code-router-shared": "^2.3.2414",
+    "@wengine-ai/claude-code-router-shared": "^2.3.2415",
     "adm-zip": "^0.5.16",
     "better-sqlite3": "^12.10.0",
     "rotating-file-stream": "^3.2.7"

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/server.ts","./src/api/middleware.ts","./src/api/routes.ts","./src/plugins/index.ts","./src/plugins/plugin-manager.ts","./src/plugins/token-speed.ts","./src/plugins/types.ts","./src/plugins/output/console-handler.ts","./src/plugins/output/index.ts","./src/plugins/output/output-manager.ts","./src/plugins/output/temp-file-handler.ts","./src/plugins/output/types.ts","./src/plugins/output/webhook-handler.ts","./src/services/active-probe.ts","./src/services/config.ts","./src/services/provider-health.ts","./src/services/provider.ts","./src/services/quota-adapters.ts","./src/services/quota-store.ts","./src/services/rate-limit.ts","./src/services/tokenizer.ts","./src/services/transformer.ts","./src/tokenizer/api-tokenizer.ts","./src/tokenizer/huggingface-tokenizer.ts","./src/tokenizer/tiktoken-tokenizer.ts","./src/transformer/anthropic.transformer.ts","./src/transformer/cerebras.transformer.ts","./src/transformer/cleancache.transformer.ts","./src/transformer/customparams.transformer.ts","./src/transformer/deepseek.transformer.ts","./src/transformer/enhancetool.transformer.ts","./src/transformer/forcereasoning.transformer.ts","./src/transformer/gemini.transformer.ts","./src/transformer/groq.transformer.ts","./src/transformer/index.ts","./src/transformer/kimi.transformer.ts","./src/transformer/maxcompletiontokens.transformer.ts","./src/transformer/maxtoken.transformer.ts","./src/transformer/openai.responses.transformer.ts","./src/transformer/openai.transformer.ts","./src/transformer/openrouter.transformer.ts","./src/transformer/reasoning.transformer.ts","./src/transformer/sampling.transformer.ts","./src/transformer/streamoptions.transformer.ts","./src/transformer/tooluse.transformer.ts","./src/transformer/vercel.transformer.ts","./src/transformer/vertex-claude.transformer.ts","./src/transformer/vertex-gemini.transformer.ts","./src/types/llm.ts","./src/types/tokenizer.d.ts","./src/types/transformer.ts","./src/utils/cache.ts","./src/utils/converter.ts","./src/utils/gemini.util.ts","./src/utils/image.ts","./src/utils/request.ts","./src/utils/router.ts","./src/utils/thinking.ts","./src/utils/toolargumentsparser.ts","./src/utils/vertex-claude.util.ts","./src/utils/sse/sseparser.transform.ts","./src/utils/sse/sseserializer.transform.ts","./src/utils/sse/index.ts","./src/utils/sse/rewritestream.ts"],"errors":true,"version":"5.9.3"}