@x12i/openrouter-runtime 1.0.3 → 1.0.5

package/README.md

@@ -70,3 +70,47 @@ const runtime = createOpenRouterRuntime({
 ```
 
 Function calls are executed locally and looped back to OpenRouter until a final response is produced or `maxToolIterations` is reached.
+
+## Streaming
+
+`runtime.run(request)` is non-streaming by design. Use it for background tasks, graph nodes, tool calls, structured output, research jobs, classification, extraction, patch generation, and automation.
+
+```ts
+const response = await runtime.run({
+  model: "openai/gpt-5.2",
+  prompt: "Summarize this document."
+});
+```
+
+This sends a normal non-streaming OpenRouter request and returns a completed `RuntimeResponse`.
+
+### Why `run()` is not streaming
+
+`run()` is designed for reliable runtime execution, not token-by-token UI delivery.
+
+Most runtime calls are background operations: graph nodes, tool loops, extraction, classification, research, patch generation, and structured output. For those workloads, streaming adds connection complexity without improving the final result.
+
+When streaming support is added, it will be available through `runtime.stream(request)`, not through `runtime.run(request)`.
+
+```ts
+// Future API
+for await (const event of runtime.stream(request)) {
+  // send token deltas to browser/client
+}
+```
+
+Today, `stream()` is reserved and throws `STREAMING_NOT_IMPLEMENTED`. The package should be treated as a non-streaming runtime.
+
+Do not pass streaming through raw overrides:
+
+```ts
+await runtime.run({
+  model: "openai/gpt-5.2",
+  prompt: "Summarize this document.",
+  rawOpenRouterOverrides: {
+    stream: true
+  }
+});
+```
+
+If `rawOpenRouterOverrides.stream = true` is provided to `runtime.run()`, it is ignored and reported as a `STREAMING_OVERRIDE_IGNORED_FOR_RUN` warning.

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;
@@ -833,8 +890,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);
@@ -855,6 +913,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),
@@ -863,6 +922,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";
@@ -1236,6 +1305,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);
@@ -1247,7 +1324,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,
@@ -1261,7 +1338,8 @@ function createOpenRouterRuntime(options) {
       } catch (error) {
         return errorResponse(requestWithId, error);
       }
-    }
+    },
+    stream: streamNotImplemented
   };
   function errorResponse(request, error) {
     const runtimeError = normalizeError(error);
@@ -1304,6 +1382,7 @@ function normalizeError(error) {
       code: error.code,
       message: error.message,
       source: "validation",
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
       details: error.details
     };
   }
@@ -1313,7 +1392,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 {
@@ -1322,6 +1405,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,