@poolzin/pool-bot 2026.2.20 → 2026.2.21

package/CHANGELOG.md

@@ -1,9 +1,17 @@
+## v2026.2.21 (2026-02-18)
+
+### Features
+- **PLCODE Controller Skill:** native bundled skill for controlling PLCODE via CLI commands, slash commands, and multi-agent orchestration — includes session management, model selection, agent delegation (plan/code/review), operator prompts, failure handling, and workflow references
+
+---
+
 ## v2026.2.20 (2026-02-18)
 
 ### Features
 - **Z.AI Provider:** added ZhipuAI (GLM) as first-class provider with 5 models — GLM-4.7-Flash (free), GLM-4.5-Flash (free), GLM-4.6V-Flash (free vision), GLM-4.7, GLM-5
 - **Image Generation Tool:** `image_generate` tool powered by Z.AI CogView-4, CogView-4-Flash, and GLM-Image — generates images from text prompts, downloads to disk, returns media path
 - **Deep Research Tool:** `deep_research` tool powered by Z.AI GLM-4.7-Flash + web_search — configurable depth (shallow/standard/deep), language, and max sources; returns structured report with sources and metadata; cost ~$0.01–$0.05 per query
+- **Provider Infrastructure:** multi-key token pool with 4 scheduling strategies (round-robin, least-used, priority, random), proactive rate limit tracking with header parsing, request monitoring with ring-buffer observability and percentile stats, sticky session binding, and models.dev catalog — integrated into the LLM pipeline as an opt-in layer that coexists with existing auth/cooldown paths
 
 ---
 

package/dist/agents/model-auth.js

@@ -4,6 +4,7 @@ import { getShellEnvAppliedKeys } from "../infra/shell-env.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import { ensureAuthProfileStore, listProfilesForProvider, resolveApiKeyForProfile, resolveAuthProfileOrder, resolveAuthStorePathForDisplay, } from "./auth-profiles.js";
 import { normalizeProviderId } from "./model-selection.js";
+import { resolveTokenFromPool } from "./provider/integration.js";
 export { ensureAuthProfileStore, resolveAuthProfileOrder } from "./auth-profiles.js";
 const AWS_BEARER_ENV = "AWS_BEARER_TOKEN_BEDROCK";
 const AWS_ACCESS_KEY_ENV = "AWS_ACCESS_KEY_ID";
@@ -135,6 +136,17 @@ export async function resolveApiKeyForProvider(params) {
         }
         catch { }
     }
