@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/providers/openai/__tests__/api-error-normalization.test.ts

@@ -0,0 +1,321 @@
+import { describe, expect, test } from "bun:test";
+
+import type OpenAI from "openai";
+
+import {
+  captureRawErrorBodyFetch,
+  formatNormalizedOpenAIAPIError,
+  normalizeOpenAIAPIError,
+} from "../api-error-normalization.js";
+
+/**
+ * Stand-in for an `OpenAI.APIError`. The real SDK constructor stringifies the
+ * body into `.message` and renders unparseable bodies as "(no body)" — exactly
+ * the lossy behavior we work around by capturing the raw body separately — so
+ * the tests pass the raw body explicitly the way the provider does.
+ */
+function apiError(
+  status: number,
+  opts: { message?: string; sdkBody?: unknown; headers?: Headers } = {},
+): InstanceType<typeof OpenAI.APIError> {
+  return {
+    status,
+    message: opts.message ?? `${status} status code (no body)`,
+    headers: opts.headers ?? new Headers(),
+    error: opts.sdkBody,
+  } as unknown as InstanceType<typeof OpenAI.APIError>;
+}
+
+describe("normalizeOpenAIAPIError", () => {
+  test("surfaces Django {detail} bodies the SDK would drop", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400),
+      JSON.stringify({
+        detail: "Model 'MiniMax-M3' is not yet supported on Vellum.",
+      }),
+    );
+    expect(n.message).toBe(
+      "Model 'MiniMax-M3' is not yet supported on Vellum.",
+    );
+    expect(formatNormalizedOpenAIAPIError("Together AI", 400, n)).toBe(
+      "Together AI API error (400): Model 'MiniMax-M3' is not yet supported on Vellum.",
+    );
+  });
+
+  test("extracts OpenAI-shaped error metadata", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(401),
+      JSON.stringify({
+        error: {
+          message: "Invalid API key provided",
+          code: "invalid_api_key",
+          type: "invalid_request_error",
+          param: "api_key",
+        },
+      }),
+    );
+    expect(n).toMatchObject({
+      message: "Invalid API key provided",
+      apiErrorCode: "invalid_api_key",
+      apiErrorType: "invalid_request_error",
+      apiErrorParam: "api_key",
+    });
+    expect(formatNormalizedOpenAIAPIError("OpenAI", 401, n)).toContain(
+      "code=invalid_api_key; type=invalid_request_error; param=api_key",
+    );
+  });
+
+  test("promotes OpenRouter metadata.raw over the generic wrapper message", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400, {
+        sdkBody: {
+          error: {
+            code: 400,
+            message: "Provider returned error",
+            metadata: {
+              raw: "messages.4: tool_use_id must reference a prior tool_use block",
+              provider_name: "Anthropic",
+            },
+          },
+        },
+      }),
+    );
+    expect(n.message).toBe(
+      "messages.4: tool_use_id must reference a prior tool_use block",
+    );
+    expect(n.detail).toBe("provider=Anthropic");
+    expect(n.apiErrorCode).toBe("400");
+  });
+
+  test("prefers the captured raw body over the SDK's parsed error", () => {
+    // SDK collapsed the body; raw body still has the real detail.
+    const n = normalizeOpenAIAPIError(
+      apiError(400, { sdkBody: {} }),
+      JSON.stringify({ detail: "managed proxy rejected model" }),
+    );
+    expect(n.message).toBe("managed proxy rejected model");
+  });
+
+  test("falls back to the SDK-parsed error when the captured JSON was truncated", () => {
+    // encodeCapturedBody slices oversized bodies, which can leave an invalid
+    // JSON prefix. Rather than render that fragment (and lose metadata), fall
+    // back to the body the SDK already parsed from the full response.
+    const truncated =
+      '{"error":{"message":"too long","code":"context_length_exceeded","type":"invalid_request_error","param":"messag';
+    const n = normalizeOpenAIAPIError(
+      apiError(400, {
+        sdkBody: {
+          error: {
+            message: "too long",
+            code: "context_length_exceeded",
+            type: "invalid_request_error",
+            param: "messages",
+          },
+        },
+      }),
+      truncated,
+    );
+    expect(n.message).toBe("too long");
+    expect(n.apiErrorCode).toBe("context_length_exceeded");
+    expect(n.apiErrorType).toBe("invalid_request_error");
+    expect(n.apiErrorParam).toBe("messages");
+  });
+
+  test("uses a plain-text raw body when JSON parsing fails", () => {
+    const n = normalizeOpenAIAPIError(apiError(502), "upstream timeout");
+    expect(n.message).toBe("upstream timeout");
+  });
+
+  test("reads the upstream request id from headers", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400, { headers: new Headers({ "x-request-id": "req_abc123" }) }),
+      JSON.stringify({ detail: "bad request" }),
+    );
+    expect(n.requestId).toBe("req_abc123");
+    expect(formatNormalizedOpenAIAPIError("OpenAI", 400, n)).toContain(
+      "request_id=req_abc123",
+    );
+  });
+
+  test("falls back to x-openrouter-request-id", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400, {
+        headers: new Headers({ "x-openrouter-request-id": "gen-or-xyz" }),
+      }),
+      JSON.stringify({ detail: "bad request" }),
+    );
+    expect(n.requestId).toBe("gen-or-xyz");
+  });
+
+  test("truncates very long details with an ellipsis", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400),
+      JSON.stringify({ detail: "X".repeat(5000) }),
+    );
+    expect(n.message.length).toBeLessThanOrEqual(2001);
+    expect(n.message.endsWith("…")).toBe(true);
+  });
+
+  test("degrades to the status-stripped SDK message when there is no body", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(500, { message: "500 Internal Server Error" }),
+    );
+    expect(n.message).toBe("Internal Server Error");
+  });
+
+  test("falls back to 'Request failed' for the SDK '(no body)' sentinel", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(500, { message: "500 status code (no body)" }),
+    );
+    expect(n.message).toBe("Request failed");
+  });
+
+  test("surfaces the verbatim captured body as rawBody for downstream persistence", () => {
+    const raw = JSON.stringify({ detail: "model gone", extra: "kept" });
+    const n = normalizeOpenAIAPIError(apiError(400), raw);
+    // Extracted message is the clean detail...
+    expect(n.message).toBe("model gone");
+    // ...but the raw body is carried verbatim so the Raw tab can show it all.
+    expect(n.rawBody).toBe(raw);
+  });
+
+  test("keeps sibling code/type/param when the body is {error: <string>}", () => {
+    const n = normalizeOpenAIAPIError(
+      apiError(400),
+      JSON.stringify({
+        error: "bad request",
+        code: "context_length_exceeded",
+        type: "invalid_request_error",
+      }),
+    );
+    expect(n.message).toBe("bad request");
+    expect(n.apiErrorCode).toBe("context_length_exceeded");
+    expect(n.apiErrorType).toBe("invalid_request_error");
+  });
+});
+
+describe("captureRawErrorBodyFetch", () => {
+  // The fetch wrapper stashes the dropped body in a WeakMap keyed by the
+  // response's headers object — which the SDK passes through to
+  // APIError.headers — so normalize() recovers it with no explicit rawBody
+  // argument and nothing is written to a (loggable) header.
+  function fakeFetch(body: string, status: number): typeof globalThis.fetch {
+    return (async () =>
+      new Response(body, { status })) as unknown as typeof globalThis.fetch;
+  }
+
+  function errFor(res: Response, status: number) {
+    return {
+      status,
+      message: `${status} status code (no body)`,
+      headers: res.headers,
+      error: undefined,
+    } as unknown as InstanceType<typeof import("openai").APIError>;
+  }
+
+  test("recovers a non-2xx body into normalize() via the headers WeakMap", async () => {
+    const original = globalThis.fetch;
+    globalThis.fetch = fakeFetch(JSON.stringify({ detail: "model gone" }), 400);
+    try {
+      const res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      // No rawBody arg: normalize recovers the body keyed by res.headers alone.
+      expect(normalizeOpenAIAPIError(errFor(res, 400)).message).toBe(
+        "model gone",
+      );
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
+
+  test("never writes the captured body to a header", async () => {
+    const original = globalThis.fetch;
+    globalThis.fetch = fakeFetch(JSON.stringify({ detail: "secret" }), 400);
+    try {
+      const res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      const headerNames = [...res.headers.keys()];
+      expect(headerNames.some((h) => h.includes("vellum"))).toBe(false);
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
+
+  test("passes OK responses through untouched", async () => {
+    const original = globalThis.fetch;
+    globalThis.fetch = fakeFetch("ok", 200);
+    try {
+      const res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      expect(await res.text()).toBe("ok");
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
+
+  test("recovers (truncated) detail for oversized terminal errors", async () => {
+    const big = "y".repeat(40_000);
+    const original = globalThis.fetch;
+    globalThis.fetch = fakeFetch(JSON.stringify({ detail: big }), 400);
+    try {
+      const res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      const n = normalizeOpenAIAPIError(errFor(res, 400));
+      // The captured body is bounded (16 KB) and the message re-truncated to
+      // MAX_DETAIL_CHARS, so an oversized error can't balloon either.
+      expect(n.message).toContain("yyyy");
+      expect(n.message.length).toBeLessThanOrEqual(2001);
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
+
+  test("does not drain SDK-retryable bodies (408/409/429/5xx)", async () => {
+    const original = globalThis.fetch;
+    // Mirror the full SDK retry predicate, not just 429/5xx.
+    for (const status of [408, 409, 429, 500, 503]) {
+      globalThis.fetch = fakeFetch(
+        JSON.stringify({ detail: "retry me" }),
+        status,
+      );
+      try {
+        const res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+        // Pass-through: nothing captured, and the body is still readable by the
+        // SDK (we never consumed it).
+        expect(normalizeOpenAIAPIError(errFor(res, status)).message).not.toBe(
+          "retry me",
+        );
+        expect(res.status).toBe(status);
+        expect(await res.text()).toContain("retry me");
+      } finally {
+        globalThis.fetch = original;
+      }
+    }
+  });
+
+  test("honors the x-should-retry header override", async () => {
+    const original = globalThis.fetch;
+    const withHeader = (
+      status: number,
+      value: string,
+    ): typeof globalThis.fetch =>
+      (async () =>
+        new Response(JSON.stringify({ detail: "header says so" }), {
+          status,
+          headers: { "x-should-retry": value },
+        })) as unknown as typeof globalThis.fetch;
+    try {
+      // x-should-retry:true on an otherwise-terminal 400 → SDK retries → skip.
+      globalThis.fetch = withHeader(400, "true");
+      let res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      expect(normalizeOpenAIAPIError(errFor(res, 400)).message).not.toBe(
+        "header says so",
+      );
+
+      // x-should-retry:false on a 500 → SDK won't retry → capture it.
+      globalThis.fetch = withHeader(500, "false");
+      res = await captureRawErrorBodyFetch("https://x/v1/chat", {});
+      expect(normalizeOpenAIAPIError(errFor(res, 500)).message).toBe(
+        "header says so",
+      );
+    } finally {
+      globalThis.fetch = original;
+    }
+  });
+});

package/src/providers/openai/api-error-normalization.ts

@@ -0,0 +1,270 @@
+import type OpenAI from "openai";
+
+/**
+ * Normalized view of an OpenAI-compatible `APIError`. The SDK reads
+ * `error.message` and renders bodies it can't parse as "(no body)", so
+ * Django `{"detail": "..."}` payloads from the managed runtime proxy and
+ * OpenRouter's nested `error.metadata.raw` get dropped. We capture the raw
+ * non-2xx body in a `fetch` wrapper and reconstruct the useful fields here.
+ */
+export interface NormalizedOpenAIAPIError {
+  message: string;
+  detail?: string;
+  requestId?: string;
+  apiErrorCode?: string;
+  apiErrorType?: string;
+  apiErrorParam?: string;
+  /**
+   * The captured raw upstream non-2xx body, verbatim (possibly truncated to
+   * MAX_CAPTURED_BODY_CHARS). Carried so callers can persist the actual
+   * provider payload for the inspector's Raw tab instead of only the
+   * extracted fields. Absent for retryable (429/5xx) errors, whose bodies
+   * `captureRawErrorBodyFetch` intentionally doesn't drain.
+   */
+  rawBody?: string;
+}
+
+const MAX_DETAIL_CHARS = 2000;
+const REQUEST_ID_HEADERS = [
+  "x-request-id",
+  "x-openrouter-request-id",
+  "openai-request-id",
+  "x-amzn-requestid",
+] as const;
+
+// The OpenAI SDK keeps only the `.error` key of a parsed JSON error body and
+// discards the rest, so a Django-proxy `{ "detail": … }` payload never reaches
+// the thrown APIError. captureRawErrorBodyFetch stashes the raw body in a
+// WeakMap keyed by the response's headers object — which the SDK passes through
+// to `APIError.headers` by reference — so it stays correlated to its own
+// request, with no shared provider state for concurrent calls to clobber. A
+// WeakMap (rather than a synthetic header) keeps the body out of the SDK's
+// debug header logging and is reclaimed automatically with the response.
+const capturedErrorBodies = new WeakMap<object, string>();
+// Bound the stored body so a huge HTML error page can't balloon memory; the
+// message is re-truncated to MAX_DETAIL_CHARS downstream anyway.
+const MAX_CAPTURED_BODY_CHARS = 16_384;
+
+/**
+ * SDK `fetch` option that captures non-2xx response bodies. Install via the
+ * OpenAI client `fetch` option; safe to share across requests and instances
+ * because the captured body is keyed per-response in a WeakMap, not stored on
+ * any shared field.
+ */
+export const captureRawErrorBodyFetch = async (
+  url: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> => {
+  const res = await globalThis.fetch(url, init);
+  if (res.ok) return res;
+  // Don't drain bodies the SDK will retry: reading a large or slow upstream
+  // error page on every attempt would delay those retries and buffer the whole
+  // body. We still capture terminal (non-retryable) errors — that's where the
+  // actionable upstream detail lives (unsupported model, invalid key, malformed
+  // request, etc.).
+  if (sdkWillRetry(res)) return res;
+  // clone() so reading the body leaves the SDK's own read of `res` intact.
+  const body = await res
+    .clone()
+    .text()
+    .catch(() => undefined);
+  if (!body) return res;
+  capturedErrorBodies.set(
+    res.headers,
+    body.length > MAX_CAPTURED_BODY_CHARS
+      ? body.slice(0, MAX_CAPTURED_BODY_CHARS)
+      : body,
+  );
+  return res;
+};
+
+/**
+ * Mirror the OpenAI SDK's `shouldRetry` predicate so this wrapper never drains
+ * a body the SDK is about to retry. The SDK retries more than 429/5xx: an
+ * explicit `x-should-retry` header (which also overrides 429/5xx to *not*
+ * retry), plus 408 (request timeout) and 409 (lock timeout). Keep in sync with
+ * `openai/client.js` `shouldRetry`.
+ */
+function sdkWillRetry(res: Response): boolean {
+  const shouldRetryHeader = res.headers.get("x-should-retry");
+  if (shouldRetryHeader === "true") return true;
+  if (shouldRetryHeader === "false") return false;
+  return (
+    res.status === 408 ||
+    res.status === 409 ||
+    res.status === 429 ||
+    res.status >= 500
+  );
+}
+
+export function normalizeOpenAIAPIError(
+  error: InstanceType<typeof OpenAI.APIError>,
+  rawBody: string | undefined = readCapturedErrorBody(error.headers),
+): NormalizedOpenAIAPIError {
+  // Prefer the captured raw body (intact upstream payload) over the SDK's
+  // already-parsed `error.error`, which may have collapsed the detail. But if
+  // the captured body didn't parse as a JSON object — e.g. it was truncated
+  // past MAX_CAPTURED_BODY_CHARS into an invalid prefix — fall back to the
+  // SDK's parsed object so we don't drop code/type/param it already extracted.
+  const parsedRaw = parseBody(rawBody);
+  const sdkError = (error as { error?: unknown }).error;
+  const parsed = asRecord(parsedRaw) ?? sdkError ?? parsedRaw;
+  const body = extractBody(parsed);
+
+  const message =
+    body.message ||
+    stripLeadingStatus(error.message ?? "", error.status) ||
+    "Request failed";
+
+  const out: NormalizedOpenAIAPIError = { message };
+  if (body.detail && body.detail !== message) out.detail = body.detail;
+  const code = body.apiErrorCode ?? scalar((error as { code?: unknown }).code);
+  const type = body.apiErrorType ?? scalar((error as { type?: unknown }).type);
+  const param =
+    body.apiErrorParam ?? scalar((error as { param?: unknown }).param);
+  if (code) out.apiErrorCode = code;
+  if (type) out.apiErrorType = type;
+  if (param) out.apiErrorParam = param;
+  const requestId = readHeader(error.headers);
+  if (requestId) out.requestId = requestId;
+  if (rawBody) out.rawBody = rawBody;
+  return out;
+}
+
+export function formatNormalizedOpenAIAPIError(
+  providerLabel: string,
+  status: number | undefined,
+  n: NormalizedOpenAIAPIError,
+): string {
+  const statusLabel =
+    typeof status === "number" ? String(status) : "unknown status";
+  const extras = [
+    n.detail,
+    n.apiErrorCode && `code=${n.apiErrorCode}`,
+    n.apiErrorType && `type=${n.apiErrorType}`,
+    n.apiErrorParam && `param=${n.apiErrorParam}`,
+    n.requestId && `request_id=${n.requestId}`,
+  ].filter((v): v is string => Boolean(v));
+  const suffix = extras.length > 0 ? ` [${extras.join("; ")}]` : "";
+  return `${providerLabel} API error (${statusLabel}): ${n.message}${suffix}`;
+}
+
+interface BodyDetails {
+  message?: string;
+  detail?: string;
+  apiErrorCode?: string;
+  apiErrorType?: string;
+  apiErrorParam?: string;
+}
+
+function extractBody(body: unknown): BodyDetails {
+  if (typeof body === "string") return { message: trunc(body.trim()) };
+  const rec = asRecord(body);
+  if (!rec) return {};
+
+  // OpenAI/OpenRouter nest under `error`; Django puts `detail` at the top.
+  // A plain `error: "string"` is the whole message but may still carry
+  // sibling code/type/param, so fall through to the metadata extraction below.
+  const err = asRecord(rec.error) ?? rec;
+
+  let message =
+    str(rec.error) ?? str(err.message) ?? str(err.detail) ?? str(rec.detail);
+  let detail: string | undefined;
+
+  // OpenRouter: the real downstream error lives in metadata.raw while the
+  // top-level message is a generic "Provider returned error".
+  const meta = asRecord(err.metadata);
+  const raw = str(meta?.raw);
+  const provider = str(meta?.provider_name);
+  if (raw && message && /^provider returned error$/i.test(message)) {
+    message = raw;
+  } else if (raw && raw !== message) {
+    detail = raw;
+  }
+  if (provider) {
+    detail = detail
+      ? `${detail}; provider=${provider}`
+      : `provider=${provider}`;
+  }
+
+  return {
+    ...(message ? { message: trunc(message) } : {}),
+    ...(detail ? { detail: trunc(detail) } : {}),
+    ...withScalar("apiErrorCode", err.code ?? rec.code),
+    ...withScalar("apiErrorType", err.type ?? rec.type),
+    ...withScalar("apiErrorParam", err.param ?? rec.param),
+  };
+}
+
+function parseBody(raw: string | undefined): unknown {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed; // non-JSON body (HTML error page, plain text)
+  }
+}
+
+function stripLeadingStatus(
+  message: string,
+  status: number | undefined,
+): string {
+  const trimmed = message.trim();
+  // SDK sentinel for an unparseable/empty body — carries no signal, so let the
+  // caller fall back to "Request failed" rather than surface SDK phrasing.
+  if (/^\d*\s*status code \(no body\)$/i.test(trimmed)) return "";
+  if (typeof status !== "number") return trimmed;
+  return trimmed.replace(new RegExp(`^${status}\\s+`), "").trim() || trimmed;
+}
+
+function trunc(s: string): string {
+  return s.length > MAX_DETAIL_CHARS ? `${s.slice(0, MAX_DETAIL_CHARS)}…` : s;
+}
+
+function withScalar(key: keyof BodyDetails, value: unknown): BodyDetails {
+  const s = scalar(value);
+  return s ? { [key]: s } : {};
+}
+
+function scalar(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readHeader(headers: unknown): string | undefined {
+  return readHeaderValue(headers, REQUEST_ID_HEADERS);
+}
+
+function readHeaderValue(
+  headers: unknown,
+  names: readonly string[],
+): string | undefined {
+  if (!headers) return undefined;
+  const get = (headers as { get?: unknown }).get;
+  const getter = typeof get === "function" ? get.bind(headers) : undefined;
+  for (const name of names) {
+    const raw = getter
+      ? (getter(name) as string | null)
+      : (asRecord(headers)?.[name] ?? asRecord(headers)?.[name.toLowerCase()]);
+    if (typeof raw === "string" && raw.length > 0) return raw;
+  }
+  return undefined;
+}
+
+function readCapturedErrorBody(headers: unknown): string | undefined {
+  return headers && typeof headers === "object"
+    ? capturedErrorBodies.get(headers)
+    : undefined;
+}