@poolzin/pool-bot 2026.2.20 → 2026.2.22

package/dist/agents/provider/integration.js

@@ -0,0 +1,136 @@
+/**
+ * Provider Infrastructure — Integration Facade
+ *
+ * Thin integration layer that bridges the provider infrastructure modules
+ * (TokenPool, RateLimits, RequestMonitor) into the existing LLM pipeline
+ * (model-auth.ts, model-fallback.ts, attempt.ts).
+ *
+ * Design principles:
+ * - **Opt-in**: Only activates when TokenPool has tokens for a provider
+ * - **Fallthrough**: Returns null/undefined when not configured, letting existing paths run
+ * - **Error-isolated**: Never throws — all failures are caught and logged
+ * - **Zero behavior change by default**: Without pool configuration, the system is identical
+ *
+ * @module provider/integration
+ */
+import { RateLimits } from "./rate-limits.js";
+import { RequestMonitor } from "./request-monitor.js";
+import { TokenPool } from "./token-pool.js";
+/**
+ * Try to resolve an API key from the token pool for a provider.
+ * Returns `null` if no pool is configured or no tokens are available,
+ * allowing the caller to fall back to the existing auth resolution path.
+ */
+export async function resolveTokenFromPool(provider) {
+    try {
+        if (!TokenPool.hasPool(provider))
+            return null;
+        const result = await TokenPool.getToken(provider);
+        if (!result)
+            return null;
+        return {
+            apiKey: result.token.key,
+            tokenID: result.token.id,
+            source: `pool:${provider}/${result.token.id}`,
+            waited: result.waited,
+        };
+    }
+    catch {
+        // Never break the auth chain — fall back to existing resolution
+        return null;
+    }
+}
+/**
+ * Check whether a provider is rate-limited across all its pool keys.
+ * Returns `{ isLimited: false }` if no pool is configured (safe default).
+ *
+ * When `keyID` is provided, checks that specific key only.
+ */
+export function isProviderRateLimited(provider, keyID) {
+    try {
+        const check = RateLimits.isLimited(provider, keyID);
+        return {
+            isLimited: check.isLimited,
+            waitTimeMs: check.waitTimeMs,
+        };
+    }
+    catch {
+        return { isLimited: false, waitTimeMs: 0 };
+    }
+}
+/**
+ * Record the outcome of a provider request into both RateLimits and RequestMonitor.
+ *
+ * - For 429 responses: marks the provider/key as rate-limited (with header parsing)
+ * - For successes: records success in TokenPool (for scheduling) and clears rate limits
+ * - All outcomes: logged in RequestMonitor for observability
+ *
+ * Safe to call unconditionally — does nothing harmful if provider modules aren't configured.
+ */
+export function recordRequestOutcome(outcome) {
+    try {
+        // Feed into RequestMonitor for observability
+        RequestMonitor.logRequest({
+            providerID: outcome.provider,
+            modelID: outcome.model,
+            method: "chat",
+            status: outcome.status,
+            latencyMs: outcome.latencyMs,
+            streaming: outcome.streaming,
+            keyID: outcome.keyID,
+            inputTokens: outcome.inputTokens,
+            outputTokens: outcome.outputTokens,
+            cacheReadTokens: outcome.cacheReadTokens,
+            cacheWriteTokens: outcome.cacheWriteTokens,
+            error: outcome.error,
+        });
+    }
+    catch {
+        // Observability should never break the pipeline
+    }
+    try {
+        // Feed into RateLimits for 429s
+        if (outcome.status === 429) {
+            RateLimits.markLimitedFromResponse(outcome.provider, outcome.status, outcome.headers ?? {}, outcome.keyID);
+        }
+    }
+    catch {
+        // Rate limit tracking should never break the pipeline
+    }
+    try {
+        // Feed success/failure into TokenPool for scheduling decisions
+        if (outcome.keyID && TokenPool.hasPool(outcome.provider)) {
+            if (outcome.status >= 200 && outcome.status < 400) {
+                TokenPool.recordSuccess(outcome.provider, outcome.keyID, {
+                    inputTokens: outcome.inputTokens ?? 0,
+                    outputTokens: outcome.outputTokens ?? 0,
+                });
+            }
+            else if (outcome.status >= 400) {
+                TokenPool.recordFailure(outcome.provider, outcome.keyID, outcome.status, outcome.headers);
+            }
+        }
+    }
+    catch {
+        // Token pool feedback should never break the pipeline
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience: record a fallback error
+// ---------------------------------------------------------------------------
+/**
+ * Record a fallback error (e.g., from model-fallback catch block).
+ * Extracts provider, model, status from the error and feeds into the monitoring pipeline.
+ */
+export function recordFallbackError(params) {
+    recordRequestOutcome({
+        provider: params.provider,
+        model: params.model,
+        status: params.status ?? 500,
+        latencyMs: params.latencyMs ?? 0,
+        streaming: false,
+        keyID: params.keyID,
+        error: params.error ?? params.reason,
+        headers: params.headers,
+    });
+}

package/dist/agents/provider/models-dev.js

@@ -0,0 +1,129 @@
+/**
+ * Models.dev Catalog
+ *
+ * Fetches and caches the model catalog from https://models.dev/api.json.
+ * Provides typed schemas for providers and models via Zod.
+ *
+ * @module provider/models-dev
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import z from "zod";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { resolveStateDir } from "../../config/paths.js";
+export var ModelsDev;
+(function (ModelsDev) {
+    const log = createSubsystemLogger("provider/models-dev");
+    /** Cache directory: ~/.poolbot/cache/ */
+    const cacheDir = path.join(resolveStateDir(), "cache");
+    const filepath = path.join(cacheDir, "models.json");
+    /** User-Agent for fetching */
+    const USER_AGENT = "pool-bot";
+    ModelsDev.Model = z.object({
+        id: z.string(),
+        name: z.string(),
+        family: z.string().optional(),
+        release_date: z.string(),
+        attachment: z.boolean(),
+        reasoning: z.boolean(),
+        temperature: z.boolean(),
+        tool_call: z.boolean(),
+        interleaved: z
+            .union([
+            z.literal(true),
+            z
+                .object({
+                field: z.enum(["reasoning_content", "reasoning_details"]),
+            })
+                .strict(),
+        ])
+            .optional(),
+        cost: z
+            .object({
+            input: z.number(),
+            output: z.number(),
+            cache_read: z.number().optional(),
+            cache_write: z.number().optional(),
+            context_over_200k: z
+                .object({
+                input: z.number(),
+                output: z.number(),
+                cache_read: z.number().optional(),
+                cache_write: z.number().optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+        limit: z.object({
+            context: z.number(),
+            output: z.number(),
+        }),
+        modalities: z
+            .object({
+            input: z.array(z.enum(["text", "audio", "image", "video", "pdf"])),
+            output: z.array(z.enum(["text", "audio", "image", "video", "pdf"])),
+        })
+            .optional(),
+        experimental: z.boolean().optional(),
+        status: z.enum(["alpha", "beta", "deprecated"]).optional(),
+        options: z.record(z.string(), z.any()),
+        headers: z.record(z.string(), z.string()).optional(),
+        provider: z.object({ npm: z.string() }).optional(),
+    });
+    ModelsDev.Provider = z.object({
+        api: z.string().optional(),
+        name: z.string(),
+        env: z.array(z.string()),
+        id: z.string(),
+        npm: z.string().optional(),
+        models: z.record(z.string(), ModelsDev.Model),
+    });
+    /**
+     * Gets the cached model catalog, triggering a background refresh.
+     * Returns empty object if no cached data is available.
+     */
+    async function get() {
+        // Fire-and-forget background refresh
+        refresh().catch((e) => log.error("background refresh failed", { error: String(e) }));
+        // Try reading from cache
+        try {
+            const content = await readFile(filepath, "utf-8");
+            const result = JSON.parse(content);
+            return result;
+        }
+        catch {
+            // No cached file yet — return empty catalog
+            return {};
+        }
+    }
+    ModelsDev.get = get;
+    /**
+     * Fetches the latest model catalog from models.dev and caches it.
+     */
+    async function refresh() {
+        if (process.env.POOLBOT_DISABLE_MODELS_FETCH)
+            return;
+        log.info("refreshing", { filepath });
+        const result = await fetch("https://models.dev/api.json", {
+            headers: {
+                "User-Agent": USER_AGENT,
+            },
+            signal: AbortSignal.timeout(10 * 1000),
+        }).catch((e) => {
+            log.error("failed to fetch models.dev", { error: String(e) });
+        });
+        if (!result || !result.ok)
+            return;
+        try {
+            const text = await result.text();
+            await mkdir(cacheDir, { recursive: true });
+            await writeFile(filepath, text, "utf-8");
+        }
+        catch (e) {
+            log.error("failed to write models.json", { error: String(e) });
+        }
+    }
+    ModelsDev.refresh = refresh;
+})(ModelsDev || (ModelsDev = {}));
+// Background refresh every hour
+setInterval(() => ModelsDev.refresh().catch(() => { }), 60 * 60 * 1000).unref();