@x12i/openrouter-runtime 1.0.4 → 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`:
@@ -70,3 +97,44 @@ const runtime = createOpenRouterRuntime({
 ```
 
 Function calls are executed locally and looped back to OpenRouter until a final response is produced or `maxToolIterations` is reached.
+
+## Streaming
+
+### `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({
+  model: "openai/gpt-5.2",
+  prompt: "Summarize this document."
+});
+```
+
+This sends a normal non-streaming OpenRouter request and returns a completed `RuntimeResponse`.
+
+`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`.
+
+### Streaming lives on a separate method: `executeStreamingChat()`
+
+Streaming is **not** available through `run()`, and the old `runtime.stream()` name was **removed on purpose**.
+
+Clients that still call `runtime.stream(...)` will break. That is intentional — so mistaken streaming usage is caught immediately.
+
+The reserved streaming entrypoint is:
+
+```ts
+for await (const event of runtime.executeStreamingChat(request)) {
+  // token deltas / stream events (not implemented yet)
+}
+```
+
+Today, `executeStreamingChat()` throws `STREAMING_NOT_IMPLEMENTED`. Treat this package as a non-streaming runtime until that method is implemented.
+
+| 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) {
@@ -890,8 +917,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);
@@ -912,6 +940,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),
@@ -920,6 +949,41 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }) {
     warnings
   };
 }
+function enforceStreamingPolicyForRun(body, warnings, context) {
+  if (context.streaming) 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.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 }
+    });
+  }
+}
 function resolveApiMode(request, defaultMode = "auto", serverTools) {
   const mode = request.apiMode ?? defaultMode;
   if (mode === "chat") return "chat";
@@ -952,7 +1016,7 @@ function buildChatBody(request, baseBody) {
   return clean({
     ...baseBody,
     messages,
-    max_tokens: request.maxTokens,
+    max_completion_tokens: request.maxTokens,
     response_format: request.responseFormat
   });
 }
@@ -1293,6 +1357,14 @@ function optional6(key, value) {
   return value === void 0 ? {} : { [key]: value };
 }
 
+// src/runtime/streaming.ts
+async function* executeStreamingChatNotImplemented() {
+  throw new RuntimeConfigError(
+    "STREAMING_NOT_IMPLEMENTED",
+    "executeStreamingChat() is reserved and not implemented yet. Use runtime.run() for non-streaming execution."
+  );
+}
+
 // src/runtime/create-runtime.ts
 function createOpenRouterRuntime(options) {
   const resolvedOptions = resolveRuntimeOptions(options);
@@ -1302,22 +1374,42 @@ 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);
+        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);
       }
+    },
+    executeStreamingChat(request) {
+      resolvedOptions.logger?.warn?.("runtime.executeStreamingChat.called", {
+        requestId: request.id,
+        streaming: true,
+        entrypoint: "executeStreamingChat",
+        implemented: false
+      });
+      return executeStreamingChatNotImplemented();
     }
   };
   function errorResponse(request, error) {
@@ -1411,6 +1503,8 @@ function operatorHintFor(code) {
   RuntimeConfigError,
   buildOpenRouterServerTools,
   compileRuntimeRequest,
-  createOpenRouterRuntime
+  createConsoleLogger,
+  createOpenRouterRuntime,
+  isRuntimeLoggingEnabled
 });
 //# sourceMappingURL=index.cjs.map