@x12i/openrouter-runtime 1.0.4 → 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

@@ -890,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);
@@ -912,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),
@@ -920,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";
@@ -1293,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);
@@ -1304,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,
@@ -1318,7 +1338,8 @@ function createOpenRouterRuntime(options) {
       } catch (error) {
         return errorResponse(requestWithId, error);
       }
-    }
+    },
+    stream: streamNotImplemented
   };
   function errorResponse(request, error) {
     const runtimeError = normalizeError(error);