@x12i/openrouter-runtime 1.0.6 → 1.1.0

package/README.md

@@ -100,11 +100,9 @@ Function calls are executed locally and looped back to OpenRouter until a final
 
 ## Streaming
 
-### `run()` is non-streaming — always
+Streaming is a **separate API**. It is never an argument on `run()`, never the default, and never available through the removed `stream()` name.
 
-`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.
+### `run()` — non-streaming only
 
 ```ts
 const response = await runtime.run({
@@ -113,28 +111,35 @@ const response = await runtime.run({
 });
 ```
 
-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**.
+- Always sends `stream: false`
+- Returns a completed `RuntimeResponse`
+- Use for tools, research, extraction, patches, automation
 
-Clients that still call `runtime.stream(...)` will break. That is intentional — so mistaken streaming usage is caught immediately.
+Any truthy `rawOpenRouterOverrides.stream` is overwritten (`STREAMING_OVERRIDE_IGNORED_FOR_RUN`). Nested `advisor.stream` is forced off (`ADVISOR_STREAMING_IGNORED_FOR_RUN`).
 
-The reserved streaming entrypoint is:
+### `executeStreamingChat()` — streaming only
 
 ```ts
-for await (const event of runtime.executeStreamingChat(request)) {
-  // token deltas / stream events (not implemented yet)
+for await (const event of runtime.executeStreamingChat({
+  model: "openai/gpt-5.2",
+  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);
+  }
 }
 ```
 
-Today, `executeStreamingChat()` throws `STREAMING_NOT_IMPLEMENTED`. Treat this package as a non-streaming runtime until that method is implemented.
+- 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? | Status |
+| Method | Streaming? | Notes |
 | --- | --- | --- |
-| `runtime.run(request)` | No | Supported |
-| `runtime.executeStreamingChat(request)` | Yes (future) | Throws `STREAMING_NOT_IMPLEMENTED` |
+| `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

@@ -950,11 +950,14 @@ function compileRuntimeRequest(request, defaults, options = { apiKey: "" }, cont
   };
 }
 function enforceStreamingPolicyForRun(body, warnings, context) {
-  if (context.streaming) return;
+  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.executeStreamingChat() when streaming is implemented.",
+      message: "runtime.run() is non-streaming. Use runtime.executeStreamingChat() for streaming.",
       details: { ignoredStreamValue: body.stream }
     });
   }
@@ -1357,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* executeStreamingChatNotImplemented() {
-  throw new RuntimeConfigError(
-    "STREAMING_NOT_IMPLEMENTED",
-    "executeStreamingChat() is reserved and not implemented yet. 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
@@ -1403,13 +1727,8 @@ function createOpenRouterRuntime(options) {
       }
     },
     executeStreamingChat(request) {
-      resolvedOptions.logger?.warn?.("runtime.executeStreamingChat.called", {
-        requestId: request.id,
-        streaming: true,
-        entrypoint: "executeStreamingChat",
-        implemented: false
-      });
-      return executeStreamingChatNotImplemented();
+      const requestWithId = { ...request, id: request.id ?? createRuntimeId() };
+      return executeStreamingChat(requestWithId, context);
     }
   };
   function errorResponse(request, error) {