@x12i/openrouter-runtime 1.0.6 → 1.1.0

package/dist/index.d.cts

@@ -4,7 +4,8 @@ type ToolMode = "disabled" | "allowed" | "required";
 interface OpenRouterRuntime {
     run(request: RuntimeRequest): Promise<RuntimeResponse>;
     /**
-     * Streaming chat entrypoint. Separate from `run()` by design.
+     * Explicit streaming chat API. Separate from `run()` by design — never an argument, never the default.
+     * Always sends OpenRouter Chat Completions with `stream: true` and yields typed SSE events.
      * The old `stream()` name was removed so mistaken/old clients break loudly.
      */
     executeStreamingChat(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
@@ -364,9 +365,60 @@ interface RuntimePolicyViolation {
     details?: unknown;
 }
 interface RuntimeStreamEvent {
-    type: string;
+    type: RuntimeStreamEventType;
+    requestId: string;
     data?: unknown;
 }
+type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+interface RuntimeStreamStartEvent extends RuntimeStreamEvent {
+    type: "stream.start";
+    data: {
+        model: string;
+        apiMode: "chat";
+        entrypoint: "executeStreamingChat";
+    };
+}
+interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.text.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.tool_call.delta";
+    data: {
+        index: number;
+        id?: string;
+        name?: string;
+        argumentsDelta?: string;
+    };
+}
+interface RuntimeStreamUsageEvent extends RuntimeStreamEvent {
+    type: "stream.usage";
+    data: {
+        usage: RuntimeUsage;
+    };
+}
+interface RuntimeStreamWarningEvent extends RuntimeStreamEvent {
+    type: "stream.warning";
+    data: {
+        warning: RuntimeWarning;
+    };
+}
+interface RuntimeStreamErrorEvent extends RuntimeStreamEvent {
+    type: "stream.error";
+    data: {
+        error: RuntimeError;
+    };
+}
+interface RuntimeStreamDoneEvent extends RuntimeStreamEvent {
+    type: "stream.done";
+    data: {
+        text: string;
+        finishReason?: string;
+        model: string;
+    };
+}
 type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | unknown;
 
 declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
@@ -414,4 +466,4 @@ declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy):
 declare function isRuntimeLoggingEnabled(env?: Record<string, string | undefined> | undefined): boolean;
 declare function createConsoleLogger(): RuntimeLogger;
 
-export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };
+export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, type RuntimeStreamStartEvent, type RuntimeStreamTextDeltaEvent, type RuntimeStreamToolCallDeltaEvent, type RuntimeStreamUsageEvent, type RuntimeStreamWarningEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };

package/dist/index.d.ts

@@ -4,7 +4,8 @@ type ToolMode = "disabled" | "allowed" | "required";
 interface OpenRouterRuntime {
     run(request: RuntimeRequest): Promise<RuntimeResponse>;
     /**
-     * Streaming chat entrypoint. Separate from `run()` by design.
+     * Explicit streaming chat API. Separate from `run()` by design — never an argument, never the default.
+     * Always sends OpenRouter Chat Completions with `stream: true` and yields typed SSE events.
      * The old `stream()` name was removed so mistaken/old clients break loudly.
      */
     executeStreamingChat(request: RuntimeRequest): AsyncIterable<RuntimeStreamEvent>;
@@ -364,9 +365,60 @@ interface RuntimePolicyViolation {
     details?: unknown;
 }
 interface RuntimeStreamEvent {
-    type: string;
+    type: RuntimeStreamEventType;
+    requestId: string;
     data?: unknown;
 }
+type RuntimeStreamEventType = "stream.start" | "stream.text.delta" | "stream.tool_call.delta" | "stream.usage" | "stream.warning" | "stream.error" | "stream.done";
+interface RuntimeStreamStartEvent extends RuntimeStreamEvent {
+    type: "stream.start";
+    data: {
+        model: string;
+        apiMode: "chat";
+        entrypoint: "executeStreamingChat";
+    };
+}
+interface RuntimeStreamTextDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.text.delta";
+    data: {
+        text: string;
+    };
+}
+interface RuntimeStreamToolCallDeltaEvent extends RuntimeStreamEvent {
+    type: "stream.tool_call.delta";
+    data: {
+        index: number;
+        id?: string;
+        name?: string;
+        argumentsDelta?: string;
+    };
+}
+interface RuntimeStreamUsageEvent extends RuntimeStreamEvent {
+    type: "stream.usage";
+    data: {
+        usage: RuntimeUsage;
+    };
+}
+interface RuntimeStreamWarningEvent extends RuntimeStreamEvent {
+    type: "stream.warning";
+    data: {
+        warning: RuntimeWarning;
+    };
+}
+interface RuntimeStreamErrorEvent extends RuntimeStreamEvent {
+    type: "stream.error";
+    data: {
+        error: RuntimeError;
+    };
+}
+interface RuntimeStreamDoneEvent extends RuntimeStreamEvent {
+    type: "stream.done";
+    data: {
+        text: string;
+        finishReason?: string;
+        model: string;
+    };
+}
 type RuntimePatchApplier = (patch: RuntimePatchProposal) => Promise<unknown> | unknown;
 
 declare function createOpenRouterRuntime(options: OpenRouterRuntimeOptions): OpenRouterRuntime;
@@ -414,4 +466,4 @@ declare function buildOpenRouterServerTools(policy?: RuntimeServerToolsPolicy):
 declare function isRuntimeLoggingEnabled(env?: Record<string, string | undefined> | undefined): boolean;
 declare function createConsoleLogger(): RuntimeLogger;
 
-export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };
+export { type AdvisorPolicy, type ApplyPatchPolicy, type CompiledOpenRouterRequest, type DatetimePolicy, type FusionPolicy, type ImageGenerationPolicy, OpenRouterHttpError, type OpenRouterRuntime, type OpenRouterRuntimeOptions, type RuntimeCitation, RuntimeConfigError, type RuntimeDefaults, type RuntimeError, type RuntimeFunctionToolDefinition, type RuntimeGeneratedImage, type RuntimeLogger, type RuntimeMessage, type RuntimePatchProposal, type RuntimePolicyViolation, type RuntimeRequest, type RuntimeResponse, type RuntimeServerToolsPolicy, type RuntimeStreamDoneEvent, type RuntimeStreamErrorEvent, type RuntimeStreamEvent, type RuntimeStreamEventType, type RuntimeStreamStartEvent, type RuntimeStreamTextDeltaEvent, type RuntimeStreamToolCallDeltaEvent, type RuntimeStreamUsageEvent, type RuntimeStreamWarningEvent, type RuntimeToolExecutor, type RuntimeToolUsage, type RuntimeUsage, type RuntimeWarning, type ServerToolKey, type ServerToolUsage, type SubagentPolicy, type WebFetchPolicy, type WebSearchPolicy, buildOpenRouterServerTools, compileRuntimeRequest, createConsoleLogger, createOpenRouterRuntime, isRuntimeLoggingEnabled };

package/dist/index.js

@@ -918,11 +918,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 }
     });
   }
@@ -1325,12 +1328,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
@@ -1371,13 +1695,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) {