@blockrun/clawrouter 0.12.94 → 0.12.96

package/dist/payment-preauth.js

@@ -0,0 +1,102 @@
+/**
+ * Payment Pre-Auth Cache
+ *
+ * Wraps the @x402/fetch SDK with pre-authorization caching.
+ * After the first 402 response, caches payment requirements per endpoint.
+ * On subsequent requests, pre-signs payment and attaches it to the first
+ * request, skipping the 402 round trip (~200ms savings per request).
+ *
+ * Falls back to normal 402 flow if pre-signed payment is rejected.
+ */
+import { x402HTTPClient } from "@x402/fetch";
+const DEFAULT_TTL_MS = 3_600_000; // 1 hour
+export function createPayFetchWithPreAuth(baseFetch, client, ttlMs = DEFAULT_TTL_MS, options) {
+    const httpClient = new x402HTTPClient(client);
+    const cache = new Map();
+    return async (input, init) => {
+        const request = new Request(input, init);
+        const urlPath = new URL(request.url).pathname;
+        // Extract model from request body to create model-specific cache keys.
+        // Without this, a cached payment from a paid model (e.g. sonnet) would be
+        // incorrectly applied to a free model (nvidia/gpt-oss-120b), causing
+        // payment errors even when the server wouldn't charge for the request.
+        let requestModel = "";
+        if (init?.body) {
+            try {
+                const bodyStr = init.body instanceof Uint8Array
+                    ? new TextDecoder().decode(init.body)
+                    : typeof init.body === "string"
+                        ? init.body
+                        : "";
+                if (bodyStr) {
+                    const parsed = JSON.parse(bodyStr);
+                    requestModel = parsed.model ?? "";
+                }
+            }
+            catch {
+                /* not JSON, use empty model */
+            }
+        }
+        const cacheKey = `${urlPath}:${requestModel}`;
+        // Try pre-auth if we have cached payment requirements
+        // Skip for Solana: payments use per-tx blockhashes that expire ~60-90s,
+        // making cached requirements useless and causing double charges.
+        const cached = !options?.skipPreAuth ? cache.get(cacheKey) : undefined;
+        if (cached && Date.now() - cached.cachedAt < ttlMs) {
+            try {
+                const payload = await client.createPaymentPayload(cached.paymentRequired);
+                const headers = httpClient.encodePaymentSignatureHeader(payload);
+                const preAuthRequest = request.clone();
+                for (const [key, value] of Object.entries(headers)) {
+                    preAuthRequest.headers.set(key, value);
+                }
+                const response = await baseFetch(preAuthRequest);
+                if (response.status !== 402) {
+                    return response; // Pre-auth worked — saved ~200ms
+                }
+                // Pre-auth rejected (params may have changed) — invalidate and fall through
+                cache.delete(cacheKey);
+            }
+            catch {
+                // Pre-auth signing failed — invalidate and fall through
+                cache.delete(cacheKey);
+            }
+        }
+        // Normal flow: make request, handle 402 if needed
+        const clonedRequest = request.clone();
+        const response = await baseFetch(request);
+        if (response.status !== 402) {
+            return response;
+        }
+        // Parse 402 response and cache for future pre-auth
+        let paymentRequired;
+        try {
+            const getHeader = (name) => response.headers.get(name);
+            let body;
+            try {
+                const responseText = await Promise.race([
+                    response.text(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Body read timeout")), 30_000)),
+                ]);
+                if (responseText)
+                    body = JSON.parse(responseText);
+            }
+            catch {
+                /* empty body is fine */
+            }
+            paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, body);
+            cache.set(cacheKey, { paymentRequired, cachedAt: Date.now() });
+        }
+        catch (error) {
+            throw new Error(`Failed to parse payment requirements: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
+        }
+        // Sign payment and retry
+        const payload = await client.createPaymentPayload(paymentRequired);
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(payload);
+        for (const [key, value] of Object.entries(paymentHeaders)) {
+            clonedRequest.headers.set(key, value);
+        }
+        return baseFetch(clonedRequest);
+    };
+}
+//# sourceMappingURL=payment-preauth.js.map

package/dist/payment-preauth.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BlockRun ProviderPlugin for OpenClaw
+ *
+ * Registers BlockRun as an LLM provider in OpenClaw.
+ * Uses a local x402 proxy to handle micropayments transparently —
+ * pi-ai sees a standard OpenAI-compatible API at localhost.
+ */
+import type { ProviderPlugin } from "./types.js";
+import type { ProxyHandle } from "./proxy.js";
+/**
+ * Update the proxy handle (called from index.ts when the proxy starts).
+ */
+export declare function setActiveProxy(proxy: ProxyHandle): void;
+export declare function getActiveProxy(): ProxyHandle | null;
+/**
+ * BlockRun provider plugin definition.
+ */
+export declare const blockrunProvider: ProviderPlugin;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO9C;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAEvD;AAED,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAEnD;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAqB9B,CAAC"}

package/dist/provider.js

@@ -0,0 +1,45 @@
+/**
+ * BlockRun ProviderPlugin for OpenClaw
+ *
+ * Registers BlockRun as an LLM provider in OpenClaw.
+ * Uses a local x402 proxy to handle micropayments transparently —
+ * pi-ai sees a standard OpenAI-compatible API at localhost.
+ */
+import { buildProviderModels } from "./models.js";
+/**
+ * State for the running proxy (set when the plugin activates).
+ */
+let activeProxy = null;
+/**
+ * Update the proxy handle (called from index.ts when the proxy starts).
+ */
+export function setActiveProxy(proxy) {
+    activeProxy = proxy;
+}
+export function getActiveProxy() {
+    return activeProxy;
+}
+/**
+ * BlockRun provider plugin definition.
+ */
+export const blockrunProvider = {
+    id: "blockrun",
+    label: "BlockRun",
+    docsPath: "https://blockrun.ai/docs",
+    aliases: ["br"],
+    envVars: ["BLOCKRUN_WALLET_KEY"],
+    // Model definitions — dynamically set to proxy URL
+    get models() {
+        if (!activeProxy) {
+            // Fallback: point to BlockRun API directly (won't handle x402, but
+            // allows config loading before proxy starts)
+            return buildProviderModels("https://blockrun.ai/api");
+        }
+        return buildProviderModels(activeProxy.baseUrl);
+    },
+    // No auth required — the x402 proxy handles wallet-based payments internally.
+    // The proxy auto-generates a wallet on first run and stores it at
+    // ~/.openclaw/blockrun/wallet.key. Users just fund that wallet with USDC.
+    auth: [],
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD;;GAEG;AACH,IAAI,WAAW,GAAuB,IAAI,CAAC;AAE3C;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,EAAE,EAAE,UAAU;IACd,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,0BAA0B;IACpC,OAAO,EAAE,CAAC,IAAI,CAAC;IACf,OAAO,EAAE,CAAC,qBAAqB,CAAC;IAEhC,mDAAmD;IACnD,IAAI,MAAM;QACR,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,mEAAmE;YACnE,6CAA6C;YAC7C,OAAO,mBAAmB,CAAC,yBAAyB,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,mBAAmB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;IAED,8EAA8E;IAC9E,kEAAkE;IAClE,0EAA0E;IAC1E,IAAI,EAAE,EAAE;CACT,CAAC"}

package/dist/proxy.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Local x402 Proxy Server
+ *
+ * Sits between OpenClaw's pi-ai (which makes standard OpenAI-format requests)
+ * and BlockRun's API (which requires x402 micropayments).
+ *
+ * Flow:
+ *   pi-ai → http://localhost:{port}/v1/chat/completions
+ *        → proxy forwards to https://blockrun.ai/api/v1/chat/completions
+ *        → gets 402 → @x402/fetch signs payment → retries
+ *        → streams response back to pi-ai
+ *
+ * Optimizations (v0.3.0):
+ *   - SSE heartbeat: for streaming requests, sends headers + heartbeat immediately
+ *     before the x402 flow, preventing OpenClaw's 10-15s timeout from firing.
+ *   - Response dedup: hashes request bodies and caches responses for 30s,
+ *     preventing double-charging when OpenClaw retries after timeout.
+ *   - Smart routing: when model is "blockrun/auto", classify query and pick cheapest model.
+ *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
+ */
+import { type RoutingDecision, type RoutingConfig } from "./router/index.js";
+import { type ResponseCacheConfig } from "./response-cache.js";
+import { BalanceMonitor } from "./balance.js";
+import type { SolanaBalanceMonitor } from "./solana-balance.js";
+/** Union type for chain-agnostic balance monitoring */
+type AnyBalanceMonitor = BalanceMonitor | SolanaBalanceMonitor;
+import { type SessionConfig } from "./session.js";
+/**
+ * Semantic error categories from upstream provider responses.
+ * Used to distinguish auth failures from rate limits from server errors
+ * so each category can be handled independently without cross-contamination.
+ */
+export type ErrorCategory = "auth_failure" | "quota_exceeded" | "rate_limited" | "overloaded" | "server_error" | "payment_error" | "config_error";
+/**
+ * Classify an upstream error response into a semantic category.
+ * Returns null if the status+body is not a provider-side issue worth retrying.
+ */
+export declare function categorizeError(status: number, body: string): ErrorCategory | null;
+/**
+ * Get the proxy port from pre-loaded configuration.
+ * Port is validated at module load time, this just returns the cached value.
+ */
+export declare function getProxyPort(): number;
+/**
+ * Detect degraded 200-response payloads that should trigger model fallback.
+ * Returns a short reason when fallback should happen, otherwise undefined.
+ */
+export declare function detectDegradedSuccessResponse(body: string): string | undefined;
+type ChatMessage = {
+    role: string;
+    content: string | unknown;
+};
+/**
+ * Extended message type for thinking-enabled conversations.
+ */
+type ExtendedChatMessage = ChatMessage & {
+    tool_calls?: unknown[];
+    reasoning_content?: unknown;
+};
+/**
+ * Normalize messages for thinking-enabled requests.
+ * When thinking/extended_thinking is enabled, ALL assistant messages in history
+ * must have reasoning_content (can be empty string if not present).
+ *
+ * Reasoning models like Kimi K2.5, DeepSeek-R1, etc. strip their thinking tokens
+ * before we forward the response to the client. So when the client sends back the
+ * assistant message in a follow-up turn, it lacks reasoning_content. These models
+ * reject the multi-turn history with 400 if any assistant message is missing it.
+ *
+ * Previously only tool-call messages were patched — this missed plain text assistant
+ * messages, causing 100% failures on existing (multi-turn) chats.
+ *
+ * Error examples:
+ *   "400 thinking is enabled but reasoning_content is missing in assistant tool call message"
+ *   "400 thinking is enabled but reasoning_content is missing in assistant message"
+ */
+export declare function normalizeMessagesForThinking(messages: ExtendedChatMessage[]): ExtendedChatMessage[];
+/**
+ * Remove "blockrun" branding from system messages before sending upstream.
+ *
+ * OpenClaw embeds `model=blockrun/auto` and `default_model=blockrun/auto` in its
+ * system prompt Runtime section. LLMs pick up "blockrun" and adopt it as their
+ * identity (e.g. "I'm Blockrun"), overriding the user's SOUL.md persona.
+ *
+ * This function replaces `blockrun/<profile>` references with the actual resolved
+ * model name, and strips any remaining "blockrun/" prefix so the upstream LLM
+ * never sees "blockrun" as an identity to adopt.
+ */
+export declare function debrandSystemMessages(messages: ChatMessage[], resolvedModel: string): ChatMessage[];
+/** Callback info for low balance warning */
+export type LowBalanceInfo = {
+    balanceUSD: string;
+    walletAddress: string;
+};
+/** Callback info for insufficient funds error */
+export type InsufficientFundsInfo = {
+    balanceUSD: string;
+    requiredUSD: string;
+    walletAddress: string;
+};
+/**
+ * Wallet config: either a plain EVM private key string, or the full
+ * resolution object from resolveOrGenerateWalletKey() which may include
+ * Solana keys. Using the full object prevents callers from accidentally
+ * forgetting to forward Solana key bytes.
+ */
+export type WalletConfig = string | {
+    key: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+export type PaymentChain = "base" | "solana";
+export type ProxyOptions = {
+    wallet: WalletConfig;
+    apiBase?: string;
+    /** Payment chain: "base" (default) or "solana". Can also be set via CLAWROUTER_PAYMENT_CHAIN env var. */
+    paymentChain?: PaymentChain;
+    /** Port to listen on (default: 8402) */
+    port?: number;
+    routingConfig?: Partial<RoutingConfig>;
+    /** Request timeout in ms (default: 180000 = 3 minutes). Covers on-chain tx + LLM response. */
+    requestTimeoutMs?: number;
+    /** Skip balance checks (for testing only). Default: false */
+    skipBalanceCheck?: boolean;
+    /** Override the balance monitor with a mock (for testing only). */
+    _balanceMonitorOverride?: AnyBalanceMonitor;
+    /**
+     * Session persistence config. When enabled, maintains model selection
+     * across requests within a session to prevent mid-task model switching.
+     */
+    sessionConfig?: Partial<SessionConfig>;
+    /**
+     * Auto-compress large requests to reduce network usage.
+     * When enabled, requests are automatically compressed using
+     * LLM-safe context compression (15-40% reduction).
+     * Default: true
+     */
+    autoCompressRequests?: boolean;
+    /**
+     * Threshold in KB to trigger auto-compression (default: 180).
+     * Requests larger than this are compressed before sending.
+     * Set to 0 to compress all requests.
+     */
+    compressionThresholdKB?: number;
+    /**
+     * Response caching config. When enabled, identical requests return
+     * cached responses instead of making new API calls.
+     * Default: enabled with 10 minute TTL, 200 max entries.
+     */
+    cacheConfig?: ResponseCacheConfig;
+    /**
+     * Maximum total spend (in USD) per session run.
+     * Default: undefined (no limit). Example: 0.5 = $0.50 per session.
+     */
+    maxCostPerRunUsd?: number;
+    /**
+     * How to enforce the per-run cost cap.
+     * - 'graceful' (default): when budget runs low, downgrade to cheaper models; use free model
+     *   as last resort. Only hard-stops when no model can serve the request.
+     * - 'strict': immediately return 429 once the session spend reaches the cap.
+     */
+    maxCostPerRunMode?: "graceful" | "strict";
+    /**
+     * Set of model IDs to exclude from routing.
+     * Excluded models are filtered out of fallback chains.
+     * Loaded from ~/.openclaw/blockrun/exclude-models.json
+     */
+    excludeModels?: Set<string>;
+    onReady?: (port: number) => void;
+    onError?: (error: Error) => void;
+    onPayment?: (info: {
+        model: string;
+        amount: string;
+        network: string;
+    }) => void;
+    onRouted?: (decision: RoutingDecision) => void;
+    /** Called when balance drops below $1.00 (warning, request still proceeds) */
+    onLowBalance?: (info: LowBalanceInfo) => void;
+    /** Called when balance is insufficient for a request (request fails) */
+    onInsufficientFunds?: (info: InsufficientFundsInfo) => void;
+};
+export type ProxyHandle = {
+    port: number;
+    baseUrl: string;
+    walletAddress: string;
+    solanaAddress?: string;
+    balanceMonitor: AnyBalanceMonitor;
+    close: () => Promise<void>;
+};
+type ModelListEntry = {
+    id: string;
+    object: "model";
+    created: number;
+    owned_by: string;
+};
+/**
+ * Build `/v1/models` response entries from the full OpenClaw model registry.
+ * This includes alias IDs (e.g., `flash`, `kimi`) so `/model <alias>` works reliably.
+ */
+export declare function buildProxyModelList(createdAt?: number): ModelListEntry[];
+/**
+ * Start the local x402 proxy server.
+ *
+ * If a proxy is already running on the target port, reuses it instead of failing.
+ * Port can be configured via BLOCKRUN_PROXY_PORT environment variable.
+ *
+ * Returns a handle with the assigned port, base URL, and a close function.
+ */
+export declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
+export {};
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

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

package/dist/proxy.debrand.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=proxy.debrand.test.d.ts.map

package/dist/proxy.debrand.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.debrand.test.d.ts","sourceRoot":"","sources":["../src/proxy.debrand.test.ts"],"names":[],"mappings":""}

package/dist/proxy.debrand.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { debrandSystemMessages } from "./proxy.js";
+describe("debrandSystemMessages", () => {
+    it("replaces blockrun/auto with the resolved model in system messages", () => {
+        const messages = [
+            {
+                role: "system",
+                content: "You are a personal assistant.\n\n## Runtime\nRuntime: model=blockrun/auto | default_model=blockrun/auto",
+            },
+            { role: "user", content: "Hello" },
+        ];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        expect(result[0].content).toBe("You are a personal assistant.\n\n## Runtime\nRuntime: model=deepseek/deepseek-chat | default_model=deepseek/deepseek-chat");
+        // User message untouched
+        expect(result[1].content).toBe("Hello");
+    });
+    it("replaces blockrun/eco and blockrun/premium profiles", () => {
+        const messages = [
+            {
+                role: "system",
+                content: "model=blockrun/eco | default_model=blockrun/premium",
+            },
+        ];
+        const result = debrandSystemMessages(messages, "google/gemini-2.5-flash");
+        expect(result[0].content).toBe("model=google/gemini-2.5-flash | default_model=google/gemini-2.5-flash");
+    });
+    it("strips blockrun/ prefix from explicit model names", () => {
+        const messages = [
+            {
+                role: "system",
+                content: "model=blockrun/openai/gpt-4o | default_model=blockrun/auto",
+            },
+        ];
+        const result = debrandSystemMessages(messages, "openai/gpt-4o");
+        expect(result[0].content).toBe("model=openai/gpt-4o | default_model=openai/gpt-4o");
+    });
+    it("does not modify non-system messages", () => {
+        const messages = [
+            { role: "user", content: "I use blockrun/auto for my tasks" },
+            { role: "assistant", content: "I'm Blockrun!" },
+        ];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        expect(result[0].content).toBe("I use blockrun/auto for my tasks");
+        expect(result[1].content).toBe("I'm Blockrun!");
+    });
+    it("returns same array reference when no changes needed", () => {
+        const messages = [
+            { role: "system", content: "You are a helpful assistant." },
+            { role: "user", content: "Hi" },
+        ];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        expect(result).toBe(messages); // same reference = no copy
+    });
+    it("handles non-string system content gracefully", () => {
+        const messages = [{ role: "system", content: [{ type: "text", text: "blockrun/auto" }] }];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        // Array content is not modified (only string content)
+        expect(result).toBe(messages);
+    });
+    it("is case-insensitive for blockrun prefix", () => {
+        const messages = [{ role: "system", content: "model=Blockrun/Auto" }];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        expect(result[0].content).toBe("model=deepseek/deepseek-chat");
+    });
+    it("replaces blockrun/free profile", () => {
+        const messages = [{ role: "system", content: "default_model=blockrun/free" }];
+        const result = debrandSystemMessages(messages, "nvidia/gpt-oss-120b");
+        expect(result[0].content).toBe("default_model=nvidia/gpt-oss-120b");
+    });
+    it("handles realistic OpenClaw system prompt with SOUL.md", () => {
+        // This simulates the actual system prompt OpenClaw generates,
+        // which caused the model to say "I'm Blockrun" (issue #99)
+        const systemContent = [
+            "You are a personal assistant running inside OpenClaw.",
+            "",
+            "## Runtime",
+            "Runtime: agent=main | host=openclaw | os=Darwin 25.3.0 (arm64) | node=v22.14.0 | model=blockrun/auto | default_model=blockrun/auto | channel=control-ui | thinking=off",
+            "",
+            "# Project Context",
+            "",
+            "## SOUL.md",
+            "",
+            "AIBot = Watson",
+            "User = Fred",
+        ].join("\n");
+        const messages = [
+            { role: "system", content: systemContent },
+            { role: "user", content: "Hey there!" },
+        ];
+        const result = debrandSystemMessages(messages, "deepseek/deepseek-chat");
+        // "blockrun" should be completely gone from system prompt
+        expect(result[0].content).not.toContain("blockrun");
+        // Resolved model should appear instead
+        expect(result[0].content).toContain("model=deepseek/deepseek-chat");
+        expect(result[0].content).toContain("default_model=deepseek/deepseek-chat");
+        // SOUL.md content should be preserved
+        expect(result[0].content).toContain("AIBot = Watson");
+        expect(result[0].content).toContain("User = Fred");
+    });
+});
+//# sourceMappingURL=proxy.debrand.test.js.map

package/dist/proxy.debrand.test.js.map

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

package/dist/proxy.degraded-response.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=proxy.degraded-response.test.d.ts.map

package/dist/proxy.degraded-response.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.degraded-response.test.d.ts","sourceRoot":"","sources":["../src/proxy.degraded-response.test.ts"],"names":[],"mappings":""}

package/dist/proxy.degraded-response.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { detectDegradedSuccessResponse } from "./proxy.js";
+describe("detectDegradedSuccessResponse", () => {
+    it("flags plain overload placeholder text", () => {
+        const result = detectDegradedSuccessResponse("The AI service is temporarily overloaded. Please try again in a moment.");
+        expect(result).toBeDefined();
+    });
+    it("flags overload placeholder inside successful chat response JSON", () => {
+        const payload = JSON.stringify({
+            choices: [
+                {
+                    message: {
+                        role: "assistant",
+                        content: "The AI service is temporarily overloaded. Please try again in a moment.",
+                    },
+                },
+            ],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toBeDefined();
+    });
+    it("flags known repetitive hallucination loop patterns", () => {
+        const payload = JSON.stringify({
+            choices: [
+                {
+                    message: {
+                        role: "assistant",
+                        content: `The boxed is the response.
+
+Yes.
+
+The response is the text.
+
+Yes.
+
+The final answer is the boxed.
+
+Yes.`,
+                    },
+                },
+            ],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toBeDefined();
+    });
+    it("flags empty turn: no content and no tool_calls with finish_reason stop", () => {
+        const payload = JSON.stringify({
+            choices: [
+                {
+                    message: { role: "assistant", content: "" },
+                    finish_reason: "stop",
+                },
+            ],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toMatch(/empty turn/);
+    });
+    it("flags empty turn: null content, no tool_calls, finish_reason stop", () => {
+        const payload = JSON.stringify({
+            choices: [{ message: { role: "assistant", content: null }, finish_reason: "stop" }],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toMatch(/empty turn/);
+    });
+    it("does not flag responses with tool_calls even if content is empty", () => {
+        const payload = JSON.stringify({
+            choices: [
+                {
+                    message: {
+                        role: "assistant",
+                        content: null,
+                        tool_calls: [
+                            { id: "call_1", type: "function", function: { name: "read_file", arguments: "{}" } },
+                        ],
+                    },
+                    finish_reason: "tool_calls",
+                },
+            ],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toBeUndefined();
+    });
+    it("does not flag empty turn when finish_reason is not stop", () => {
+        const payload = JSON.stringify({
+            choices: [{ message: { role: "assistant", content: "" }, finish_reason: "length" }],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toBeUndefined();
+    });
+    it("does not flag normal assistant responses", () => {
+        const payload = JSON.stringify({
+            choices: [
+                {
+                    message: {
+                        role: "assistant",
+                        content: "Paris is the capital of France.",
+                    },
+                },
+            ],
+        });
+        const result = detectDegradedSuccessResponse(payload);
+        expect(result).toBeUndefined();
+    });
+});
+//# sourceMappingURL=proxy.degraded-response.test.js.map

package/dist/proxy.degraded-response.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.degraded-response.test.js","sourceRoot":"","sources":["../src/proxy.degraded-response.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAE3D,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,MAAM,GAAG,6BAA6B,CAC1C,yEAAyE,CAC1E,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE;gBACP;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,WAAW;wBACjB,OAAO,EAAE,yEAAyE;qBACnF;iBACF;aACF;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE;gBACP;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,WAAW;wBACjB,OAAO,EAAE;;;;;;;;;;KAUhB;qBACM;iBACF;aACF;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE;gBACP;oBACE,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE;oBAC3C,aAAa,EAAE,MAAM;iBACtB;aACF;SACF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;SACpF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE;gBACP;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,WAAW;wBACjB,OAAO,EAAE,IAAI;wBACb,UAAU,EAAE;4BACV,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;yBACrF;qBACF;oBACD,aAAa,EAAE,YAAY;iBAC5B;aACF;SACF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;SACpF,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;YAC7B,OAAO,EAAE;gBACP;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,WAAW;wBACjB,OAAO,EAAE,iCAAiC;qBAC3C;iBACF;aACF;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/proxy.image-download.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=proxy.image-download.test.d.ts.map

package/dist/proxy.image-download.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.image-download.test.d.ts","sourceRoot":"","sources":["../src/proxy.image-download.test.ts"],"names":[],"mappings":""}