@x12i/openrouter-runtime 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -6,7 +6,7 @@ interface OpenRouterRuntime {
     stream?(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
 }
 interface OpenRouterRuntimeOptions {
-    apiKey: string;
+    apiKey?: string;
     baseUrl?: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
@@ -311,6 +311,7 @@ interface RuntimeError {
     message: string;
     source: "runtime" | "validation" | "openrouter" | "tool_executor" | "policy";
     retryable?: boolean;
+    operatorHint?: string;
     details?: unknown;
 }
 interface RuntimeWarning {
@@ -366,29 +367,42 @@ type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | u
 
 declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
 
-declare function compileRuntimeRequest(request: RuntimeRequest, defaults: RuntimeDefaults, options?: OpenRouterRuntimeOptions): CompiledOpenRouterRequest;
+interface RuntimeCompileContext {
+    streaming: boolean;
+}
+interface OpenRouterTool {
+    type: string;
+    function?: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+    parameters?: Record<string, unknown>;
+}
+
+declare function compileRuntimeRequest(request: RuntimeRequest, defaults: RuntimeDefaults, options?: OpenRouterRuntimeOptions, context?: Partial<RuntimeCompileContext>): CompiledOpenRouterRequest;
 
 declare class RuntimeConfigError extends Error {
     readonly code: string;
     readonly details?: unknown | undefined;
     constructor(code: string, message: string, details?: unknown | undefined);
 }
+type ProviderFailureCode = "PROVIDER_AUTH_FAILED" | "PROVIDER_RATE_LIMITED" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_MODEL_NOT_FOUND" | "PROVIDER_GATEWAY_UNREACHABLE" | "PROVIDER_REQUEST_FAILED";
+interface ProviderAttemptError {
+    provider: string;
+    modelId?: string;
+    httpStatus?: number;
+    code: ProviderFailureCode;
+    message: string;
+    retryable?: boolean;
+}
 declare class OpenRouterHttpError extends Error {
     readonly status: number;
-    readonly code: string;
+    readonly code: ProviderFailureCode;
     readonly body?: unknown | undefined;
     readonly retryable: boolean;
-    constructor(status: number, code: string, message: string, body?: unknown | undefined, retryable?: boolean);
-}
-
-interface OpenRouterTool {
-    type: string;
-    function?: {
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
-    };
-    parameters?: Record<string, unknown>;
+    readonly providerAttempts: ProviderAttemptError[];
+    constructor(status: number, code: ProviderFailureCode, message: string, body?: unknown | undefined, retryable?: boolean, providerAttempts?: ProviderAttemptError[]);
 }
 
 declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy): OpenRouterTool[];

package/dist/index.js

@@ -2,6 +2,7 @@
 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
@@ -29,6 +30,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 {
@@ -42,18 +47,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
@@ -70,13 +77,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));
     }
   }
@@ -95,10 +124,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)
       );
@@ -107,9 +137,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);
   }
@@ -130,10 +166,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;
@@ -803,8 +860,9 @@ function buildSubagentTool(policy) {
 }
 
 // src/runtime/runtime.ts
-function compileRuntimeRequest(request, defaults, options = { apiKey: "" }) {
+function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, context = {}) {
   const warnings = [];
+  const effectiveContext = { streaming: false, ...context };
   const requestedModel = request.model ?? options.defaultModel ?? "";
   const normalized = normalizeModel(requestedModel);
   warnings.push(...normalized.warnings);
@@ -825,6 +883,7 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }) {
   const headers = buildHeaders(options);
   const baseBody = buildBaseBody(request, normalized.model, defaults, tools, serverTools);
   const body = apiMode === "chat" ? buildChatBody(request, baseBody) : buildResponsesBody(request, baseBody);
+  enforceStreamingPolicyForRun(body, warnings, effectiveContext);
   return {
     apiMode,
     url: endpointFor(options.baseUrl ?? "https://openrouter.ai/api/v1", apiMode),
@@ -833,6 +892,16 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }) {
     warnings
   };
 }
+function enforceStreamingPolicyForRun(body, warnings, context) {
+  if (context.streaming) return;
+  if (body.stream === true) {
+    warnings.push({
+      code: "STREAMING_OVERRIDE_IGNORED_FOR_RUN",
+      message: "runtime.run() is non-streaming. Use runtime.stream() when streaming is implemented."
+    });
+  }
+  delete body.stream;
+}
 function resolveApiMode(request, defaultMode = "auto", serverTools) {
   const mode = request.apiMode ?? defaultMode;
   if (mode === "chat") return "chat";
@@ -1206,6 +1275,14 @@ function optional6(key, value) {
   return value === void 0 ? {} : { [key]: value };
 }
 
+// src/runtime/streaming.ts
+async function* streamNotImplemented() {
+  throw new RuntimeConfigError(
+    "STREAMING_NOT_IMPLEMENTED",
+    "Streaming is reserved for a later phase. Use runtime.run() for non-streaming execution."
+  );
+}
+
 // src/runtime/create-runtime.ts
 function createOpenRouterRuntime(options) {
   const resolvedOptions = resolveRuntimeOptions(options);
@@ -1217,7 +1294,7 @@ function createOpenRouterRuntime(options) {
       try {
         resolvedOptions.logger?.info?.("runtime.request.started", { requestId: requestWithId.id });
         await resolvedOptions.hooks?.beforeCompile?.(requestWithId);
-        const compiled = compileRuntimeRequest(requestWithId, defaults, resolvedOptions);
+        const compiled = compileRuntimeRequest(requestWithId, defaults, resolvedOptions, { streaming: false });
         await resolvedOptions.hooks?.afterCompile?.(compiled);
         resolvedOptions.logger?.debug?.("runtime.request.compiled", {
           requestId: requestWithId.id,
@@ -1231,7 +1308,8 @@ function createOpenRouterRuntime(options) {
       } catch (error) {
         return errorResponse(requestWithId, error);
       }
-    }
+    },
+    stream: streamNotImplemented
   };
   function errorResponse(request, error) {
     const runtimeError = normalizeError(error);
@@ -1274,6 +1352,7 @@ function normalizeError(error) {
       code: error.code,
       message: error.message,
       source: "validation",
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
       details: error.details
     };
   }
@@ -1283,7 +1362,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 {
@@ -1292,6 +1375,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;
+  }
+}
 export {
   OpenRouterHttpError,
   RuntimeConfigError,