@x12i/openrouter-runtime 1.0.5 → 1.1.0

package/README.md

@@ -32,6 +32,33 @@ const response = await runtime.run({
 console.log(response.text);
 ```
 
+## Console logging
+
+Turn on runtime console logs with:
+
+```bash
+OPENROUTER_RUNTIME_LOGS=true
+```
+
+When that env var is `true` / `1` / `yes` / `on`, and you do not pass a custom `logger`, the runtime logs to the console:
+
+- `runtime.request.started` — includes `streaming: false` and `entrypoint: "run"`
+- `runtime.request.compiled` — includes `bodyStream: false` and any streaming-related warning codes
+- `runtime.response.normalized`
+- `runtime.executeStreamingChat.called` — if someone hits the reserved streaming method
+- provider retry / function-tool events
+
+This package does **not** auto-load `.env`. Put the vars in your environment (shell export, process manager, or host `dotenv`) before calling `createOpenRouterRuntime()`. See `.env.example`.
+
+Example:
+
+```bash
+OPEN_ROUTER_KEY=sk-or-...
+OPENROUTER_RUNTIME_LOGS=true
+```
+
+You can still pass an explicit `logger` to override the console logger.
+
 ## Server Tools
 
 Enable OpenRouter server tools through `serverTools`:
@@ -73,7 +100,9 @@ Function calls are executed locally and looped back to OpenRouter until a final
 
 ## 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.
+Streaming is a **separate API**. It is never an argument on `run()`, never the default, and never available through the removed `stream()` name.
+
+### `run()` — non-streaming only
 
 ```ts
 const response = await runtime.run({
@@ -82,35 +111,35 @@ const response = await runtime.run({
 });
 ```
 
-This sends a normal non-streaming OpenRouter request and returns a completed `RuntimeResponse`.
+- Always sends `stream: false`
+- Returns a completed `RuntimeResponse`
+- Use for tools, research, extraction, patches, automation
 
-### Why `run()` is not streaming
+Any truthy `rawOpenRouterOverrides.stream` is overwritten (`STREAMING_OVERRIDE_IGNORED_FOR_RUN`). Nested `advisor.stream` is forced off (`ADVISOR_STREAMING_IGNORED_FOR_RUN`).
 
-`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)`.
+### `executeStreamingChat()` — streaming only
 
 ```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({
+for await (const event of runtime.executeStreamingChat({
   model: "openai/gpt-5.2",
-  prompt: "Summarize this document.",
-  rawOpenRouterOverrides: {
-    stream: true
+  prompt: "Say hello"
+})) {
+  if (event.type === "stream.text.delta") {
+    process.stdout.write(event.data.text);
   }
-});
+  if (event.type === "stream.done") {
+    console.log("\nfinal:", event.data.text);
+  }
+}
 ```
 
-If `rawOpenRouterOverrides.stream = true` is provided to `runtime.run()`, it is ignored and reported as a `STREAMING_OVERRIDE_IGNORED_FOR_RUN` warning.
+- Always sends `stream: true` (Chat Completions SSE)
+- Yields typed events: `stream.start`, `stream.text.delta`, `stream.tool_call.delta`, `stream.usage`, `stream.warning`, `stream.error`, `stream.done`
+- Chat Completions only — Responses / `applyPatch` must use `run()`
+- Local function-tool loops are not run here; use `run()` for tool iteration
+
+| Method | Streaming? | Notes |
+| --- | --- | --- |
+| `runtime.run(request)` | No | Default execution path |
+| `runtime.executeStreamingChat(request)` | Yes | Explicit streaming API |
+| `runtime.stream(request)` | — | **Removed** — breaks by design |

package/dist/index.cjs

@@ -24,18 +24,45 @@ __export(index_exports, {
   RuntimeConfigError: () => RuntimeConfigError,
   buildOpenRouterServerTools: () => buildOpenRouterServerTools,
   compileRuntimeRequest: () => compileRuntimeRequest,
-  createOpenRouterRuntime: () => createOpenRouterRuntime
+  createConsoleLogger: () => createConsoleLogger,
+  createOpenRouterRuntime: () => createOpenRouterRuntime,
+  isRuntimeLoggingEnabled: () => isRuntimeLoggingEnabled
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/utils/console-logger.ts
+var TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+function isRuntimeLoggingEnabled(env = typeof process === "undefined" ? void 0 : process.env) {
+  const value = env?.OPENROUTER_RUNTIME_LOGS?.trim().toLowerCase();
+  return value !== void 0 && TRUTHY.has(value);
+}
+function createConsoleLogger() {
+  return {
+    debug(event, data) {
+      console.debug(`[openrouter-runtime] ${event}`, data ?? "");
+    },
+    info(event, data) {
+      console.info(`[openrouter-runtime] ${event}`, data ?? "");
+    },
+    warn(event, data) {
+      console.warn(`[openrouter-runtime] ${event}`, data ?? "");
+    },
+    error(event, data) {
+      console.error(`[openrouter-runtime] ${event}`, data ?? "");
+    }
+  };
+}
+
 // src/config/defaults.ts
 function resolveRuntimeOptions(options) {
+  const logger = options.logger ?? (isRuntimeLoggingEnabled() ? createConsoleLogger() : void 0);
   return {
     ...options,
     apiKey: options.apiKey ?? readOpenRouterApiKeyFromEnv() ?? "",
     baseUrl: options.baseUrl ?? "https://openrouter.ai/api/v1",
     defaultHeaders: options.defaultHeaders ?? {},
-    fetch: options.fetch ?? globalThis.fetch
+    fetch: options.fetch ?? globalThis.fetch,
+    ...logger ? { logger } : {}
   };
 }
 function resolveDefaults(options) {
@@ -923,14 +950,42 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
   };
 }
 function enforceStreamingPolicyForRun(body, warnings, context) {
-  if (context.streaming) return;
-  if (body.stream === true) {
+  if (context.streaming) {
+    body.stream = true;
+    return;
+  }
+  if (body.stream !== void 0 && body.stream !== false) {
     warnings.push({
       code: "STREAMING_OVERRIDE_IGNORED_FOR_RUN",
-      message: "runtime.run() is non-streaming. Use runtime.stream() when streaming is implemented."
+      message: "runtime.run() is non-streaming. Use runtime.executeStreamingChat() for streaming.",
+      details: { ignoredStreamValue: body.stream }
+    });
+  }
+  body.stream = false;
+  stripAdvisorStreaming(body, warnings);
+}
+function stripAdvisorStreaming(body, warnings) {
+  const tools = body.tools;
+  if (!Array.isArray(tools)) return;
+  let stripped = 0;
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object") continue;
+    const record = tool;
+    if (record.type !== "openrouter:advisor") continue;
+    const parameters = record.parameters;
+    if (!parameters || typeof parameters !== "object") continue;
+    const params = parameters;
+    if (params.stream === void 0 || params.stream === false) continue;
+    params.stream = false;
+    stripped += 1;
+  }
+  if (stripped > 0) {
+    warnings.push({
+      code: "ADVISOR_STREAMING_IGNORED_FOR_RUN",
+      message: "runtime.run() disables advisor.stream. Nested advisor streaming is not supported on the non-streaming entrypoint.",
+      details: { advisorsStripped: stripped }
     });
   }
-  delete body.stream;
 }
 function resolveApiMode(request, defaultMode = "auto", serverTools) {
   const mode = request.apiMode ?? defaultMode;
@@ -964,7 +1019,7 @@ function buildChatBody(request, baseBody) {
   return clean({
     ...baseBody,
     messages,
-    max_tokens: request.maxTokens,
+    max_completion_tokens: request.maxTokens,
     response_format: request.responseFormat
   });
 }
@@ -1305,12 +1360,333 @@ function optional6(key, value) {
   return value === void 0 ? {} : { [key]: value };
 }
 
+// src/openrouter/stream-client.ts
+async function openOpenRouterStream(compiled, options, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const cleanup = () => clearTimeout(timeout);
+  try {
+    const response = await options.fetch(compiled.url, {
+      method: "POST",
+      headers: {
+        ...compiled.headers,
+        Accept: "text/event-stream"
+      },
+      body: JSON.stringify(compiled.body),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      cleanup();
+      const body = text ? parseBody2(text) : void 0;
+      const message = extractMessage2(body) ?? `OpenRouter stream failed with status ${response.status}.`;
+      throw new OpenRouterHttpError(
+        response.status,
+        classifyProviderFailure2(response.status, message, body),
+        message,
+        body,
+        isRetryableStatus2(response.status)
+      );
+    }
+    return { response, cleanup };
+  } catch (error) {
+    cleanup();
+    if (error instanceof OpenRouterHttpError) throw error;
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new OpenRouterHttpError(408, "PROVIDER_GATEWAY_UNREACHABLE", "OpenRouter stream timed out.", void 0, true);
+    }
+    throw new OpenRouterHttpError(
+      503,
+      "PROVIDER_GATEWAY_UNREACHABLE",
+      error instanceof Error ? error.message : "OpenRouter stream failed before receiving a response.",
+      void 0,
+      true
+    );
+  }
+}
+async function* parseSseStream(response) {
+  const body = response.body;
+  if (!body) {
+    throw new OpenRouterHttpError(
+      503,
+      "PROVIDER_GATEWAY_UNREACHABLE",
+      "OpenRouter stream response had no body.",
+      void 0,
+      true
+    );
+  }
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const parts = buffer.split(/\r?\n/);
+    buffer = parts.pop() ?? "";
+    for (const part of parts) {
+      const line = part.trim();
+      if (!line || line.startsWith(":")) continue;
+      if (!line.startsWith("data:")) continue;
+      const data = line.slice(5).trim();
+      if (!data) continue;
+      if (data === "[DONE]") return;
+      try {
+        yield JSON.parse(data);
+      } catch {
+      }
+    }
+  }
+  const trailing = buffer.trim();
+  if (trailing.startsWith("data:")) {
+    const data = trailing.slice(5).trim();
+    if (data && data !== "[DONE]") {
+      try {
+        yield JSON.parse(data);
+      } catch {
+      }
+    }
+  }
+}
+function parseBody2(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function extractMessage2(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const record = body;
+  const error = record.error;
+  if (typeof error === "object" && error !== null && typeof error.message === "string") {
+    return error.message;
+  }
+  return typeof record.message === "string" ? record.message : void 0;
+}
+function classifyProviderFailure2(status, message, body) {
+  const haystack = `${message} ${JSON.stringify(body ?? "")}`.toLowerCase();
+  if (status === 401 || status === 403) return "PROVIDER_AUTH_FAILED";
+  if (status === 402 || /\b(quota|credit|credits|billing|balance|insufficient funds|insufficient credit)\b/.test(haystack)) {
+    return "PROVIDER_QUOTA_EXCEEDED";
+  }
+  if (status === 404 || /\bmodel\b.*\b(not found|not a valid|invalid|unavailable)\b/.test(haystack) || /\b(no endpoints found|not a valid model id)\b/.test(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 isRetryableStatus2(status) {
+  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+
 // 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."
-  );
+async function* executeStreamingChat(request, context) {
+  const requestId = request.id ?? "unknown";
+  const options = context.options;
+  const defaults = context.defaults;
+  options.logger?.info?.("runtime.executeStreamingChat.started", {
+    requestId,
+    streaming: true,
+    entrypoint: "executeStreamingChat"
+  });
+  try {
+    assertStreamingChatRequest(request, defaults);
+    const streamingRequest = {
+      ...request,
+      apiMode: "chat"
+    };
+    const compiled = compileRuntimeRequest(streamingRequest, defaults, options, { streaming: true });
+    if (compiled.body.stream !== true) {
+      throw new RuntimeConfigError(
+        "STREAMING_CHAT_MISCONFIGURED",
+        "executeStreamingChat() requires stream=true on the compiled OpenRouter body."
+      );
+    }
+    for (const warning of compiled.warnings) {
+      yield warningEvent(requestId, warning);
+    }
+    const model = typeof compiled.body.model === "string" ? compiled.body.model : "";
+    yield startEvent(requestId, model);
+    await options.hooks?.beforeOpenRouterRequest?.(compiled);
+    const timeoutMs = request.execution?.timeoutMs ?? defaults.timeoutMs;
+    const session = await openOpenRouterStream(compiled, options, timeoutMs);
+    let text = "";
+    let finishReason;
+    let resolvedModel = model;
+    try {
+      for await (const chunk of parseSseStream(session.response)) {
+        if (!isRecord(chunk)) continue;
+        if (chunk.error) {
+          const message = isRecord(chunk.error) && typeof chunk.error.message === "string" ? chunk.error.message : "OpenRouter stream returned an error chunk.";
+          const error = {
+            code: "PROVIDER_REQUEST_FAILED",
+            message,
+            source: "openrouter",
+            details: chunk.error
+          };
+          yield errorEvent(requestId, error);
+          throw new OpenRouterHttpError(500, "PROVIDER_REQUEST_FAILED", message, chunk, false);
+        }
+        if (typeof chunk.model === "string") resolvedModel = chunk.model;
+        const choice = Array.isArray(chunk.choices) && isRecord(chunk.choices[0]) ? chunk.choices[0] : void 0;
+        const delta = choice && isRecord(choice.delta) ? choice.delta : void 0;
+        if (delta && typeof delta.content === "string" && delta.content.length > 0) {
+          text += delta.content;
+          yield textDeltaEvent(requestId, delta.content);
+        }
+        if (delta && Array.isArray(delta.tool_calls)) {
+          for (const toolCall of delta.tool_calls) {
+            if (!isRecord(toolCall)) continue;
+            const index = typeof toolCall.index === "number" ? toolCall.index : 0;
+            const fn = isRecord(toolCall.function) ? toolCall.function : {};
+            yield toolCallDeltaEvent(requestId, {
+              index,
+              ...typeof toolCall.id === "string" ? { id: toolCall.id } : {},
+              ...typeof fn.name === "string" ? { name: fn.name } : {},
+              ...typeof fn.arguments === "string" ? { argumentsDelta: fn.arguments } : {}
+            });
+          }
+        }
+        if (choice && typeof choice.finish_reason === "string") {
+          finishReason = choice.finish_reason;
+        }
+        if (chunk.usage) {
+          const usage = normalizeUsage(chunk.usage);
+          if (usage) yield usageEvent(requestId, usage);
+        }
+      }
+    } finally {
+      session.cleanup();
+    }
+    await options.hooks?.afterOpenRouterResponse?.({ streamed: true, text, finishReason, model: resolvedModel });
+    yield doneEvent(requestId, {
+      text,
+      model: resolvedModel,
+      ...finishReason ? { finishReason } : {}
+    });
+    options.logger?.info?.("runtime.executeStreamingChat.completed", {
+      requestId,
+      streaming: true,
+      entrypoint: "executeStreamingChat",
+      finishReason,
+      textLength: text.length
+    });
+  } catch (error) {
+    const runtimeError = toRuntimeError(error);
+    yield errorEvent(requestId, runtimeError);
+    options.logger?.error?.("runtime.executeStreamingChat.failed", {
+      requestId,
+      streaming: true,
+      code: runtimeError.code,
+      message: runtimeError.message
+    });
+    throw error instanceof Error ? error : new Error(runtimeError.message);
+  }
+}
+function assertStreamingChatRequest(request, defaults) {
+  if (request.apiMode === "responses") {
+    throw new RuntimeConfigError(
+      "STREAMING_CHAT_REQUIRES_CHAT_API",
+      "executeStreamingChat() only supports Chat Completions. Use runtime.run() for Responses API requests."
+    );
+  }
+  if (request.serverTools?.applyPatch?.mode && request.serverTools.applyPatch.mode !== "disabled") {
+    throw new RuntimeConfigError(
+      "STREAMING_CHAT_DOES_NOT_SUPPORT_APPLY_PATCH",
+      "executeStreamingChat() does not support applyPatch. Use runtime.run() instead."
+    );
+  }
+  if (defaults.serverTools?.applyPatch?.mode && defaults.serverTools.applyPatch.mode !== "disabled") {
+    const requestPatch = request.serverTools?.applyPatch;
+    if (!requestPatch || requestPatch.mode !== "disabled") {
+      throw new RuntimeConfigError(
+        "STREAMING_CHAT_DOES_NOT_SUPPORT_APPLY_PATCH",
+        "executeStreamingChat() does not support applyPatch defaults. Use runtime.run() instead."
+      );
+    }
+  }
+}
+function startEvent(requestId, model) {
+  return {
+    type: "stream.start",
+    requestId,
+    data: {
+      model,
+      apiMode: "chat",
+      entrypoint: "executeStreamingChat"
+    }
+  };
+}
+function textDeltaEvent(requestId, text) {
+  return {
+    type: "stream.text.delta",
+    requestId,
+    data: { text }
+  };
+}
+function toolCallDeltaEvent(requestId, data) {
+  return {
+    type: "stream.tool_call.delta",
+    requestId,
+    data
+  };
+}
+function usageEvent(requestId, usage) {
+  return {
+    type: "stream.usage",
+    requestId,
+    data: { usage }
+  };
+}
+function warningEvent(requestId, warning) {
+  return {
+    type: "stream.warning",
+    requestId,
+    data: { warning }
+  };
+}
+function errorEvent(requestId, error) {
+  return {
+    type: "stream.error",
+    requestId,
+    data: { error }
+  };
+}
+function doneEvent(requestId, data) {
+  return {
+    type: "stream.done",
+    requestId,
+    data
+  };
+}
+function toRuntimeError(error) {
+  if (error instanceof RuntimeConfigError) {
+    return {
+      code: error.code,
+      message: error.message,
+      source: "validation",
+      details: error.details
+    };
+  }
+  if (error instanceof OpenRouterHttpError) {
+    return {
+      code: error.code,
+      message: error.message,
+      source: "openrouter",
+      retryable: error.retryable,
+      details: {
+        providerAttempts: error.providerAttempts,
+        ...error.body === void 0 ? {} : { response: error.body }
+      }
+    };
+  }
+  return {
+    code: "RUNTIME_ERROR",
+    message: error instanceof Error ? error.message : String(error),
+    source: "runtime"
+  };
 }
 
 // src/runtime/create-runtime.ts
@@ -1322,24 +1698,38 @@ function createOpenRouterRuntime(options) {
     async run(request) {
       const requestWithId = { ...request, id: request.id ?? createRuntimeId() };
       try {
-        resolvedOptions.logger?.info?.("runtime.request.started", { requestId: requestWithId.id });
+        resolvedOptions.logger?.info?.("runtime.request.started", {
+          requestId: requestWithId.id,
+          streaming: false,
+          entrypoint: "run"
+        });
         await resolvedOptions.hooks?.beforeCompile?.(requestWithId);
         const compiled = compileRuntimeRequest(requestWithId, defaults, resolvedOptions, { streaming: false });
         await resolvedOptions.hooks?.afterCompile?.(compiled);
         resolvedOptions.logger?.debug?.("runtime.request.compiled", {
           requestId: requestWithId.id,
-          apiMode: compiled.apiMode
+          apiMode: compiled.apiMode,
+          streaming: false,
+          bodyStream: compiled.body.stream,
+          streamingWarnings: compiled.warnings.filter((warning) => warning.code.includes("STREAMING") || warning.code.includes("ADVISOR_STREAMING")).map((warning) => warning.code)
         });
         await resolvedOptions.hooks?.beforeOpenRouterRequest?.(compiled);
         const response = compiled.apiMode === "chat" ? await runChat(requestWithId, compiled, context) : await runResponses(requestWithId, compiled, context);
         await resolvedOptions.hooks?.afterOpenRouterResponse?.(response.raw.response);
-        resolvedOptions.logger?.info?.("runtime.response.normalized", { requestId: requestWithId.id, status: response.status });
+        resolvedOptions.logger?.info?.("runtime.response.normalized", {
+          requestId: requestWithId.id,
+          status: response.status,
+          streaming: false
+        });
         return response;
       } catch (error) {
         return errorResponse(requestWithId, error);
       }
     },
-    stream: streamNotImplemented
+    executeStreamingChat(request) {
+      const requestWithId = { ...request, id: request.id ?? createRuntimeId() };
+      return executeStreamingChat(requestWithId, context);
+    }
   };
   function errorResponse(request, error) {
     const runtimeError = normalizeError(error);
@@ -1432,6 +1822,8 @@ function operatorHintFor(code) {
   RuntimeConfigError,
   buildOpenRouterServerTools,
   compileRuntimeRequest,
-  createOpenRouterRuntime
+  createConsoleLogger,
+  createOpenRouterRuntime,
+  isRuntimeLoggingEnabled
 });
 //# sourceMappingURL=index.cjs.map