@framers/agentos 0.10.30 → 0.10.32

package/dist/core/llm/providers/implementations/OpenRouterProvider.js

@@ -11,6 +11,7 @@ import { OpenRouterProviderError } from '../errors/OpenRouterProviderError.js';
 import { ApiKeyPool } from '../../../providers/ApiKeyPool.js';
 import { createGMIErrorFromError, GMIErrorCode } from '../../../utils/errors.js'; // Corrected import path
 import { clampMaxOutputTokens } from '../model-output-limits.js';
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '../errors/errorCodes.js';
 import { stripGeminiOnlyParams } from '../openrouter-only-params.js';
 import { baseUrlCredentials, redactUrlSecrets } from '../url-secrets.js';
 /**
@@ -161,6 +162,68 @@ function parseErrorBody(text) {
         return text;
     }
 }
+/**
+ * Whether an OpenRouter error is a request larger than the model's context
+ * window. Once a provider took the request, OpenRouter types it
+ * `context_length_exceeded`. Its own check before routing answers HTTP 400
+ * with no type, only the message: "This endpoint's maximum context length is
+ * 16384 tokens. However, you requested about 33760 tokens ..." (observed
+ * 2026-10-05, for streamed and plain requests alike).
+ *
+ * @param errorType - The typed code, when the error carries one.
+ * @param code - The HTTP status, or the numeric code inside a 200 body or event.
+ * @param message - The error's message as OpenRouter sent it.
+ */
+function isContextWindowRejection(errorType, code, message) {
+    if (errorType === 'context_length_exceeded')
+        return true;
+    return code === 400 && /maximum context length is \d+ tokens/i.test(message);
+}
+/**
+ * A string error code that names a class (`server_error`), kept as the error's
+ * code. A number in a string (`'502'`) is not one: it is neither a status the
+ * registry should read nor a class the retry classifier knows.
+ */
+function namedErrorCode(code) {
+    return typeof code === 'string' && /^[a-z][a-z0-9_]*$/i.test(code) ? code : undefined;
+}
+/**
+ * Classify an OpenRouter error envelope as a content decline, or not.
+ *
+ * - `metadata.error_type` `refusal`: the model refused (code `content_filter`).
+ * - `metadata.error_type` `content_policy_violation`: a filter flagged the
+ *   input or output.
+ * - The documented moderation metadata (`reasons` + `flagged_input`) with no
+ *   `error_type`.
+ * - With `inBody`, a numeric code 403 and no `error_type`: the error reference
+ *   gives every in-body policy decline the code 403 once the HTTP line was
+ *   already committed. Never applied to an HTTP 403 response, which without a
+ *   decline type is a guardrail or permission block (`permission_denied`).
+ *
+ * @param error - The `error` object from an OpenRouter body, choice or event.
+ * @param opts.inBody - True when the error sits inside an HTTP 200 body.
+ * @returns The decline, or `undefined` when the error is not one.
+ */
+export function classifyOpenRouterDecline(error, opts = {}) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const env = error;
+    const meta = env.metadata && typeof env.metadata === 'object' ? env.metadata : undefined;
+    const errorType = typeof meta?.error_type === 'string' ? meta.error_type : undefined;
+    if (errorType === 'refusal')
+        return { code: 'content_filter', nativeType: 'refusal' };
+    if (errorType === 'content_policy_violation') {
+        return { code: 'content_policy_violation', nativeType: 'content_policy_violation' };
+    }
+    if (errorType !== undefined)
+        return undefined;
+    if (Array.isArray(meta?.reasons) && typeof meta?.flagged_input === 'string') {
+        return { code: 'content_policy_violation', nativeType: 'moderation' };
+    }
+    if (opts.inBody && env.code === 403)
+        return { code: 'content_policy_violation', nativeType: 'in_body_403' };
+    return undefined;
+}
 export class OpenRouterProvider {
     constructor() {
         this.providerId = 'openrouter';
@@ -451,6 +514,7 @@ export class OpenRouterProvider {
                 throw error;
             apiResponseData = await this.makeApiRequest('/chat/completions', 'POST', options.requestTimeout ?? this.config.requestTimeout, payload);
         }
+        this.throwOnInBodyError(apiResponseData, modelId);
         return this.mapApiToCompletionResponse(apiResponseData, modelId);
     }
     /**
@@ -578,40 +642,116 @@ export class OpenRouterProvider {
         }
         const accumulatedToolCalls = new Map();
         const abortSignal = options.abortSignal;
+        // `usage` is what a refused turn billed before the abort; a consumer
+        // metering final chunks would otherwise lose it.
+        const abortChunk = (message, usage) => ({
+            id: `openrouter-abort-${Date.now()}`,
+            object: 'chat.completion.chunk',
+            created: Math.floor(Date.now() / 1000),
+            modelId,
+            choices: [],
+            error: { message, type: 'abort' },
+            isFinal: true,
+            ...(usage ? { usage } : {}),
+        });
         if (abortSignal?.aborted) {
-            yield { id: `openrouter-abort-${Date.now()}`, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), modelId, choices: [], error: { message: 'Stream aborted prior to first chunk', type: 'abort' }, isFinal: true };
+            // The response is already open, and parseSseStream, which closes it,
+            // never runs on this path.
+            stream.destroy?.();
+            yield abortChunk('Stream aborted prior to first chunk');
             return;
         }
         const abortHandler = () => { };
         abortSignal?.addEventListener('abort', abortHandler, { once: true });
-        for await (const rawChunk of this.parseSseStream(stream)) {
-            if (abortSignal?.aborted) {
-                yield { id: `openrouter-abort-${Date.now()}`, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), modelId, choices: [], error: { message: 'Stream aborted by caller', type: 'abort' }, isFinal: true };
-                break;
-            }
-            if (rawChunk.startsWith('data: ') && rawChunk.includes('[DONE]')) {
-                const doneData = rawChunk.substring('data: '.length).trim();
-                if (doneData === '[DONE]')
-                    break;
-            }
-            if (rawChunk === 'data: [DONE]') {
-                break;
-            }
-            if (rawChunk.startsWith('data: ')) {
-                const jsonData = rawChunk.substring('data: '.length);
-                try {
-                    const apiChunk = JSON.parse(jsonData);
+        // Text yielded so far (for the decline's partialText); the
+        // decline held back when a content_filter finish arrives, while the
+        // trailing usage chunk is read; a read error seen during that wait.
+        let yieldedText = '';
+        let held = null;
+        let readError;
+        const isDecline = (e) => e instanceof OpenRouterProviderError && (e.code === 'content_filter' || e.code === 'content_policy_violation');
+        try {
+            try {
+                for await (const rawChunk of this.parseSseStream(stream)) {
+                    if (abortSignal?.aborted) {
+                        // The line that shows the abort is usually the usage line a held
+                        // decline was waiting for: read what it reports before leaving.
+                        if (held)
+                            held.usage = this.usageOfSseLine(rawChunk) ?? held.usage;
+                        yield abortChunk('Stream aborted by caller', held?.usage);
+                        return;
+                    }
+                    if (!rawChunk.startsWith('data: '))
+                        continue;
+                    const jsonData = rawChunk.substring('data: '.length);
+                    if (jsonData.trim() === '[DONE]')
+                        break;
+                    // The parse has its own catch, so a decline thrown while HANDLING
+                    // a chunk is never swallowed as a parse failure. A line that is not
+                    // JSON, or is JSON but not an object, is skipped as before.
+                    let apiChunk;
+                    try {
+                        apiChunk = JSON.parse(jsonData);
+                    }
+                    catch (error) {
+                        console.warn('OpenRouterProvider: Failed to parse stream chunk JSON, skipping chunk. Data:', jsonData, 'Error:', error);
+                        continue;
+                    }
+                    if (!apiChunk || typeof apiChunk !== 'object') {
+                        console.warn('OpenRouterProvider: Stream chunk is not a JSON object, skipping chunk. Data:', jsonData);
+                        continue;
+                    }
                     // OpenRouter reports upstream failures MID-STREAM as an SSE data
-                    // event carrying an `error` object and no choices. Previously this
-                    // fell into the empty-choices branch and surfaced as a generic
-                    // "Stream chunk contained no choices" — the real upstream reason
-                    // (provider outage, moderation, context overflow) was discarded,
-                    // which made every mid-stream failure look identical to callers'
-                    // retry/fallback routing. Surface the actual message + code and
-                    // terminate the stream.
+                    // event carrying an `error` object. A content decline throws typed
+                    // (the walkers move on before any output; after output the stream
+                    // ends with an error part). Any other error still surfaces as an
+                    // upstream_error chunk and ends the stream.
                     if (apiChunk.error && typeof apiChunk.error === 'object') {
+                        // The stream is an HTTP 200, so the in-body 403 row applies here too.
+                        const decline = classifyOpenRouterDecline(apiChunk.error, { inBody: true });
+                        if (decline) {
+                            throw this.declineError(modelId, decline, {
+                                httpStatus: typeof apiChunk.error.code === 'number' ? apiChunk.error.code : undefined,
+                                error: apiChunk.error,
+                                partialText: yieldedText,
+                                // The event's own usage when it reports one, else what the
+                                // held finish or the usage chunk reported.
+                                usage: mapOpenRouterUsage(apiChunk.usage) ?? held?.usage,
+                            });
+                        }
                         const errMessage = apiChunk.error.message || 'OpenRouter mid-stream error';
                         const errCode = apiChunk.error.code;
+                        // The typed code: metadata.error_type, else the envelope's own
+                        // `type`, in the order the HTTP error path reads them.
+                        const envelopeType = apiChunk.error.type;
+                        const errType = typeof apiChunk.error.metadata?.error_type === 'string'
+                            ? apiChunk.error.metadata.error_type
+                            : typeof envelopeType === 'string'
+                                ? envelopeType
+                                : undefined;
+                        // A 401 or 403 inside a 200 stream describes an upstream attempt,
+                        // not this key: without the `[NNN]` prefix the health registry
+                        // counts a transient failure, not its auth policy (as inBodyError
+                        // does for a 200 body).
+                        const decorated = errCode === 401 || errCode === 403
+                            ? `OpenRouter in-body error ${errCode}: ${errMessage}`
+                            : errCode !== undefined
+                                ? `[${errCode}] ${errMessage}`
+                                : errMessage;
+                        // A context-window rejection, or a string code such as
+                        // `server_error`, rides the chunk's `code` for the walkers.
+                        const chunkCode = isContextWindowRejection(errType, typeof errCode === 'number' ? errCode : undefined, errMessage)
+                            ? CONTEXT_WINDOW_EXCEEDED_CODE
+                            : namedErrorCode(errCode);
+                        if (held) {
+                            // The answer already ended on a content_filter finish. A later
+                            // upstream failure is the end of the read: it neither replaces
+                            // the held decline nor loses the usage read so far.
+                            if (apiChunk.usage)
+                                held.usage = mapOpenRouterUsage(apiChunk.usage);
+                            readError = new Error(decorated);
+                            break;
+                        }
                         yield {
                             id: apiChunk.id ?? `openrouter-error-${Date.now()}`,
                             object: 'chat.completion.chunk',
@@ -620,25 +760,79 @@ export class OpenRouterProvider {
                             choices: [],
                             isFinal: true,
                             error: {
-                                message: errCode !== undefined ? `[${errCode}] ${errMessage}` : errMessage,
+                                message: decorated,
                                 type: 'upstream_error',
+                                ...(chunkCode !== undefined ? { code: chunkCode } : {}),
                             },
                         };
                         break;
                     }
-                    yield this.mapApiToStreamChunkResponse(apiChunk, modelId, accumulatedToolCalls);
+                    if (held) {
+                        // After a content_filter finish only the trailing usage-only
+                        // chunk is wanted; nothing more is yielded.
+                        if (apiChunk.usage)
+                            held.usage = mapOpenRouterUsage(apiChunk.usage);
+                        continue;
+                    }
+                    const choice = apiChunk.choices?.[0];
+                    if (choice && choice.finish_reason === 'content_filter') {
+                        held = {
+                            decline: { code: 'content_filter', nativeType: 'content_filter_finish' },
+                            refusal: choice.delta?.refusal ?? choice.message?.refusal ?? null,
+                            usage: mapOpenRouterUsage(apiChunk.usage),
+                        };
+                        continue;
+                    }
+                    // A chunk of an unexpected shape (no choices array, a malformed
+                    // tool call) is logged and skipped, as it was when the parse and
+                    // the mapping shared one catch.
+                    let mapped;
+                    try {
+                        mapped = this.mapApiToStreamChunkResponse(apiChunk, modelId, accumulatedToolCalls);
+                    }
+                    catch (error) {
+                        console.warn('OpenRouterProvider: Failed to map stream chunk, skipping chunk. Data:', jsonData, 'Error:', this.describeError(error));
+                        continue;
+                    }
+                    if (mapped.responseTextDelta)
+                        yieldedText += mapped.responseTextDelta;
+                    yield mapped;
                     // Don't break on finish_reason: with stream_options.include_usage,
                     // OpenRouter (like OpenAI) emits a trailing usage-only chunk AFTER
-                    // the finish_reason chunk and BEFORE [DONE]. Breaking here would
-                    // skip the usage chunk and zero out the caller's token totals. The
-                    // [DONE] marker check above is the right termination signal.
+                    // the finish_reason chunk and BEFORE [DONE]. The [DONE] marker
+                    // check above is the right termination signal.
                 }
-                catch (error) {
-                    console.warn('OpenRouterProvider: Failed to parse stream chunk JSON, skipping chunk. Data:', jsonData, 'Error:', error);
+            }
+            catch (error) {
+                if (isDecline(error))
+                    throw error;
+                // A read error after a content_filter finish does not lose the
+                // decline: it is thrown below with the usage held so far.
+                if (held)
+                    readError = error;
+                else
+                    throw error;
+            }
+            if (held) {
+                // An abort during the wait wins over the decline. The loop only
+                // checks the signal when a line arrives, so a read that ended
+                // without one is checked here.
+                if (abortSignal?.aborted) {
+                    yield abortChunk('Stream aborted by caller', held.usage);
+                    return;
                 }
+                throw this.declineError(modelId, held.decline, {
+                    httpStatus: 200,
+                    refusal: held.refusal,
+                    partialText: yieldedText,
+                    usage: held.usage,
+                    readError,
+                });
             }
         }
-        abortSignal?.removeEventListener('abort', abortHandler);
+        finally {
+            abortSignal?.removeEventListener('abort', abortHandler);
+        }
     }
     async generateEmbeddings(modelId, texts, options) {
         this.ensureInitialized();
@@ -947,7 +1141,8 @@ export class OpenRouterProvider {
                     }
                     if (errorData?.error && typeof errorData.error === 'object') {
                         errorMessage = errorData.error.message || errorMessage;
-                        errorType = errorData.error.type || errorType;
+                        const metaType = errorData.error.metadata?.error_type;
+                        errorType = (typeof metaType === 'string' ? metaType : undefined) || errorData.error.type || errorType;
                     }
                     else if (typeof errorData === 'string' && errorData.trim()) {
                         errorMessage = errorData;
@@ -959,6 +1154,16 @@ export class OpenRouterProvider {
                 else if (error instanceof Error) {
                     errorMessage = error.message;
                 }
+                // A content decline is a verdict on the request, not provider
+                // health: throw it typed at once (no in-provider retry, no key
+                // cooldown) so the walkers move on and the breaker stays closed.
+                const decline = classifyOpenRouterDecline(errorData?.error);
+                if (decline) {
+                    throw this.declineError(String(body?.model ?? ''), decline, {
+                        httpStatus: statusCode,
+                        error: errorData.error,
+                    });
+                }
                 // A throttled (429) or credit-exhausted (402) key must not be
                 // reused by the next attempt/request — cool it down in the pool.
                 if ((statusCode === 402 || statusCode === 429) && this.keyPool?.hasKeys) {
@@ -968,7 +1173,7 @@ export class OpenRouterProvider {
                 // logic (e.g. isRetryableError, which greps for \b402\b) can route on it
                 // even when the OR API body provides a friendlier description.
                 const decoratedMessage = this.redactSecrets(statusCode ? `[${statusCode}] ${errorMessage}` : errorMessage);
-                lastError = new OpenRouterProviderError(decoratedMessage, 'API_REQUEST_FAILED', statusCode, errorType, {
+                lastError = new OpenRouterProviderError(decoratedMessage, isContextWindowRejection(errorType, statusCode, errorMessage) ? CONTEXT_WINDOW_EXCEEDED_CODE : 'API_REQUEST_FAILED', statusCode, errorType, {
                     requestEndpoint: endpoint,
                     requestBodyPreview: body ? JSON.stringify(body).substring(0, 200) + '...' : undefined,
                     responseData: this.redactResponseData(errorData),
@@ -996,6 +1201,110 @@ export class OpenRouterProvider {
         // the compiler + any future refactor honest.
         throw lastError ?? new OpenRouterProviderError('OpenRouter request failed.', 'API_REQUEST_FAILED');
     }
+    /**
+     * The error a declined request raises. Code `content_filter` or
+     * `content_policy_violation` is what `isContentPolicyRefusal` and the
+     * health registry's exemption read, so the walkers move on and no breaker
+     * opens. The message is fixed: no HTTP status digits and no upstream text,
+     * which retry classifiers grep for. The response status, the upstream
+     * message (redacted, 300 chars), the provider, the refusal text (300), the
+     * partial text (2,000) and the billed usage ride `details`.
+     */
+    declineError(modelId, decline, details) {
+        const meta = details.error?.metadata;
+        const bounded = (value, max) => typeof value === 'string' && value.length > 0 ? this.redactSecrets(value).slice(0, max) : undefined;
+        return new OpenRouterProviderError(`OpenRouter declined the request on ${modelId || 'the requested model'} (${decline.nativeType}).`, decline.code, undefined, decline.nativeType, {
+            httpStatus: details.httpStatus,
+            upstreamMessage: bounded(details.error?.message, 300),
+            providerName: typeof meta?.provider_name === 'string' ? meta.provider_name : undefined,
+            providerCode: typeof meta?.provider_code === 'string' ? meta.provider_code : undefined,
+            refusal: bounded(details.refusal, 300),
+            partialText: bounded(details.partialText, 2000),
+            usage: details.usage,
+            ...(details.readError !== undefined ? { readError: this.describeError(details.readError) } : {}),
+        });
+    }
+    /**
+     * A 200 body that reports a failure instead of an answer throws before
+     * mapping, in this order: a body holding only `error` and no
+     * choice; a choice ended by `finish_reason: 'error'` with its own error
+     * object; a choice ended by `finish_reason: 'content_filter'` (the model
+     * declined as output). A choice with `finish_reason: 'error'` and no error
+     * object is not a documented shape and is mapped as before.
+     */
+    throwOnInBodyError(body, modelId) {
+        const choices = Array.isArray(body.choices) ? body.choices : [];
+        const first = choices[0];
+        const usage = mapOpenRouterUsage(body.usage);
+        if (body.error && typeof body.error === 'object' && choices.length === 0) {
+            throw this.inBodyError(body.error, modelId, { responseId: body.id, usage });
+        }
+        if (first && first.finish_reason === 'error' && first.error && typeof first.error === 'object') {
+            throw this.inBodyError(first.error, modelId, {
+                responseId: body.id,
+                usage,
+                partialText: first.message?.content ?? null,
+            });
+        }
+        if (first && first.finish_reason === 'content_filter') {
+            throw this.declineError(modelId, { code: 'content_filter', nativeType: 'content_filter_finish' }, {
+                httpStatus: 200,
+                refusal: first.message?.refusal ?? null,
+                partialText: first.message?.content ?? null,
+                usage,
+            });
+        }
+    }
+    /**
+     * An error reported inside an HTTP 200 body: a decline becomes
+     * the decline error; anything else becomes the error an HTTP response with
+     * that code produces today, so `isRetryableError` and the breaker treat it
+     * by its code. The exception is a 401 or 403 that is not a decline: it is
+     * still retryable, but it carries no status, so it counts as a transient
+     * failure and not as a rejected key.
+     */
+    inBodyError(error, modelId, extra) {
+        const code = typeof error.code === 'number' ? error.code : undefined;
+        // A named string code (`server_error`) is kept as the error's code, as a
+        // stream error event's is, so the retry classifier reads it.
+        const stringCode = namedErrorCode(error.code);
+        const decline = classifyOpenRouterDecline(error, { inBody: true });
+        if (decline) {
+            return this.declineError(modelId, decline, {
+                httpStatus: code,
+                error,
+                partialText: extra.partialText,
+                usage: extra.usage,
+            });
+        }
+        // The body is untyped network input: a message that is not a string
+        // must not reach the redaction's string calls.
+        const message = this.redactSecrets(typeof error.message === 'string' && error.message ? error.message : 'OpenRouter reported an error in a 200 response');
+        // The typed code: metadata.error_type, else the envelope's own `type`, in
+        // the order the HTTP error path reads them.
+        const envelopeType = error.type;
+        const errorType = typeof error.metadata?.error_type === 'string'
+            ? error.metadata.error_type
+            : typeof envelopeType === 'string'
+                ? envelopeType
+                : undefined;
+        // The 200 means the configured key was accepted, so a 401 or 403 inside
+        // the body describes an upstream attempt (a BYOK key, a failover leg),
+        // not this account. Its code stays in the message, where the retry
+        // classifiers read it, and in details; the error carries no status and
+        // no `[NNN]` prefix, so the breaker counts one transient failure instead
+        // of opening its auth policy (one failure, 30 minutes) on one response.
+        const inBodyAuth = code === 401 || code === 403;
+        return new OpenRouterProviderError(code === undefined ? message : inBodyAuth ? `OpenRouter in-body error ${code}: ${message}` : `[${code}] ${message}`, isContextWindowRejection(errorType, code, message)
+            ? CONTEXT_WINDOW_EXCEEDED_CODE
+            : (stringCode ?? 'API_REQUEST_FAILED'), inBodyAuth ? undefined : code, errorType ?? 'UNKNOWN_API_ERROR', {
+            responseId: extra.responseId,
+            ...(inBodyAuth ? { httpStatus: code } : {}),
+            responseData: this.redactResponseData(error),
+            partialText: typeof extra.partialText === 'string' ? this.redactSecrets(extra.partialText).slice(0, 2000) : undefined,
+            usage: extra.usage,
+        });
+    }
     /**
      * Masks the configured API keys (the raw config value and each key in a
      * comma-separated pool) and any base-URL credentials out of text bound
@@ -1078,6 +1387,20 @@ export class OpenRouterProvider {
         }
         return { message: this.redactSecrets(String(error)) };
     }
+    /** The usage a raw SSE line reports, when it is a data line that carries one. */
+    usageOfSseLine(rawChunk) {
+        if (!rawChunk.startsWith('data: '))
+            return undefined;
+        try {
+            const parsed = JSON.parse(rawChunk.substring('data: '.length));
+            return parsed && typeof parsed === 'object'
+                ? mapOpenRouterUsage(parsed.usage)
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async *parseSseStream(stream) {
         let buffer = '';
         const readableStream = stream;