@wengine-ai/llms 2.3.2415 → 2.3.2416

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

@@ -56,6 +56,30 @@ export interface PluginDispatchInput {
      *  spreads) for per-request wrapper state. */
     req?: any;
 }
+/**
+ * Outcome of a level-1 account-state check.
+ *
+ * `available: false` parks the provider without a network call; `parkedUntil`
+ * lets the plugin tell the core when the account frees up (e.g. a quota reset
+ * epoch), so the probe does not re-check before then.
+ */
+export interface ManagedProbeVerdict {
+    available: boolean;
+    /** Epoch ms after which the account may be usable again. */
+    parkedUntil?: number;
+    /** Stable reason used for logging only — never shown to a client. */
+    reason?: string;
+}
+/** Input for a runtime-owned liveness probe. */
+export interface ManagedProbeInput {
+    /** One ordinary core dispatch attempt (same seam as `PluginDispatchInput.attempt`). */
+    attempt(): Promise<Response>;
+    /** Model to probe with (the first circuit-open model of the provider). */
+    model: string;
+    provider: LLMProvider;
+    /** Per-attempt config; the core sets `TIMEOUT` so a probe cannot outlive its budget. */
+    config: any;
+}
 /**
  * Managed-subscription semantics for one provider family. Everything the data
  * plane needs to talk to a subscription upstream without the core knowing it:
@@ -109,6 +133,36 @@ export interface ManagedRuntime {
      * hard attempt bound and must never swallow client aborts.
      */
     dispatchRequest?(input: PluginDispatchInput): Promise<Response>;
+    /**
+     * Cheap account-state check used by the background recovery probe.
+     *
+     * Two-level probing exists because account state and reachability fail
+     * independently: a parked/over-quota account must NOT spend a network call
+     * (the Gemini lesson), while a healthy-but-unreachable account must not be
+     * restored to the model list on the strength of its state alone. The core
+     * calls this FIRST and only issues the (expensive) real request when it
+     * resolves.
+     *
+     * Resolve to use the `available` hint semantics below; throw a classified
+     * error (e.g. `*_account_cooling`) to report the account as unusable. When
+     * absent, the core falls back to `ensureUsable()` — which is the same check
+     * every real request already performs — so plugins that only implement the
+     * circuit breaker still work.
+     */
+    probeAccountState?(): Promise<ManagedProbeVerdict>;
+    /**
+     * Optional runtime-owned liveness probe (level 2).
+     *
+     * Called only after `probeAccountState`/`ensureUsable` reported the account as
+     * usable. Implementations should make the cheapest request that still proves
+     * the upstream answers for THIS account (a quota/status endpoint is ideal,
+     * otherwise a 1-token chat). Must honour the supplied signal/timeout and must
+     * not persist cooldowns that a probe is not allowed to set.
+     *
+     * When absent the core performs a generic 1-token request through
+     * `dispatchRequest` (see `PluginDispatchInput`).
+     */
+    probeLiveness?(input: ManagedProbeInput): 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

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