+    // Token pool rotation: if a pool is configured for this provider,
+    // try to get a key from the pool (with rate-limit-aware scheduling).
+    // Falls through to existing env/config resolution if no pool or no tokens.
+    const poolResult = await resolveTokenFromPool(provider);
+    if (poolResult) {
+        return {
+            apiKey: poolResult.apiKey,
+            source: poolResult.source,
+            mode: "api-key",
+        };
+    }
     const envResolved = resolveEnvApiKey(provider);
     if (envResolved) {
         return {

package/dist/agents/model-fallback.js

@@ -2,6 +2,7 @@ import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js";
 import { coerceToFailoverError, describeFailoverError, isFailoverError, isTimeoutError, } from "./failover-error.js";
 import { buildModelAliasIndex, modelKey, parseModelRef, resolveConfiguredModelRef, resolveModelRefFromString, } from "./model-selection.js";
 import { ensureAuthProfileStore, getSoonestCooldownExpiry, isProfileInCooldown, resolveAuthProfileOrder, } from "./auth-profiles.js";
+import { isProviderRateLimited, recordFallbackError } from "./provider/integration.js";
 function isAbortError(err) {
     if (!err || typeof err !== "object")
         return false;
@@ -218,6 +219,21 @@ export async function runWithModelFallback(params) {
                 lastProbeAttempt.set(probeThrottleKey, now);
             }
         }
+        // Provider-level rate limit check (from token pool / rate limit tracking).
+        // Complements the per-profile cooldown above — skips candidates when all
+        // API keys in the pool are known to be rate-limited.
+        const poolLimit = isProviderRateLimited(candidate.provider);
+        if (poolLimit.isLimited && hasFallbackCandidates && i > 0) {
+            // Skip non-primary candidates that are pool-rate-limited.
+            // Primary (i === 0) is never skipped here — it gets a chance to probe.
+            attempts.push({
+                provider: candidate.provider,
+                model: candidate.model,
+                error: `Provider ${candidate.provider} pool is rate-limited (wait ${poolLimit.waitTimeMs}ms)`,
+                reason: "rate_limit",
+            });
+            continue;
+        }
         try {
             const result = await params.run(candidate.provider, candidate.model);
             return {
@@ -246,6 +262,14 @@ export async function runWithModelFallback(params) {
                 status: described.status,
                 code: described.code,
             });
+            // Feed error into provider infrastructure (rate limits + monitoring)
+            recordFallbackError({
+                provider: candidate.provider,
+                model: candidate.model,
+                status: described.status,
+                reason: described.reason,
+                error: described.message,
+            });
             await params.onError?.({
                 provider: candidate.provider,
                 model: candidate.model,

package/dist/agents/pi-embedded-runner/run/attempt.js

@@ -20,6 +20,7 @@ import { resolveSessionAgentIds } from "../../agent-scope.js";
 import { makeBootstrapWarn, resolveBootstrapContextForRun } from "../../bootstrap-files.js";
 import { resolvePoolbotDocsPath } from "../../docs-path.js";
 import { resolveModelAuthMode } from "../../model-auth.js";
+import { recordRequestOutcome } from "../../provider/integration.js";
 import { isCloudCodeAssistFormatError, resolveBootstrapMaxChars, validateAnthropicTurns, validateGeminiTurns, } from "../../pi-embedded-helpers.js";
 import { subscribeEmbeddedPiSession } from "../../pi-embedded-subscribe.js";
 import { ensurePiCompactionReserveTokens, resolveCompactionReserveTokensFloor, } from "../../pi-settings.js";
@@ -694,6 +695,20 @@ export async function runEmbeddedAttempt(params) {
                     note: promptError ? "prompt error" : undefined,
                 });
                 anthropicPayloadLogger?.recordUsage(messagesSnapshot, promptError);
+                // Record request outcome into provider infrastructure (monitoring + rate limits).
+                // Fire-and-forget — never blocks or throws.
+                try {
+                    recordRequestOutcome({
+                        provider: params.provider,
+                        model: params.modelId,
+                        status: promptError ? 500 : 200,
+                        latencyMs: Date.now() - promptStartedAt,
+                        streaming: true,
+                    });
+                }
+                catch {
+                    // Observability must never break the run
+                }
                 // Run agent_end hooks to allow plugins to analyze the conversation
                 // This is fire-and-forget, so we don't await
                 if (hookRunner?.hasHooks("agent_end")) {

package/dist/agents/provider/config-loader.js

@@ -0,0 +1,76 @@
+/**
+ * Provider Pool — Config Loader
+ *
+ * Reads pool configuration from `models.providers.<id>.pool` in the
+ * PoolBot config and initializes the TokenPool with the configured tokens.
+ *
+ * Called once during gateway/agent startup. Idempotent — clears
+ * existing pool state before loading.
+ *
+ * @module provider/config-loader
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { TokenPool } from "./token-pool.js";
+const log = createSubsystemLogger("provider/config-loader");
+/**
+ * Load token pool configuration from the PoolBot config.
+ *
+ * Reads `models.providers.<providerID>.pool` entries and calls
+ * `TokenPool.addToken()` for each configured token.
+ *
+ * @returns Number of providers with pool configuration loaded
+ */
+export function loadPoolConfig(cfg) {
+    const providers = cfg.models?.providers;
+    if (!providers)
+        return 0;
+    let loadedProviders = 0;
+    for (const [providerID, providerCfg] of Object.entries(providers)) {
+        const pool = providerCfg.pool;
+        if (!pool?.tokens?.length)
+            continue;
+        // Configure pool scheduling before adding tokens
+        if (pool.scheduling || pool.maxWaitMs || pool.autoDisable !== undefined) {
+            TokenPool.configure(providerID, {
+                scheduling: pool.scheduling,
+                maxWaitMs: pool.maxWaitMs,
+                autoDisable: pool.autoDisable,
+                autoDisableThreshold: pool.autoDisableThreshold,
+            });
+        }
+        let tokenCount = 0;
+        for (const tokenCfg of pool.tokens) {
+            if (!tokenCfg.id || !tokenCfg.key) {
+                log.info("skipped-invalid-token", { providerID, tokenID: tokenCfg.id ?? "(missing)" });
+                continue;
+            }
+            try {
+                TokenPool.addToken(providerID, tokenCfg.id, tokenCfg.key, {
+                    tier: tokenCfg.tier ?? "paid",
+                    label: tokenCfg.label,
+                    enabled: tokenCfg.enabled ?? true,
+                });
+                tokenCount++;
+            }
+            catch (e) {
+                log.info("token-add-failed", {
+                    providerID,
+                    tokenID: tokenCfg.id,
+                    error: String(e),
+                });
+            }
+        }
+        if (tokenCount > 0) {
+            loadedProviders++;
+            log.info("pool-loaded", {
+                providerID,
+                tokens: tokenCount,
+                scheduling: pool.scheduling ?? "priority",
+            });
+        }
+    }
+    if (loadedProviders > 0) {
+        log.info("config-loaded", { providers: loadedProviders });
+    }
+    return loadedProviders;
+}

package/dist/agents/provider/index.js

@@ -0,0 +1,15 @@
+/**
+ * Provider Infrastructure
+ *
+ * Operational modules for token rotation, rate limiting,
+ * request monitoring, session management, and model catalog.
+ *
+ * @module provider
+ */
+export { RateLimits } from "./rate-limits.js";
+export { RequestMonitor } from "./request-monitor.js";
+export { SessionManager } from "./session-binding.js";
+export { TokenPool } from "./token-pool.js";
+export { ModelsDev } from "./models-dev.js";
+export { resolveTokenFromPool, isProviderRateLimited, recordRequestOutcome, recordFallbackError, } from "./integration.js";
+export { loadPoolConfig } from "./config-loader.js";

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();