@x12i/openrouter-runtime 1.0.2 → 1.0.4

package/README.md

@@ -47,6 +47,15 @@ await runtime.run({
 });
 ```
 
+### Citation Policy
+
+`defaults.requireCitationsWhenSearchUsed` controls the package-wide default for web-search citation enforcement. A request-level `serverTools.webSearch.requireCitations` value overrides that default:
+
+- `requireCitations: true`: if web search is used and no citations are extracted, the runtime emits `CITATIONS_REQUIRED_BUT_MISSING`.
+- `requireCitations: false`: disables citation enforcement for that request, even if the global default is `true`.
+
+When `defaults.onPolicyViolation` is `"throw"`, citation policy failures are returned as `errors[]` with `source: "policy"` and `status: "policy_violation"`. When it is `"return_error"`, they remain in `warnings[]`.
+
 `applyPatch` automatically selects the Responses API. The runtime returns patch proposals and never mutates files unless an explicit `patchApplier` is supplied.
 
 ## Function Tools

package/dist/index.cjs

@@ -32,6 +32,7 @@ module.exports = __toCommonJS(index_exports);
 function resolveRuntimeOptions(options) {
   return {
     ...options,
+    apiKey: options.apiKey ?? readOpenRouterApiKeyFromEnv() ?? "",
     baseUrl: options.baseUrl ?? "https://openrouter.ai/api/v1",
     defaultHeaders: options.defaultHeaders ?? {},
     fetch: options.fetch ?? globalThis.fetch
@@ -59,6 +60,10 @@ function resolveDefaults(options) {
     }
   };
 }
+function readOpenRouterApiKeyFromEnv() {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  return env?.OPENROUTER_API_KEY || env?.OPEN_ROUTER_KEY;
+}
 
 // src/openrouter/errors.ts
 var RuntimeConfigError = class extends Error {
@@ -72,18 +77,20 @@ var RuntimeConfigError = class extends Error {
   details;
 };
 var OpenRouterHttpError = class extends Error {
-  constructor(status, code, message, body, retryable = false) {
+  constructor(status, code, message, body, retryable = false, providerAttempts = []) {
     super(message);
     this.status = status;
     this.code = code;
     this.body = body;
     this.retryable = retryable;
+    this.providerAttempts = providerAttempts;
     this.name = "OpenRouterHttpError";
   }
   status;
   code;
   body;
   retryable;
+  providerAttempts;
 };
 
 // src/utils/delay.ts
@@ -100,13 +107,35 @@ function retryDelay(attempt, baseDelayMs, maxDelayMs) {
 async function sendOpenRouterRequest(compiled, options, defaults, timeoutMs) {
   const attempts = defaults.retry.enabled ? defaults.retry.maxAttempts : 1;
   let lastError;
+  const providerAttempts = [];
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
       return await sendOnce(compiled, options, timeoutMs);
     } catch (error) {
       lastError = error;
+      if (error instanceof OpenRouterHttpError) {
+        const providerAttempt = toProviderAttempt(error, compiled);
+        providerAttempts.push(providerAttempt);
+        options.logger?.warn?.("openrouter.provider_attempt.failed", {
+          ...providerAttempt,
+          attempt,
+          maxAttempts: attempts
+        });
+      }
       const retryable = error instanceof OpenRouterHttpError ? error.retryable : true;
-      if (!retryable || attempt >= attempts) throw error;
+      if (!retryable || attempt >= attempts) {
+        if (error instanceof OpenRouterHttpError) {
+          throw new OpenRouterHttpError(
+            error.status,
+            error.code,
+            error.message,
+            error.body,
+            error.retryable,
+            providerAttempts
+          );
+        }
+        throw error;
+      }
       await delay(retryDelay(attempt, defaults.retry.baseDelayMs, defaults.retry.maxDelayMs));
     }
   }
@@ -125,10 +154,11 @@ async function sendOnce(compiled, options, timeoutMs) {
     const text = await response.text();
     const body = text ? parseBody(text) : void 0;
     if (!response.ok) {
+      const message = extractMessage(body) ?? `OpenRouter request failed with status ${response.status}.`;
       throw new OpenRouterHttpError(
         response.status,
-        statusToCode(response.status),
-        extractMessage(body) ?? `OpenRouter request failed with status ${response.status}.`,
+        classifyProviderFailure(response.status, message, body),
+        message,
         body,
         isRetryableStatus(response.status)
       );
@@ -137,9 +167,15 @@ async function sendOnce(compiled, options, timeoutMs) {
   } catch (error) {
     if (error instanceof OpenRouterHttpError) throw error;
     if (error instanceof Error && error.name === "AbortError") {
-      throw new OpenRouterHttpError(408, "OPENROUTER_TIMEOUT", "OpenRouter request timed out.", void 0, true);
+      throw new OpenRouterHttpError(408, "PROVIDER_GATEWAY_UNREACHABLE", "OpenRouter request timed out.", void 0, true);
     }
-    throw error;
+    throw new OpenRouterHttpError(
+      503,
+      "PROVIDER_GATEWAY_UNREACHABLE",
+      error instanceof Error ? error.message : "OpenRouter request failed before receiving a response.",
+      void 0,
+      true
+    );
   } finally {
     clearTimeout(timeout);
   }
@@ -160,10 +196,31 @@ function extractMessage(body) {
   }
   return typeof record.message === "string" ? record.message : void 0;
 }
-function statusToCode(status) {
-  if (status === 401) return "OPENROUTER_AUTH_FAILED";
-  if (status === 429) return "OPENROUTER_RATE_LIMITED";
-  return "OPENROUTER_REQUEST_FAILED";
+function toProviderAttempt(error, compiled) {
+  const modelId = typeof compiled.body.model === "string" ? compiled.body.model : void 0;
+  return {
+    provider: "openrouter",
+    ...modelId ? { modelId } : {},
+    httpStatus: error.status,
+    code: error.code,
+    message: error.message,
+    retryable: error.retryable
+  };
+}
+function classifyProviderFailure(status, message, body) {
+  const haystack = `${message} ${JSON.stringify(body ?? "")}`.toLowerCase();
+  if (status === 401 || status === 403) return "PROVIDER_AUTH_FAILED";
+  if (status === 402 || mentionsQuota(haystack)) return "PROVIDER_QUOTA_EXCEEDED";
+  if (status === 404 || mentionsMissingModel(haystack)) return "PROVIDER_MODEL_NOT_FOUND";
+  if (status === 429) return "PROVIDER_RATE_LIMITED";
+  if (status === 408 || status >= 500) return "PROVIDER_GATEWAY_UNREACHABLE";
+  return "PROVIDER_REQUEST_FAILED";
+}
+function mentionsQuota(text) {
+  return /\b(quota|credit|credits|billing|balance|insufficient funds|insufficient credit)\b/.test(text);
+}
+function mentionsMissingModel(text) {
+  return /\bmodel\b.*\b(not found|not a valid|invalid|unavailable)\b/.test(text) || /\b(no endpoints found|not a valid model id)\b/.test(text);
 }
 function isRetryableStatus(status) {
   return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
@@ -502,12 +559,13 @@ function optional3(key, value) {
 }
 
 // src/policies/post-response-validation.ts
-async function validatePostResponse(response, defaults) {
+async function validatePostResponse(response, defaults, serverTools) {
   const errors = [...response.errors];
   const warnings = [...response.warnings];
-  if (response.toolUsage.serverTools.webSearch.requested && response.citations.length > 0 && !response.toolUsage.serverTools.webSearch.used) {
-    response.toolUsage.serverTools.webSearch.used = true;
-    response.toolUsage.serverTools.webSearch.callCount = Math.max(response.toolUsage.serverTools.webSearch.callCount ?? 0, 1);
+  const webSearchUsage = response.toolUsage.serverTools.webSearch;
+  if (webSearchUsage.requested && response.citations.length > 0 && !webSearchUsage.used) {
+    webSearchUsage.used = true;
+    webSearchUsage.callCount = Math.max(webSearchUsage.callCount ?? 0, 1);
   }
   for (const [key, usage] of Object.entries(response.toolUsage.serverTools)) {
     if (usage.required && !usage.used) {
@@ -521,11 +579,18 @@ async function validatePostResponse(response, defaults) {
       }
     }
   }
-  if (defaults.requireCitationsWhenSearchUsed && response.toolUsage.serverTools.webSearch.requested && response.citations.length === 0) {
-    warnings.push({
+  const citationsRequired = serverTools?.webSearch?.requireCitations ?? defaults.requireCitationsWhenSearchUsed;
+  if (citationsRequired && webSearchUsage.used && response.citations.length === 0) {
+    const violation = {
       code: "CITATIONS_REQUIRED_BUT_MISSING",
-      message: "Web search was requested but no citations were extracted."
-    });
+      message: "Web search was used but no citations were extracted."
+    };
+    webSearchUsage.policyViolation = webSearchUsage.policyViolation ?? violation.code;
+    if (defaults.onPolicyViolation === "throw") {
+      errors.push({ ...violation, source: "policy" });
+    } else {
+      warnings.push(violation);
+    }
   }
   return {
     ...response,
@@ -1109,6 +1174,7 @@ async function runChat(request, compiled, context) {
     activeCompiled = { ...activeCompiled, body: { ...body, messages, tool_choice: "auto" } };
   }
   const model = typeof compiled.body.model === "string" ? compiled.body.model : "";
+  const serverTools = mergeServerTools(context.defaults.serverTools, request.serverTools);
   const normalized = normalizeChatResponse({
     requestBody: activeCompiled.body,
     response,
@@ -1116,10 +1182,10 @@ async function runChat(request, compiled, context) {
     model,
     warnings: compiled.warnings,
     functionToolUsage: functionUsage,
-    ...optional4("serverTools", mergeServerTools(context.defaults.serverTools, request.serverTools)),
+    ...optional4("serverTools", serverTools),
     ...optional4("metadata", request.metadata)
   });
-  return validatePostResponse(normalized, context.defaults);
+  return validatePostResponse(normalized, context.defaults, serverTools);
 }
 function optional4(key, value) {
   return value === void 0 ? {} : { [key]: value };
@@ -1211,16 +1277,17 @@ async function runResponses(request, compiled, context) {
     };
   }
   const model = typeof compiled.body.model === "string" ? compiled.body.model : "";
+  const serverTools = mergeServerTools(context.defaults.serverTools, request.serverTools);
   const normalized = normalizeResponsesResponse({
     requestBody: activeCompiled.body,
     response,
     model,
     warnings: compiled.warnings,
     functionToolUsage: functionUsage,
-    ...optional6("serverTools", mergeServerTools(context.defaults.serverTools, request.serverTools)),
+    ...optional6("serverTools", serverTools),
     ...optional6("metadata", request.metadata)
   });
-  return validatePostResponse(normalized, context.defaults);
+  return validatePostResponse(normalized, context.defaults, serverTools);
 }
 function optional6(key, value) {
   return value === void 0 ? {} : { [key]: value };
@@ -1294,6 +1361,7 @@ function normalizeError(error) {
       code: error.code,
       message: error.message,
       source: "validation",
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
       details: error.details
     };
   }
@@ -1303,7 +1371,11 @@ function normalizeError(error) {
       message: error.message,
       source: "openrouter",
       retryable: error.retryable,
-      details: error.body
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
+      details: {
+        providerAttempts: error.providerAttempts,
+        ...error.body === void 0 ? {} : { response: error.body }
+      }
     };
   }
   return {
@@ -1312,6 +1384,27 @@ function normalizeError(error) {
     source: "runtime"
   };
 }
+function optionalErrorField(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}
+function operatorHintFor(code) {
+  switch (code) {
+    case "OPENROUTER_API_KEY_MISSING":
+      return "Set OPENROUTER_API_KEY or OPEN_ROUTER_KEY, or pass apiKey when creating the runtime.";
+    case "PROVIDER_AUTH_FAILED":
+      return "Check that the OpenRouter API key is present, valid, and authorized for this route.";
+    case "PROVIDER_RATE_LIMITED":
+      return "Retry after the provider rate limit resets or reduce request concurrency.";
+    case "PROVIDER_QUOTA_EXCEEDED":
+      return "Check provider billing, credits, quota, and project limits.";
+    case "PROVIDER_MODEL_NOT_FOUND":
+      return "Verify the model id and whether it is available through OpenRouter for this account.";
+    case "PROVIDER_GATEWAY_UNREACHABLE":
+      return "Retry later; the provider gateway was unreachable or timed out.";
+    default:
+      return void 0;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OpenRouterHttpError,