@x12i/openrouter-runtime 1.0.5 → 1.0.6

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,11 @@ 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.
+### `run()` is non-streaming — always
+
+`runtime.run(request)` never streams. It is the only supported execution path today.
+
+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({
@@ -84,33 +115,26 @@ const response = await runtime.run({
 
 This sends a normal non-streaming OpenRouter request and returns a completed `RuntimeResponse`.
 
-### Why `run()` is not streaming
+`run()` always sends `stream: false` on the OpenRouter body. Any truthy `rawOpenRouterOverrides.stream` is overwritten and reported as `STREAMING_OVERRIDE_IGNORED_FOR_RUN`. Nested `serverTools.advisor.stream` is also forced off with `ADVISOR_STREAMING_IGNORED_FOR_RUN`.
 
-`run()` is designed for reliable runtime execution, not token-by-token UI delivery.
+### Streaming lives on a separate method: `executeStreamingChat()`
 
-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.
+Streaming is **not** available through `run()`, and the old `runtime.stream()` name was **removed on purpose**.
 
-When streaming support is added, it will be available through `runtime.stream(request)`, not through `runtime.run(request)`.
+Clients that still call `runtime.stream(...)` will break. That is intentional — so mistaken streaming usage is caught immediately.
+
+The reserved streaming entrypoint is:
 
 ```ts
-// Future API
-for await (const event of runtime.stream(request)) {
-  // send token deltas to browser/client
+for await (const event of runtime.executeStreamingChat(request)) {
+  // token deltas / stream events (not implemented yet)
 }
 ```
 
-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
-  }
-});
-```
+Today, `executeStreamingChat()` throws `STREAMING_NOT_IMPLEMENTED`. Treat this package as a non-streaming runtime until that method is implemented.
 
-If `rawOpenRouterOverrides.stream = true` is provided to `runtime.run()`, it is ignored and reported as a `STREAMING_OVERRIDE_IGNORED_FOR_RUN` warning.
+| Method | Streaming? | Status |
+| --- | --- | --- |
+| `runtime.run(request)` | No | Supported |
+| `runtime.executeStreamingChat(request)` | Yes (future) | Throws `STREAMING_NOT_IMPLEMENTED` |
+| `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) {
@@ -924,13 +951,38 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
 }
 function enforceStreamingPolicyForRun(body, warnings, context) {
   if (context.streaming) return;
-  if (body.stream === true) {
+  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() when streaming is implemented.",
+      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 +1016,7 @@ function buildChatBody(request, baseBody) {
   return clean({
     ...baseBody,
     messages,
-    max_tokens: request.maxTokens,
+    max_completion_tokens: request.maxTokens,
     response_format: request.responseFormat
   });
 }
@@ -1306,10 +1358,10 @@ function optional6(key, value) {
 }
 
 // src/runtime/streaming.ts
-async function* streamNotImplemented() {
+async function* executeStreamingChatNotImplemented() {
   throw new RuntimeConfigError(
     "STREAMING_NOT_IMPLEMENTED",
-    "Streaming is reserved for a later phase. Use runtime.run() for non-streaming execution."
+    "executeStreamingChat() is reserved and not implemented yet. Use runtime.run() for non-streaming execution."
   );
 }
 
@@ -1322,24 +1374,43 @@ 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) {
+      resolvedOptions.logger?.warn?.("runtime.executeStreamingChat.called", {
+        requestId: request.id,
+        streaming: true,
+        entrypoint: "executeStreamingChat",
+        implemented: false
+      });
+      return executeStreamingChatNotImplemented();
+    }
   };
   function errorResponse(request, error) {
     const runtimeError = normalizeError(error);
@@ -1432,6 +1503,8 @@ function operatorHintFor(code) {
   RuntimeConfigError,
   buildOpenRouterServerTools,
   compileRuntimeRequest,
-  createOpenRouterRuntime
+  createConsoleLogger,
+  createOpenRouterRuntime,
+  isRuntimeLoggingEnabled
 });
 //# sourceMappingURL=index.cjs.map