@frockbot/provider-openai-compatible 0.3.13 → 0.3.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/provider-openai-compatible",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "private": false,
   "type": "module",
   "exports": {
@@ -11,8 +11,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-contracts": "0.3.13",
-    "@frockbot/plugin-models": "0.3.13",
+    "@frockbot/kernel-contracts": "0.3.15",
+    "@frockbot/plugin-models": "0.3.15",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/deadlines.test.ts

@@ -7,6 +7,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
+  ModelProviderFailureError,
   ModelRequestDeadlineError,
   type NormalizedModelRequest,
 } from "@frockbot/kernel-contracts";
@@ -86,8 +87,10 @@ describe("a model request that produces nothing", () => {
       () => undefined,
       (error: unknown) => error,
     );
-    expect(failure).toBeInstanceOf(ModelRequestDeadlineError);
-    expect((failure as ModelRequestDeadlineError).phase).toBe("first-byte");
+    expect(failure).toBeInstanceOf(ModelProviderFailureError);
+    expect((failure as ModelProviderFailureError).classification).toBe(
+      "transient",
+    );
     expect((failure as Error).message).toBe(
       MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
     );

package/src/index.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { type NormalizedModelRequest } from "@frockbot/kernel-contracts";
+import {
+  ModelProviderFailureError,
+  type NormalizedModelRequest,
+} from "@frockbot/kernel-contracts";
 import { LlmRegistry } from "@frockbot/plugin-models";
 import { Context } from "cordis";
-import { OpenAICompatibleProvider, requestToWire } from "./index.js";
+import {
+  OpenAICompatibleProvider,
+  requestToWire,
+  retryAfterMillisecondsV1,
+} from "./index.js";
 
 const request: NormalizedModelRequest = {
   requestId: "request-1",
@@ -251,11 +258,29 @@ describe("OpenAICompatibleProvider", () => {
     await root.fiber.dispose();
   });
 
-  test("redacts provider response bodies from HTTP errors", async () => {
+  test.each([
+    [400, "permanent"],
+    [401, "permanent"],
+    [403, "permanent"],
+    [404, "permanent"],
+    [413, "permanent"],
+    [429, "transient"],
+    [500, "transient"],
+    [503, "transient"],
+    [418, "unknown"],
+  ] as const)("classifies HTTP %i as %s", async (status, classification) => {
     const provider = new OpenAICompatibleProvider({
       baseUrl: "https://models.example/v1",
       fetch: () =>
-        Promise.resolve(new Response("bad credentials", { status: 401 })),
+        Promise.resolve(
+          Response.json(
+            { error: { message: "provider reason", code: "provider_code" } },
+            {
+              status,
+              headers: status === 429 ? { "retry-after": "3" } : {},
+            },
+          ),
+        ),
     });
 
     let failure: unknown;
@@ -269,12 +294,71 @@ describe("OpenAICompatibleProvider", () => {
     } catch (error) {
       failure = error;
     }
-    expect(failure instanceof Error ? failure.message : "").toBe(
-      "Model request failed (401)",
+    expect(failure).toBeInstanceOf(ModelProviderFailureError);
+    expect((failure as ModelProviderFailureError).classification).toBe(
+      classification,
+    );
+    expect((failure as ModelProviderFailureError).providerReason).toContain(
+      "provider reason",
+    );
+    expect((failure as ModelProviderFailureError).retryAfterMs).toBe(
+      status === 429 ? 3_000 : undefined,
     );
   });
+
+  test("classifies content policy and network reset shapes", async () => {
+    const content = new OpenAICompatibleProvider({
+      baseUrl: "https://models.example/v1",
+      fetch: () =>
+        Promise.resolve(
+          Response.json(
+            {
+              error: {
+                message: "blocked",
+                code: "content_policy_violation",
+              },
+            },
+            { status: 422 },
+          ),
+        ),
+    });
+    const reset = new OpenAICompatibleProvider({
+      baseUrl: "https://models.example/v1",
+      fetch: () => Promise.reject(new TypeError("socket reset")),
+    });
+    for (const [provider, classification] of [
+      [content, "permanent"],
+      [reset, "transient"],
+    ] as const) {
+      const failure = await collectFailure(provider);
+      expect((failure as ModelProviderFailureError).classification).toBe(
+        classification,
+      );
+    }
+  });
+
+  test("parses both Retry-After forms", () => {
+    expect(retryAfterMillisecondsV1("1.5", 0)).toBe(1_500);
+    expect(
+      retryAfterMillisecondsV1("Thu, 01 Jan 1970 00:00:05 GMT", 2_000),
+    ).toBe(3_000);
+  });
 });
 
+async function collectFailure(provider: OpenAICompatibleProvider) {
+  try {
+    for await (const event of provider.stream(
+      request,
+      new AbortController().signal,
+    )) {
+      void event;
+    }
+  } catch (error) {
+    return error;
+  }
+  throw new Error("provider did not fail");
+}
+
 // An image a tool produced, on the wire.
 //
 // Two behaviours, and the difference between them has to be visible in the

package/src/index.ts

@@ -1,10 +1,13 @@
 import {
+  boundedModelProviderReasonV1,
   type LlmMessage,
   type LlmProvider,
   type LlmStreamEvent,
   MODEL_REQUEST_DEADLINES_V1,
   type ModelRequestDeadlinesV1,
   ModelRequestDeadlineError,
+  ModelProviderFailureError,
+  type ModelProviderFailureClassV1,
   type NormalizedModelRequest,
 } from "@frockbot/kernel-contracts";
 import type { Plugin } from "cordis";
@@ -17,13 +20,112 @@ export type FetchLike = (
   init?: RequestInit,
 ) => Promise<Response>;
 
-export class OpenAICompatibleHttpError extends Error {
-  constructor(readonly status: number) {
-    super(`Model request failed (${status})`);
+export class OpenAICompatibleHttpError extends ModelProviderFailureError {
+  constructor(
+    readonly status: number,
+    reason = `Model request failed (${status})`,
+    retryAfterMs?: number,
+    errorCode?: string,
+  ) {
+    super({
+      classification: classifyOpenAICompatibleFailureV1(status, errorCode),
+      reason,
+      ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    });
     this.name = "OpenAICompatibleHttpError";
   }
 }
 
+const CONTENT_POLICY_CODES = new Set([
+  "content_filter",
+  "content_policy_violation",
+  "moderation_blocked",
+  "safety_violation",
+]);
+
+export function classifyOpenAICompatibleFailureV1(
+  status: number,
+  errorCode?: string,
+): ModelProviderFailureClassV1 {
+  if (errorCode && CONTENT_POLICY_CODES.has(errorCode.toLowerCase())) {
+    return "permanent";
+  }
+  if (status === 408 || status === 429 || status >= 500) return "transient";
+  if ([400, 401, 403, 404, 413].includes(status)) return "permanent";
+  return "unknown";
+}
+
+export function retryAfterMillisecondsV1(
+  value: string | null,
+  now = Date.now(),
+): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.ceil(seconds * 1000);
+  }
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - now) : undefined;
+}
+
+function openAIErrorDetailV1(text: string): {
+  reason?: string;
+  code?: string;
+} {
+  if (!text.trim()) return {};
+  try {
+    const payload = JSON.parse(text) as unknown;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      return { reason: text };
+    }
+    const error = (payload as Record<string, unknown>).error;
+    if (typeof error === "string") return { reason: error };
+    if (!error || typeof error !== "object" || Array.isArray(error)) return {};
+    const record = error as Record<string, unknown>;
+    return {
+      ...(typeof record.message === "string" ? { reason: record.message } : {}),
+      ...(typeof record.code === "string"
+        ? { code: record.code }
+        : typeof record.type === "string"
+          ? { code: record.type }
+          : {}),
+    };
+  } catch {
+    return { reason: text };
+  }
+}
+
+function networkFailureV1(error: unknown): ModelProviderFailureError {
+  const message = error instanceof Error ? error.message : String(error);
+  const name = error instanceof Error ? error.name : "";
+  const transient =
+    error instanceof TypeError ||
+    ["NetworkError", "TimeoutError"].includes(name) ||
+    /\b(?:ECONNRESET|ECONNREFUSED|EPIPE|ETIMEDOUT|network|socket|gateway timeout)\b/i.test(
+      message,
+    );
+  return new ModelProviderFailureError({
+    classification: transient ? "transient" : "unknown",
+    reason: message,
+  });
+}
+
+async function httpFailureV1(response: Response): Promise<never> {
+  const text = (await response.text().catch(() => "")).slice(0, 2_000);
+  const detail = openAIErrorDetailV1(text);
+  const reason = boundedModelProviderReasonV1(
+    detail.reason
+      ? `Model request failed (${response.status}): ${detail.reason}`
+      : `Model request failed (${response.status})`,
+  );
+  throw new OpenAICompatibleHttpError(
+    response.status,
+    reason,
+    retryAfterMillisecondsV1(response.headers.get("retry-after")),
+    detail.code,
+  );
+}
+
 export interface OpenAICompatibleConfig {
   baseUrl: string;
   apiKey?: string;
@@ -548,37 +650,50 @@ export class OpenAICompatibleProvider implements LlmProvider {
     // request and then went quiet held the Turn open for as long as the socket
     // stayed up — seventeen minutes, in the incident this exists for, with
     // nothing on the person's screen the whole time.
-    yield* streamWithModelRequestDeadlinesV1(
-      async (deadlineSignal) => {
-        const response = await fetcher(
-          `${this.config.baseUrl}/chat/completions`,
-          {
-            method: "POST",
-            headers,
-            body: JSON.stringify(
-              requestToWire(request, {
-                ...(this.config.acceptsImages === undefined
-                  ? {}
-                  : { acceptsImages: this.config.acceptsImages }),
-              }),
-            ),
-            signal: deadlineSignal,
-          },
-        );
-        if (!response.ok) {
-          await response.body?.cancel();
-          throw new OpenAICompatibleHttpError(response.status);
-        }
-        if (!response.body)
-          throw new Error("Model response did not include a stream");
-        return response.body;
-      },
-      signal,
-      {
-        ...(this.config.deadlines ? { deadlines: this.config.deadlines } : {}),
-        ...(this.config.schedule ? { schedule: this.config.schedule } : {}),
-      },
-    );
+    try {
+      yield* streamWithModelRequestDeadlinesV1(
+        async (deadlineSignal) => {
+          const response = await fetcher(
+            `${this.config.baseUrl}/chat/completions`,
+            {
+              method: "POST",
+              headers,
+              body: JSON.stringify(
+                requestToWire(request, {
+                  ...(this.config.acceptsImages === undefined
+                    ? {}
+                    : { acceptsImages: this.config.acceptsImages }),
+                }),
+              ),
+              signal: deadlineSignal,
+            },
+          );
+          if (!response.ok) await httpFailureV1(response);
+          if (!response.body)
+            throw new Error("Model response did not include a stream");
+          return response.body;
+        },
+        signal,
+        {
+          ...(this.config.deadlines
+            ? { deadlines: this.config.deadlines }
+            : {}),
+          ...(this.config.schedule ? { schedule: this.config.schedule } : {}),
+        },
+      );
+    } catch (error) {
+      if (signal.aborted || error instanceof ModelProviderFailureError) {
+        throw error;
+      }
+      if (error instanceof ModelRequestDeadlineError) {
+        if (error.phase === "idle") throw error;
+        throw new ModelProviderFailureError({
+          classification: "transient",
+          reason: error.message,
+        });
+      }
+      throw networkFailureV1(error);
+    }
   }
 }