@vellumai/assistant 0.8.5 → 0.8.6

package/src/providers/inference/__tests__/adapter-factory-openai-compatible.test.ts

@@ -24,7 +24,6 @@ describe("openai-compatible adapter factory", () => {
       name: "my-vllm",
       provider: "openai-compatible",
       auth: { type: "api_key", credential: "cred-vllm" },
-      status: "active",
       label: "vLLM",
       baseUrl: "http://localhost:8080/v1",
       models: [{ id: "my-model" }],
@@ -52,7 +51,6 @@ describe("openai-compatible adapter factory", () => {
       name: "my-vllm",
       provider: "openai-compatible",
       auth: { type: "none" },
-      status: "active",
       label: null,
       baseUrl: "http://localhost:8080/v1",
       models: [{ id: "my-model" }],

package/src/providers/inference/__tests__/base-url-security.test.ts

@@ -7,6 +7,7 @@ import { migrateCreateProviderConnections } from "../../../memory/migrations/243
 import { migrateProviderConnectionStatusLabel } from "../../../memory/migrations/244-provider-connection-status-label.js";
 import { migrateProviderConnectionBaseUrlAndModels } from "../../../memory/migrations/250-provider-connection-base-url-and-models.js";
 import { migrateStripBaseUrlNonOpenaiCompatible } from "../../../memory/migrations/257-strip-base-url-non-openai-compatible.js";
+import { migrateDropProviderConnectionStatus } from "../../../memory/migrations/265-drop-provider-connection-status.js";
 import * as schema from "../../../memory/schema.js";
 import { providerConnections } from "../../../memory/schema/inference.js";
 import { getConnection } from "../connections.js";
@@ -22,6 +23,7 @@ function bootDb() {
   const db = createTestDb();
   migrateCreateProviderConnections(db);
   migrateProviderConnectionStatusLabel(db);
+  migrateDropProviderConnectionStatus(db);
   migrateProviderConnectionBaseUrlAndModels(db);
   return db;
 }
@@ -42,7 +44,6 @@ describe("migration 257: strip base_url from non-openai-compatible connections",
         name: "bad-anthropic",
         provider: "anthropic",
         auth: JSON.stringify({ type: "api_key", credential: "cred-abc" }),
-        status: "active",
         baseUrl: "https://evil.example.com/v1",
         createdAt: now,
         updatedAt: now,
@@ -65,7 +66,6 @@ describe("migration 257: strip base_url from non-openai-compatible connections",
         name: "good-vllm",
         provider: "openai-compatible",
         auth: JSON.stringify({ type: "api_key", credential: "cred-vllm" }),
-        status: "active",
         baseUrl: "https://my-vllm.example.com/v1",
         models: JSON.stringify([{ id: "my-model" }]),
         createdAt: now,
@@ -89,7 +89,6 @@ describe("migration 257: strip base_url from non-openai-compatible connections",
         name: "bad-openai",
         provider: "openai",
         auth: JSON.stringify({ type: "api_key", credential: "cred-abc" }),
-        status: "active",
         baseUrl: "https://evil.example.com/v1",
         createdAt: now,
         updatedAt: now,

package/src/providers/inference/__tests__/{connections-status-label.test.ts → connections-label.test.ts}

@@ -6,10 +6,10 @@ import { drizzle } from "drizzle-orm/bun-sqlite";
 import { migrateCreateProviderConnections } from "../../../memory/migrations/243-provider-connections.js";
 import { migrateProviderConnectionStatusLabel } from "../../../memory/migrations/244-provider-connection-status-label.js";
 import { migrateProviderConnectionBaseUrlAndModels } from "../../../memory/migrations/250-provider-connection-base-url-and-models.js";
+import { migrateDropProviderConnectionStatus } from "../../../memory/migrations/265-drop-provider-connection-status.js";
 import * as schema from "../../../memory/schema.js";
 import {
   createConnection,
-  disableManagedConnectionsForByokHatch,
   getConnection,
   listConnections,
   seedCanonicalConnections,
@@ -25,13 +25,17 @@ function createTestDb() {
 function bootDb() {
   const db = createTestDb();
   migrateCreateProviderConnections(db);
+  // 244 adds status + label columns. 265 drops status. This mirrors the
+  // production migration sequence so the Drizzle schema (which no longer
+  // declares status) stays consistent with the DB shape.
   migrateProviderConnectionStatusLabel(db);
+  migrateDropProviderConnectionStatus(db);
   migrateProviderConnectionBaseUrlAndModels(db);
   return db;
 }
 
-describe("connection CRUD status + label defaults", () => {
-  test("new connection without status/label gets status=active and label=null", () => {
+describe("connection CRUD label defaults", () => {
+  test("new connection without label gets label=null", () => {
     const db = bootDb();
     const result = createConnection(db, {
       name: "my-conn",
@@ -40,61 +44,38 @@ describe("connection CRUD status + label defaults", () => {
     });
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.connection.status).toBe("active");
       expect(result.connection.label).toBeNull();
     }
   });
 
-  test("createConnection passes explicit status and label", () => {
+  test("createConnection passes explicit label", () => {
     const db = bootDb();
     const result = createConnection(db, {
-      name: "disabled-conn",
+      name: "labeled-conn",
       provider: "openai",
       auth: { type: "platform" },
-      status: "disabled",
       label: "My OpenAI",
     });
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.connection.status).toBe("disabled");
       expect(result.connection.label).toBe("My OpenAI");
     }
   });
 
-  test("getConnection returns status and label from DB", () => {
+  test("getConnection returns label from DB", () => {
     const db = bootDb();
     createConnection(db, {
       name: "get-me",
       provider: "gemini",
       auth: { type: "platform" },
-      status: "disabled",
       label: "Gemini Pro",
     });
 
     const conn = getConnection(db, "get-me");
     expect(conn).not.toBeNull();
-    expect(conn!.status).toBe("disabled");
     expect(conn!.label).toBe("Gemini Pro");
   });
 
-  test("updateConnection updates status", () => {
-    const db = bootDb();
-    createConnection(db, {
-      name: "toggle-me",
-      provider: "anthropic",
-      auth: { type: "platform" },
-    });
-
-    const result = updateConnection(db, "toggle-me", {
-      auth: { type: "platform" },
-      status: "disabled",
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.connection.status).toBe("disabled");
-    }
-  });
-
   test("updateConnection clears label when set to null", () => {
     const db = bootDb();
     createConnection(db, {
@@ -116,7 +97,7 @@ describe("connection CRUD status + label defaults", () => {
 });
 
 describe("seedCanonicalConnections labels", () => {
-  test("first boot seeds default labels on all three managed connections", () => {
+  test("first boot seeds default labels on all managed connections", () => {
     const db = bootDb();
     seedCanonicalConnections(db);
 
@@ -162,7 +143,7 @@ describe("seedCanonicalConnections labels", () => {
     expect(after?.label).toBe("Anthropic");
   });
 
-  test("backfill leaves explicit empty-overwrite null untouched on subsequent boot", () => {
+  test("backfill fills null label on subsequent boot", () => {
     const db = bootDb();
     seedCanonicalConnections(db);
 
@@ -183,83 +164,3 @@ describe("seedCanonicalConnections labels", () => {
     expect(conn?.label).toBe("OpenAI");
   });
 });
-
-describe("disableManagedConnectionsForByokHatch", () => {
-  test("flips all three canonical managed connections to status='disabled'", () => {
-    const db = bootDb();
-    seedCanonicalConnections(db);
-
-    // Sanity: seeded rows default to active.
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("active");
-    expect(getConnection(db, "openai-managed")?.status).toBe("active");
-    expect(getConnection(db, "gemini-managed")?.status).toBe("active");
-
-    disableManagedConnectionsForByokHatch(db);
-
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "openai-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "gemini-managed")?.status).toBe("disabled");
-  });
-
-  test("leaves an excluded managed connection active", () => {
-    const db = bootDb();
-    seedCanonicalConnections(db);
-
-    disableManagedConnectionsForByokHatch(db, {
-      excludeConnection: "anthropic-managed",
-    });
-
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("active");
-    expect(getConnection(db, "openai-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "gemini-managed")?.status).toBe("disabled");
-  });
-
-  test("subsequent seedCanonicalConnections call does NOT re-flip a user-re-enabled connection", () => {
-    // Models the post-hatch lifecycle: at hatch we disable; the user
-    // later flips one back to active (e.g. after Vellum login). Every
-    // subsequent daemon boot runs seedCanonicalConnections — and that
-    // boot must NOT revert the user's choice. The hatch-disable helper
-    // is only ever called from the seedInferenceProfiles hatch branch,
-    // so it does not run on a non-hatch boot; this test confirms the
-    // ambient seed pass leaves status alone.
-    const db = bootDb();
-    seedCanonicalConnections(db);
-    disableManagedConnectionsForByokHatch(db);
-
-    // User re-enables anthropic post-hatch.
-    updateConnection(db, "anthropic-managed", {
-      auth: { type: "platform" },
-      status: "active",
-    });
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("active");
-
-    // Simulate a normal restart: seedCanonicalConnections runs every boot,
-    // disableManagedConnectionsForByokHatch does NOT.
-    seedCanonicalConnections(db);
-
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("active");
-    // The two the user didn't touch stay disabled.
-    expect(getConnection(db, "openai-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "gemini-managed")?.status).toBe("disabled");
-  });
-
-  test("idempotent re-hatch leaves all three at disabled", () => {
-    // Workspace reset / re-hatch scenario: helper runs again and any
-    // user re-enable from before the reset is intentionally undone —
-    // re-hatch means re-onboard.
-    const db = bootDb();
-    seedCanonicalConnections(db);
-    disableManagedConnectionsForByokHatch(db);
-
-    updateConnection(db, "anthropic-managed", {
-      auth: { type: "platform" },
-      status: "active",
-    });
-
-    disableManagedConnectionsForByokHatch(db);
-
-    expect(getConnection(db, "anthropic-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "openai-managed")?.status).toBe("disabled");
-    expect(getConnection(db, "gemini-managed")?.status).toBe("disabled");
-  });
-});

package/src/providers/inference/auth.ts

@@ -79,13 +79,6 @@ export const ConnectionProviderSchema = z.enum(
   VALID_CONNECTION_PROVIDERS as readonly [string, ...string[]],
 );
 
-// ---------------------------------------------------------------------------
-// Connection status
-// ---------------------------------------------------------------------------
-
-export const ConnectionStatusSchema = z.enum(["active", "disabled"]);
-export type ConnectionStatus = z.infer<typeof ConnectionStatusSchema>;
-
 // ---------------------------------------------------------------------------
 // Per-connection model entries (openai-compatible)
 // ---------------------------------------------------------------------------
@@ -104,7 +97,6 @@ export const ProviderConnectionSchema = z.object({
   name: z.string().min(1),
   provider: ConnectionProviderSchema,
   auth: AuthSchema,
-  status: ConnectionStatusSchema,
   label: z.string().min(1).nullable(),
   baseUrl: z.string().url().nullable(),
   models: z.array(ConnectionModelSchema).nullable(),

package/src/providers/inference/connections.ts

@@ -11,8 +11,6 @@ import {
   ConnectionModelSchema,
   type ConnectionProvider,
   ConnectionProviderSchema,
-  type ConnectionStatus,
-  ConnectionStatusSchema,
   type ProviderConnection,
   VALID_CONNECTION_PROVIDERS,
 } from "./auth.js";
@@ -55,16 +53,11 @@ export function listConnections(
     if (!auth.success) return [];
     const provider = ConnectionProviderSchema.safeParse(row.provider);
     if (!provider.success) return [];
-    const statusResult = ConnectionStatusSchema.safeParse(row.status);
-    const status: ConnectionStatus = statusResult.success
-      ? statusResult.data
-      : "active";
     return [
       {
         ...row,
         auth: auth.data,
         provider: provider.data,
-        status,
         label: row.label ?? null,
         baseUrl: row.baseUrl ?? null,
         models: parseModelsColumn(row.models),
@@ -89,15 +82,10 @@ export function getConnection(
   if (!auth.success) return null;
   const provider = ConnectionProviderSchema.safeParse(row.provider);
   if (!provider.success) return null;
-  const statusResult = ConnectionStatusSchema.safeParse(row.status);
-  const status: ConnectionStatus = statusResult.success
-    ? statusResult.data
-    : "active";
   return {
     ...row,
     auth: auth.data,
     provider: provider.data,
-    status,
     label: row.label ?? null,
     baseUrl: row.baseUrl ?? null,
     models: parseModelsColumn(row.models),
@@ -113,7 +101,6 @@ export type CreateConnectionInput = {
   name: string;
   provider: string;
   auth: Auth;
-  status?: ConnectionStatus;
   label?: string | null;
   baseUrl?: string | null;
   models?: ConnectionModel[] | null;
@@ -121,7 +108,6 @@ export type CreateConnectionInput = {
 
 export type UpdateConnectionInput = {
   auth: Auth;
-  status?: ConnectionStatus;
   label?: string | null;
   baseUrl?: string | null;
   models?: ConnectionModel[] | null;
@@ -173,7 +159,6 @@ export function createConnection(
     return { ok: false, error: { code: "already_exists" } };
   }
 
-  const status = input.status ?? "active";
   const label = input.label ?? null;
   const baseUrl = input.baseUrl ?? null;
   const models = input.models ?? null;
@@ -191,7 +176,6 @@ export function createConnection(
       name: input.name,
       provider,
       auth: JSON.stringify(authResult.data),
-      status,
       label,
       baseUrl,
       models: models === null ? null : JSON.stringify(models),
@@ -210,7 +194,6 @@ export function createConnection(
       name: input.name,
       provider,
       auth: authResult.data,
-      status,
       label,
       baseUrl,
       models,
@@ -255,12 +238,10 @@ export function updateConnection(
   const setClause: {
     auth: string;
     updatedAt: number;
-    status?: string;
     label?: string | null;
     baseUrl?: string | null;
     models?: string | null;
   } = { auth: JSON.stringify(authResult.data), updatedAt: now };
-  if (input.status !== undefined) setClause.status = input.status;
   if (input.label !== undefined) setClause.label = input.label;
   if (input.baseUrl !== undefined) setClause.baseUrl = input.baseUrl;
   if (input.models !== undefined)
@@ -280,7 +261,6 @@ export function updateConnection(
     connection: {
       ...existing,
       auth: authResult.data,
-      status: input.status !== undefined ? input.status : existing.status,
       label: input.label !== undefined ? input.label : existing.label,
       baseUrl: nextBaseUrl,
       models: nextModels,
@@ -376,10 +356,9 @@ const CANONICAL_CONNECTIONS: Array<{
  *     blocking prevents a confusing delete → re-appear loop).
  *   - PATCH that changes `auth` is blocked (auth is locked to `{type:"platform"}`
  *     so any other value would be reverted on the next boot upsert).
- *   - PATCH that changes `label` and/or `status` is allowed — users may legitimately
- *     disable or relabel the managed connection. `status` is never touched by the
- *     boot upsert. `label` is seeded on initial INSERT and backfilled when null
- *     on subsequent boots so pre-seed installs pick up the default; a non-null
+ *   - PATCH that changes `label` is allowed — users may legitimately relabel the
+ *     managed connection. `label` is seeded on initial INSERT and backfilled when
+ *     null on subsequent boots so pre-seed installs pick up the default; a non-null
  *     user-customized label is preserved (see `seedCanonicalConnections`).
  *
  * Mirrors `MANAGED_PROFILE_NAMES` (config/seed-inference-profiles.ts).
@@ -399,14 +378,6 @@ export const MANAGED_CONNECTION_NAMES: ReadonlySet<string> = new Set(
  * customization is preserved; the separate backfill step below assigns the
  * default only when the existing row has `label IS NULL`, covering installs
  * that pre-date the label seed.
- *
- * Status handling: the upsert never touches `status` so user customization
- * is preserved across reboots. New rows default to `status: "active"` via the
- * column default. Off-platform installs flip canonical managed rows to
- * `status: "disabled"` ONCE at hatch time via
- * `disableManagedConnectionsForByokHatch` (called from `seedInferenceProfiles`
- * when `isHatch && !isPlatform`); subsequent boots leave whatever the user
- * has chosen alone, so a post-hatch re-enable persists.
  */
 export function seedCanonicalConnections(db: DrizzleDb): void {
   const now = Date.now();
@@ -445,37 +416,3 @@ export function seedCanonicalConnections(db: DrizzleDb): void {
   }
 }
 
-/**
- * Flip canonical managed connections to `status: "disabled"` at
- * hatch time on BYOK (off-platform) installs.
- *
- * Why hatch-time only: managed connections need platform auth that a fresh
- * BYOK user doesn't have yet, so surfacing them as enabled in the picker
- * would let users pick an unusable option on day one. But this is a
- * first-time-only default — the moment the user explicitly flips one
- * back to active (e.g. after logging into Vellum), we never want a daemon
- * restart to revert that. `seedCanonicalConnections` leaves `status` alone
- * on the UPDATE path, and this helper is invoked ONLY from
- * `seedInferenceProfiles`'s `isHatch && !isPlatform` branch. Subsequent
- * non-hatch boots never call it.
- *
- * Idempotent: a second hatch (workspace reset) re-disables the rows, which
- * is the right call — re-hatch means re-onboard.
- *
- * When onboarding explicitly selected a managed profile, callers may exclude
- * that selected connection so the managed route remains usable for the first
- * post-onboarding message.
- */
-export function disableManagedConnectionsForByokHatch(
-  db: DrizzleDb,
-  options: { excludeConnection?: string } = {},
-): void {
-  const now = Date.now();
-  for (const name of MANAGED_CONNECTION_NAMES) {
-    if (name === options.excludeConnection) continue;
-    db.update(providerConnections)
-      .set({ status: "disabled", updatedAt: now })
-      .where(eq(providerConnections.name, name))
-      .run();
-  }
-}

package/src/providers/inference/resolve-auth.ts

@@ -89,9 +89,8 @@ export async function resolveAuth(
       // we need the prefix "credential/openai-codex" for the refresh logic.
       const credentialPrefix = auth.credential.replace(/\/access_token$/, "");
 
-      const { getValidCodexAccessToken } = await import(
-        "./codex-token-refresh.js"
-      );
+      const { getValidCodexAccessToken } =
+        await import("./codex-token-refresh.js");
       const token = await getValidCodexAccessToken(credentialPrefix);
 
       if (!token) {

package/src/providers/model-catalog.ts

@@ -144,6 +144,23 @@ const RAW_PROVIDER_CATALOG: ProviderCatalogEntry[] = [
       linkLabel: "Open Anthropic Console",
     },
     models: [
+      {
+        id: "claude-opus-4-8",
+        displayName: "Claude Opus 4.8",
+        contextWindowTokens: 1000000,
+        maxOutputTokens: 128000,
+        longContextPricingThresholdTokens: 200000,
+        supportsThinking: true,
+        supportsCaching: true,
+        supportsVision: true,
+        supportsToolUse: true,
+        pricing: {
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
+        },
+      },
       {
         id: "claude-opus-4-7",
         displayName: "Claude Opus 4.7",
@@ -244,7 +261,7 @@ const RAW_PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         },
       },
     ],
-    defaultModel: "claude-opus-4-7",
+    defaultModel: "claude-opus-4-8",
     apiKeyUrl: "https://console.anthropic.com/settings/keys",
     apiKeyPlaceholder: "sk-ant-api03-...",
   },
@@ -703,6 +720,23 @@ const RAW_PROVIDER_CATALOG: ProviderCatalogEntry[] = [
       // OpenRouter proxies anthropic/* through Anthropic's Messages API, so
       // prompt caching and cache TTL metadata pass through unchanged and
       // billing matches Anthropic's direct rates.
+      {
+        id: "anthropic/claude-opus-4.8",
+        displayName: "Claude Opus 4.8",
+        contextWindowTokens: 1000000,
+        maxOutputTokens: 128000,
+        longContextPricingThresholdTokens: 200000,
+        supportsThinking: true,
+        supportsCaching: true,
+        supportsVision: true,
+        supportsToolUse: true,
+        pricing: {
+          inputPer1mTokens: 5,
+          outputPer1mTokens: 25,
+          cacheWritePer1mTokens: 6.25,
+          cacheReadPer1mTokens: 0.5,
+        },
+      },
       {
         id: "anthropic/claude-opus-4.7",
         displayName: "Claude Opus 4.7",

package/src/providers/model-intents.ts

@@ -13,7 +13,7 @@ const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   anthropic: {
     balanced: "claude-sonnet-4-6",
     "latency-optimized": "claude-haiku-4-5-20251001",
-    "quality-optimized": "claude-opus-4-7",
+    "quality-optimized": "claude-opus-4-8",
     "vision-optimized": "claude-opus-4-6",
   },
   openai: {
@@ -43,12 +43,12 @@ const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   openrouter: {
     balanced: "anthropic/claude-sonnet-4.6",
     "latency-optimized": "anthropic/claude-haiku-4.5",
-    "quality-optimized": "anthropic/claude-opus-4.7",
+    "quality-optimized": "anthropic/claude-opus-4.8",
     "vision-optimized": "anthropic/claude-opus-4.6",
   },
 };
 
-const FALLBACK_DEFAULT_MODEL = "claude-opus-4-7";
+const FALLBACK_DEFAULT_MODEL = "claude-opus-4-8";
 
 const MODEL_INTENTS = new Set<ModelIntent>([
   "balanced",

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

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+
+import OpenAI from "openai";
+
+import { extractApiErrorDetail } from "../chat-completions-provider.js";
+
+/**
+ * Construct a real `OpenAI.APIError` so production code paths that use
+ * `instanceof OpenAI.APIError` and SDK-defined getters keep matching.
+ */
+function buildApiError(
+  status: number,
+  body: unknown,
+  headers?: Headers,
+): InstanceType<typeof OpenAI.APIError> {
+  return new OpenAI.APIError(
+    status,
+    body as Record<string, unknown>,
+    undefined,
+    headers ?? new Headers(),
+  );
+}
+
+describe("extractApiErrorDetail", () => {
+  test("serializes a structured body so logs show the upstream error", () => {
+    // This is the canonical OpenRouter shape that motivated the helper:
+    // the SDK's `error.message` collapses to "400 Provider returned error"
+    // and the real detail lives nested under `error.metadata.raw`.
+    const err = buildApiError(400, {
+      error: {
+        code: 400,
+        message: "Provider returned error",
+        metadata: {
+          raw: "messages.4: tool_use_id must reference a prior tool_use block",
+          provider_name: "Anthropic",
+        },
+      },
+    });
+    const { detail, requestId } = extractApiErrorDetail(err);
+    expect(detail).toContain("Provider returned error");
+    expect(detail).toContain("tool_use_id must reference a prior tool_use");
+    expect(detail).toContain("Anthropic");
+    expect(requestId).toBeUndefined();
+  });
+
+  test("surfaces the upstream request id when present in headers", () => {
+    const headers = new Headers({ "x-request-id": "req_abc123" });
+    const err = buildApiError(
+      400,
+      { error: { message: "Provider returned error" } },
+      headers,
+    );
+    const { requestId } = extractApiErrorDetail(err);
+    expect(requestId).toBe("req_abc123");
+  });
+
+  test("falls back to x-openrouter-request-id when x-request-id is absent", () => {
+    const headers = new Headers({
+      "x-openrouter-request-id": "gen-or-xyz",
+    });
+    const err = buildApiError(
+      400,
+      { error: { message: "Provider returned error" } },
+      headers,
+    );
+    const { requestId } = extractApiErrorDetail(err);
+    expect(requestId).toBe("gen-or-xyz");
+  });
+
+  test("returns empty detail when the body is missing", () => {
+    // The SDK constructs an APIError even when the upstream response had
+    // no JSON body (e.g. network-layer 5xx). The helper must degrade
+    // gracefully rather than emit `undefined` or `null` strings.
+    const err = buildApiError(500, undefined);
+    const { detail, requestId } = extractApiErrorDetail(err);
+    expect(detail).toBe("");
+    expect(requestId).toBeUndefined();
+  });
+
+  test("returns empty detail when the body serializes to an empty object", () => {
+    // `{}` carries zero signal and just adds noise to log lines.
+    const err = buildApiError(429, {});
+    const { detail } = extractApiErrorDetail(err);
+    expect(detail).toBe("");
+  });
+
+  test("truncates very long bodies with an ellipsis", () => {
+    const huge = "X".repeat(5000);
+    const err = buildApiError(400, { error: { message: huge } });
+    const { detail } = extractApiErrorDetail(err);
+    // Cap is 2000 chars; the helper appends a single-char ellipsis when truncating.
+    expect(detail.length).toBeLessThanOrEqual(2001);
+    expect(detail.endsWith("…")).toBe(true);
+  });
+
+  test("preserves string bodies verbatim (no double-encoding)", () => {
+    // Some providers return a non-JSON body (HTML error page, plain text).
+    // The SDK stores it on `error.error` as a string in that case.
+    const err = buildApiError(502, "upstream timeout");
+    const { detail } = extractApiErrorDetail(err);
+    expect(detail).toBe("upstream timeout");
+  });
+
+  test("returns empty detail when JSON.stringify throws (cyclic body)", () => {
+    // Pathological body — should not propagate the TypeError to callers.
+    // OpenAI's `APIError` constructor itself JSON.stringifies the body to
+    // build its own `.message`, so we can't get to this branch via the SDK
+    // constructor; build a structural stand-in instead.
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    const stub = {
+      status: 400,
+      message: "synthetic",
+      headers: new Headers(),
+      error: cyclic,
+    } as unknown as InstanceType<typeof OpenAI.APIError>;
+    const { detail } = extractApiErrorDetail(stub);
+    expect(detail).toBe("");
+  });
+});