@@ -57,9 +57,13 @@ export declare class ActiveProbeService {
     private resolveProxyUrl?;
     private logger?;
     private getConfig?;
+    /** Resolves the installed plugin runtime that owns a managed provider. */
+    private resolveManagedRuntime?;
+    /** Periodic timer for managed-subscription recovery probing. */
+    private managedProbeTimer?;
     private running;
     private probeTelemetry;
-    constructor(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any);
+    constructor(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any, resolveManagedRuntime?: (provider: LLMProvider) => any);
     /**
      * Record the latest reachability probe result for a provider.
      * Only /models-style reachability probes (health, manual, rate-limit header
@@ -102,6 +106,43 @@ export declare class ActiveProbeService {
      * Rate-limited models are NOT probed by runHealthProbe — they have a separate timer
      * so they can be checked more frequently (every 2 minutes) without affecting normal probes.
      */
+    /**
+     * Recover circuit-open MANAGED (subscription) providers with one real request.
+     *
+     * runHealthProbe deliberately skips managed providers: their credentials are
+     * plugin-owned, so an unauthenticated GET /v1/models would fail for reasons
+     * unrelated to health. The consequence was that a subscription provider whose
+     * circuit opened (exhausted quota, revoked token, upstream outage) had NO
+     * background path back to healthy — it stayed circuit-open and the only way it
+     * ever recovered was a real user request hitting it again, which is exactly the
+     * "keeps failing and keeps being called" behaviour.
+     *
+     * This closes that loop: for each managed provider with a circuit-open model
+     * whose probe interval has elapsed, issue one minimal request through the
+     * plugin's own dispatcher (so token refresh, account rotation and the plugin's
+     * error taxonomy all apply) and restore its models only when the upstream
+     * actually answered.
+     */
+    runManagedRecoveryProbe(): Promise<void>;
+    /**
+     * Level 1 of the managed recovery probe: is the ACCOUNT usable at all?
+     *
+     * Returns false when the account is parked (quota exhausted / verification
+     * needed / risk-blocked), in which case the caller must skip the liveness call
+     * entirely — testing the network for an account that cannot answer is pure
+     * waste and, for subscription providers, a rate-limit risk.
+     */
+    private probeManagedAccountState;
+    /**
+     * Level 2 of the managed recovery probe: does the upstream actually answer?
+     *
+     * Uses a runtime-owned `probeLiveness` when the plugin provides one (a quota or
+     * status endpoint costs no chat quota), otherwise performs a generic 1-token
+     * request through the runtime's dispatcher. The dispatcher input carries a real
+     * `attempt()` and a per-attempt `config` — both are REQUIRED by
+     * `PluginDispatchInput`, and omitting them made wrappers fail unconditionally.
+     */
+    private probeManagedLiveness;
     private runRateLimitProbe;
     /**
      * Run scheduled wake-up for configured providers
@@ -122,11 +163,11 @@ export declare class ActiveProbeService {
 /**
  * Initialize and get the active probe service
  */
-export declare function getActiveProbeService(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any): ActiveProbeService;
+export declare function getActiveProbeService(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any, resolveManagedRuntime?: (provider: LLMProvider) => any): ActiveProbeService;
 /**
  * Start the active probe service (convenience function)
  */
-export declare function startActiveProbe(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any): ActiveProbeService;
+export declare function startActiveProbe(getProviders: () => LLMProvider[], config?: ActiveProbeConfig, resolveProxyUrl?: (provider: LLMProvider) => string | undefined, logger?: any, getConfig?: (key: string) => any, resolveManagedRuntime?: (provider: LLMProvider) => any): ActiveProbeService;
 /**
  * Stop the active probe service
  */

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

@@ -76,6 +76,23 @@ export declare class ProviderHealthStore {
      * Get all models in fail pool (open status)
      */
     getFailPoolModels(): string[];
+    /**
+     * Stamp a background probe attempt without changing circuit state.
+     *
+     * Recovery probes need this: a failed probe must keep the model circuit-open
+     * but move `lastProbeTime` forward, otherwise the interval gate in
+     * isAvailable()/the probe loop would re-probe on every tick.
+     */
+    recordProbeAttempt(provider: string, model: string): void;
+    /**
+     * Park a model until the account's own reset epoch.
+     *
+     * A plugin that reports its quota window (e.g. `resets_at`) knows better than
+     * a fixed probe interval when the account can answer again. Setting
+     * `rateLimitUntil` keeps the model hidden from the list AND stops the recovery
+     * probe from spending network calls on a known-parked account.
+     */
+    markParkedUntil(provider: string, model: string, until: number): void;
     /**
      * Get all models in half-open state
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wengine-ai/llms",
-  "version": "2.3.2415",
+  "version": "2.3.2416",
   "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.2415",
+    "@wengine-ai/claude-code-router-shared": "^2.3.2416",
     "adm-zip": "^0.5.16",
     "better-sqlite3": "^12.10.0",
     "rotating-file-stream": "^3.2.7"