@diabolicallabs/llm-client 0.2.0 → 0.4.0

package/dist/index.js

@@ -7,6 +7,13 @@ var LlmError = class extends Error {
   provider;
   statusCode;
   retryable;
+  /**
+   * Optional error kind discriminator. Present on errors produced by the abort/timeout/stall
+   * machinery (v0.3.0+). May be undefined on errors from providers that pre-date the kind field
+   * or on errors that fall through to the generic normalization path.
+   * Typed as LlmErrorKind | undefined to satisfy exactOptionalPropertyTypes.
+   */
+  kind;
   // `cause` is declared on Error in lib.es2022.error.d.ts as `cause?: unknown`
   // We override it here to make it always present (not optional) after construction.
   cause;
@@ -15,10 +22,249 @@ var LlmError = class extends Error {
     this.provider = opts.provider;
     this.statusCode = opts.statusCode;
     this.retryable = opts.retryable;
+    this.kind = opts.kind;
     this.cause = opts.cause;
   }
 };
 
+// src/abort.ts
+function createAttemptController(callerSignal, timeoutMs) {
+  const internal = new AbortController();
+  let reason;
+  const timer = setTimeout(() => {
+    reason ??= "timeout";
+    internal.abort(new Error("llm-client: timeout"));
+  }, timeoutMs);
+  timer.unref?.();
+  const onCallerAbort = () => {
+    reason ??= "caller";
+    if (callerSignal !== void 0) internal.abort(callerSignal.reason);
+  };
+  if (callerSignal !== void 0) {
+    if (callerSignal.aborted) {
+      onCallerAbort();
+    } else {
+      callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+  }
+  return {
+    signal: internal.signal,
+    abortReason: () => reason,
+    abort: (r) => {
+      reason ??= r;
+      internal.abort();
+    },
+    dispose: () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+function cancellableSleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    timer.unref?.();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function* withStallTimeout(source, stallMs, ctl, provider) {
+  const it = source[Symbol.asyncIterator]();
+  while (true) {
+    let stallTimer;
+    const stallPromise = new Promise((_, reject) => {
+      stallTimer = setTimeout(() => {
+        ctl.abort("stall");
+        reject(
+          new LlmError({
+            provider,
+            kind: "stream_stall",
+            retryable: true,
+            message: `llm-client: no chunk for ${stallMs}ms`
+          })
+        );
+      }, stallMs);
+    });
+    try {
+      const next = await Promise.race([it.next(), stallPromise]);
+      clearTimeout(stallTimer);
+      if (next.done) return;
+      yield next.value;
+    } catch (err) {
+      clearTimeout(stallTimer);
+      throw err;
+    }
+  }
+}
+function classifyAbort(err, abortReason, provider) {
+  const controllerFired = abortReason !== void 0;
+  if (!controllerFired && !isAbortError(err)) return err;
+  switch (abortReason) {
+    case "timeout":
+      return new LlmError({
+        message: "llm-client: request timed out",
+        provider,
+        kind: "timeout",
+        retryable: true,
+        cause: err
+      });
+    case "stall":
+      return new LlmError({
+        message: "llm-client: stream stalled",
+        provider,
+        kind: "stream_stall",
+        retryable: true,
+        cause: err
+      });
+    default:
+      return new LlmError({
+        message: "llm-client: cancelled by caller",
+        provider,
+        kind: "cancelled",
+        retryable: false,
+        cause: err
+      });
+  }
+}
+function isAbortError(err) {
+  if (err instanceof Error && err.name === "AbortError") return true;
+  if (typeof DOMException !== "undefined" && err instanceof DOMException && err.name === "AbortError")
+    return true;
+  return false;
+}
+
+// src/json-schema.ts
+import { z } from "zod";
+function isZodSchema(s) {
+  if (typeof s !== "object" || s === null) return false;
+  const hasZod4Marker = "_zod" in s && typeof s._zod === "object";
+  const hasZod3Marker = "_def" in s;
+  if (hasZod3Marker && !hasZod4Marker) {
+    throw new LlmError({
+      message: 'llm-client: detected a Zod 3 schema. Upgrade to Zod 4 to use strict structured-output mode, or pass providerOptions.structuredMode = "prompt" to keep the v0.3.0 prompt-only path.',
+      provider: "llm-client",
+      retryable: false,
+      kind: "unknown"
+    });
+  }
+  if (!hasZod4Marker) return false;
+  return typeof s.parse === "function";
+}
+function toProviderSchema(schema, profile) {
+  const target = profile === "gemini" ? "openapi-3.0" : "draft-2020-12";
+  let json;
+  try {
+    json = z.toJSONSchema(schema, {
+      target,
+      unrepresentable: "throw",
+      cycles: "throw"
+    });
+  } catch (e) {
+    throw new LlmError({
+      message: `llm-client: schema is not representable for ${profile} strict mode \u2014 ${e.message}. Pass providerOptions.structuredMode = 'prompt' to fall back to prompt-only mode.`,
+      provider: profile,
+      retryable: false,
+      kind: "unknown",
+      cause: e
+    });
+  }
+  if (profile === "openai") return openAIStrictPostprocess(json);
+  if (profile === "gemini") return geminiPostprocess(json);
+  return anthropicPostprocess(json);
+}
+function openAIStrictPostprocess(node) {
+  if (typeof node !== "object" || node === null) {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map(openAIStrictPostprocess);
+  }
+  const src = node;
+  const obj = { ...src };
+  delete obj.$schema;
+  delete obj.format;
+  delete obj.pattern;
+  delete obj.default;
+  delete obj.examples;
+  if (obj.type === "object" && obj.properties !== void 0) {
+    const props = obj.properties;
+    const allKeys = Object.keys(props);
+    obj.required = allKeys;
+    obj.additionalProperties = false;
+    const processedProps = {};
+    for (const key of allKeys) {
+      processedProps[key] = openAIStrictPostprocess(props[key]);
+    }
+    obj.properties = processedProps;
+  }
+  if (obj.items !== void 0) {
+    obj.items = openAIStrictPostprocess(obj.items);
+  }
+  if (Array.isArray(obj.anyOf)) {
+    obj.anyOf = obj.anyOf.map(openAIStrictPostprocess);
+  }
+  if (Array.isArray(obj.oneOf)) {
+    obj.oneOf = obj.oneOf.map(openAIStrictPostprocess);
+  }
+  if (Array.isArray(obj.allOf)) {
+    obj.allOf = obj.allOf.map(openAIStrictPostprocess);
+  }
+  if (Array.isArray(obj.prefixItems)) {
+    obj.prefixItems = obj.prefixItems.map(openAIStrictPostprocess);
+  }
+  return obj;
+}
+function anthropicPostprocess(node) {
+  const obj = { ...node };
+  delete obj.$schema;
+  return obj;
+}
+function geminiPostprocess(node) {
+  if (typeof node !== "object" || node === null) {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map(geminiPostprocess);
+  }
+  const src = node;
+  const obj = { ...src };
+  delete obj.$schema;
+  delete obj.additionalProperties;
+  delete obj.default;
+  delete obj.examples;
+  if (obj.properties !== void 0) {
+    const props = obj.properties;
+    const processedProps = {};
+    for (const key of Object.keys(props)) {
+      processedProps[key] = geminiPostprocess(props[key]);
+    }
+    obj.properties = processedProps;
+  }
+  if (obj.items !== void 0) {
+    obj.items = geminiPostprocess(obj.items);
+  }
+  if (Array.isArray(obj.anyOf)) {
+    obj.anyOf = obj.anyOf.map(geminiPostprocess);
+  }
+  if (Array.isArray(obj.oneOf)) {
+    obj.oneOf = obj.oneOf.map(geminiPostprocess);
+  }
+  if (Array.isArray(obj.allOf)) {
+    obj.allOf = obj.allOf.map(geminiPostprocess);
+  }
+  return obj;
+}
+
 // src/retry.ts
 var RETRYABLE_HTTP_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var RETRYABLE_ERROR_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ETIMEDOUT", "ECONNABORTED"]);
@@ -35,19 +281,32 @@ function computeBackoffMs(attempt, baseDelayMs) {
   const ceiling = baseDelayMs * 2 ** attempt;
   return Math.random() * ceiling;
 }
+function mergeRetryOptsWithSignal(base, signal) {
+  return signal !== void 0 ? { ...base, signal } : { ...base };
+}
 async function withRetry(fn, opts) {
   let lastError;
   for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    if (opts.signal?.aborted === true) {
+      throw new LlmError({
+        message: "llm-client: cancelled by caller",
+        provider: opts.provider,
+        kind: "cancelled",
+        retryable: false,
+        cause: opts.signal.reason
+      });
+    }
     try {
       return await fn(attempt);
     } catch (err) {
       const llmErr = normalizeThrownError(err, opts.provider);
+      if (llmErr.kind === "cancelled") throw llmErr;
       if (!llmErr.retryable || attempt === opts.maxRetries) {
         throw llmErr;
       }
       lastError = llmErr;
       const delayMs = computeBackoffMs(attempt, opts.baseDelayMs);
-      await sleep(delayMs);
+      await cancellableSleep(delayMs, opts.signal);
     }
   }
   throw lastError ?? new LlmError({
@@ -59,6 +318,15 @@ async function withRetry(fn, opts) {
 function normalizeThrownError(err, provider) {
   if (err instanceof LlmError) return err;
   if (err instanceof Error) {
+    if (err.name === "AbortError" || typeof DOMException !== "undefined" && err instanceof DOMException && err.name === "AbortError") {
+      return new LlmError({
+        message: err.message || "llm-client: cancelled by caller",
+        provider,
+        kind: "cancelled",
+        retryable: false,
+        cause: err
+      });
+    }
     const errWithCode = err;
     const statusCode = errWithCode.status ?? errWithCode.statusCode;
     if (errWithCode.code !== void 0 && isRetryableErrorCode(errWithCode.code)) {
@@ -67,24 +335,34 @@ function normalizeThrownError(err, provider) {
           message: err.message,
           provider,
           statusCode,
+          kind: "network",
           retryable: true,
           cause: err
         });
       }
-      return new LlmError({ message: err.message, provider, retryable: true, cause: err });
+      return new LlmError({
+        message: err.message,
+        provider,
+        kind: "network",
+        retryable: true,
+        cause: err
+      });
     }
     if (statusCode !== void 0) {
+      const retryable = isRetryableStatus(statusCode);
       return new LlmError({
         message: err.message,
         provider,
         statusCode,
-        retryable: isRetryableStatus(statusCode),
+        kind: retryable ? "http" : "http",
+        retryable,
         cause: err
       });
     }
     return new LlmError({
       message: err.message,
       provider,
+      kind: "unknown",
       retryable: false,
       cause: err
     });
@@ -92,13 +370,11 @@ function normalizeThrownError(err, provider) {
   return new LlmError({
     message: String(err),
     provider,
+    kind: "unknown",
     retryable: false,
     cause: err
   });
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/providers/anthropic.ts
 var PROVIDER = "anthropic";
@@ -166,35 +442,44 @@ function createAnthropicProvider(config) {
   async function complete(messages, options) {
     const model = options?.model ?? config.model;
     const { system, messages: anthropicMessages } = buildAnthropicMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
-    return withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: anthropicMessages,
-          max_tokens: options?.maxTokens ?? config.maxTokens ?? 1024
-        };
-        if (system !== void 0) params.system = system;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) {
-          params.temperature = temperature;
+    return withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: anthropicMessages,
+            max_tokens: options?.maxTokens ?? config.maxTokens ?? 1024
+          };
+          if (system !== void 0) params.system = system;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) {
+            params.temperature = temperature;
+          }
+          const response = await client.messages.create(params, { signal: ctl.signal });
+          const content = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+          return {
+            content,
+            model: response.model,
+            usage: normalizeUsage(response.usage),
+            latencyMs: Date.now() - start
+          };
+        } catch (err) {
+          throw normalizeAnthropicError(classifyAbort(err, ctl.abortReason(), PROVIDER));
+        } finally {
+          ctl.dispose();
         }
-        const response = await client.messages.create(params);
-        const content = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
-        return {
-          content,
-          model: response.model,
-          usage: normalizeUsage(response.usage),
-          latencyMs: Date.now() - start
-        };
-      } catch (err) {
-        throw normalizeAnthropicError(err);
-      }
-    }, retryOpts);
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
   }
   async function* stream(messages, options) {
     const model = options?.model ?? config.model;
     const { system, messages: anthropicMessages } = buildAnthropicMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const stallMs = options?.streamStallTimeoutMs ?? config.streamStallTimeoutMs ?? 3e4;
     const params = {
       model,
       messages: anthropicMessages,
@@ -205,15 +490,23 @@ function createAnthropicProvider(config) {
     if (streamTemperature !== void 0) {
       params.temperature = streamTemperature;
     }
+    const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
     let sdkStream;
     try {
-      sdkStream = client.messages.stream(params);
+      sdkStream = client.messages.stream(params, { signal: ctl.signal });
     } catch (err) {
-      throw normalizeAnthropicError(err);
+      ctl.dispose();
+      throw normalizeAnthropicError(classifyAbort(err, ctl.abortReason(), PROVIDER));
     }
     let finalUsage;
     try {
-      for await (const event of sdkStream) {
+      const stallWrapped = withStallTimeout(
+        sdkStream,
+        stallMs,
+        ctl,
+        PROVIDER
+      );
+      for await (const event of stallWrapped) {
         if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
           yield { token: event.delta.text };
         } else if (event.type === "message_delta" && "usage" in event) {
@@ -222,13 +515,85 @@ function createAnthropicProvider(config) {
         }
       }
     } catch (err) {
-      throw normalizeAnthropicError(err);
+      throw normalizeAnthropicError(classifyAbort(err, ctl.abortReason(), PROVIDER));
+    } finally {
+      ctl.dispose();
     }
     if (finalUsage !== void 0) {
       yield { token: "", usage: finalUsage };
     }
   }
   async function structured(messages, schema, options) {
+    const structuredMode = options?.providerOptions?.["structuredMode"];
+    const useStrict = isZodSchema(schema) && structuredMode !== "prompt";
+    if (!useStrict) {
+      return structuredPromptFallback(messages, schema, options);
+    }
+    const inputSchema = toProviderSchema(schema, "anthropic");
+    const { system, messages: anthropicMessages } = buildAnthropicMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const start = Date.now();
+    const response = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model: options?.model ?? config.model,
+            messages: anthropicMessages,
+            max_tokens: options?.maxTokens ?? config.maxTokens ?? 1024,
+            tools: [
+              {
+                name: "extract",
+                description: "Return the structured data.",
+                input_schema: inputSchema
+              }
+            ],
+            tool_choice: { type: "tool", name: "extract" }
+          };
+          if (system !== void 0) params.system = system;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          return await client.messages.create(params, { signal: ctl.signal });
+        } catch (err) {
+          throw normalizeAnthropicError(classifyAbort(err, ctl.abortReason(), PROVIDER));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
+    const toolBlock = response.content.find(
+      (b) => b.type === "tool_use" && b.name === "extract"
+    );
+    if (toolBlock === void 0) {
+      const textContent = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      throw new LlmError({
+        message: `Anthropic structured: model did not call the extract tool (stop_reason=${response.stop_reason}). Text: ${textContent.slice(0, 200)}`,
+        provider: PROVIDER,
+        retryable: false,
+        kind: "unknown"
+      });
+    }
+    let data;
+    try {
+      data = schema.parse(toolBlock.input);
+    } catch (err) {
+      throw new LlmError({
+        message: `Anthropic structured output: tool response failed schema validation. ${String(err)}`,
+        provider: PROVIDER,
+        retryable: false,
+        cause: err
+      });
+    }
+    return {
+      data,
+      model: response.model,
+      id: response.id,
+      usage: normalizeUsage(response.usage),
+      latencyMs: Date.now() - start
+    };
+  }
+  async function structuredPromptFallback(messages, schema, options) {
     const jsonSystemInstruction = {
       role: "system",
       content: "You must respond with valid JSON only. No explanations, no markdown code fences, no extra text. Your entire response must be valid JSON that can be parsed with JSON.parse()."
@@ -261,6 +626,7 @@ function createAnthropicProvider(config) {
     }
     return {
       data,
+      model: response.model,
       usage: response.usage,
       latencyMs: Date.now() - start
     };
@@ -334,34 +700,43 @@ function createDeepSeekProvider(config) {
   async function complete(messages, options) {
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
-    return withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: chatMessages,
-          stream: false
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        const response = await client.chat.completions.create(params);
-        const content = response.choices.map((c) => c.message.content ?? "").join("");
-        return {
-          content,
-          model: response.model,
-          usage: normalizeUsage2(response.usage),
-          latencyMs: Date.now() - start
-        };
-      } catch (err) {
-        throw normalizeDeepSeekError(err);
-      }
-    }, retryOpts);
+    return withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: chatMessages,
+            stream: false
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          const response = await client.chat.completions.create(params, { signal: ctl.signal });
+          const content = response.choices.map((c) => c.message.content ?? "").join("");
+          return {
+            content,
+            model: response.model,
+            usage: normalizeUsage2(response.usage),
+            latencyMs: Date.now() - start
+          };
+        } catch (err) {
+          throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
   }
   async function* stream(messages, options) {
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const stallMs = options?.streamStallTimeoutMs ?? config.streamStallTimeoutMs ?? 3e4;
     const params = {
       model,
       messages: chatMessages,
@@ -372,15 +747,17 @@ function createDeepSeekProvider(config) {
     if (maxTokens !== void 0) params.max_tokens = maxTokens;
     const temperature = options?.temperature ?? config.temperature;
     if (temperature !== void 0) params.temperature = temperature;
+    const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
     let sdkStream;
     try {
-      sdkStream = await client.chat.completions.create(params);
+      sdkStream = await client.chat.completions.create(params, { signal: ctl.signal });
     } catch (err) {
-      throw normalizeDeepSeekError(err);
+      ctl.dispose();
+      throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
     }
     let finalUsage;
     try {
-      for await (const chunk of sdkStream) {
+      for await (const chunk of withStallTimeout(sdkStream, stallMs, ctl, PROVIDER2)) {
         const delta = chunk.choices[0]?.delta.content;
         if (delta !== void 0 && delta !== null && delta.length > 0) {
           yield { token: delta };
@@ -390,7 +767,9 @@ function createDeepSeekProvider(config) {
         }
       }
     } catch (err) {
-      throw normalizeDeepSeekError(err);
+      throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
+    } finally {
+      ctl.dispose();
     }
     if (finalUsage !== void 0) {
       yield { token: "", usage: finalUsage };
@@ -404,23 +783,30 @@ function createDeepSeekProvider(config) {
     const augmentedMessages = [jsonSystemInstruction, ...messages];
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages(augmentedMessages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
-    const rawResponse = await withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: chatMessages,
-          stream: false
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        return await client.chat.completions.create(params);
-      } catch (err) {
-        throw normalizeDeepSeekError(err);
-      }
-    }, retryOpts);
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: chatMessages,
+            stream: false
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          return await client.chat.completions.create(params, { signal: ctl.signal });
+        } catch (err) {
+          throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
     const rawContent = rawResponse.choices[0]?.message.content ?? "";
     let parsed;
     try {
@@ -447,6 +833,8 @@ function createDeepSeekProvider(config) {
     }
     return {
       data,
+      model: rawResponse.model,
+      id: rawResponse.id,
       usage: normalizeUsage2(rawResponse.usage),
       latencyMs: Date.now() - start
     };
@@ -498,11 +886,26 @@ function normalizeGeminiError(err) {
   }
   return normalizeThrownError(err, PROVIDER3);
 }
+function makeAbortRacePromise(signal) {
+  return new Promise((_, reject) => {
+    const onAbort = () => {
+      const e = new Error("AbortError");
+      e.name = "AbortError";
+      reject(e);
+    };
+    if (signal.aborted) {
+      onAbort();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
 function createGeminiProvider(config) {
+  const configTimeoutMs = config.timeoutMs ?? 3e4;
   const ai = new GoogleGenAI({
     apiKey: config.apiKey,
     httpOptions: {
-      timeout: config.timeoutMs ?? 3e4
+      timeout: configTimeoutMs * 2
     }
   });
   const retryOpts = {
@@ -513,53 +916,62 @@ function createGeminiProvider(config) {
   async function complete(messages, options) {
     const model = options?.model ?? config.model;
     const { system, contents } = buildGeminiContents(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? configTimeoutMs;
     const start = Date.now();
-    return withRetry(async () => {
-      try {
-        const geminiConfig = {};
-        if (system !== void 0) geminiConfig.systemInstruction = system;
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) geminiConfig.temperature = temperature;
-        const response = await ai.models.generateContent({
-          model,
-          contents,
-          config: geminiConfig
-        });
-        return {
-          content: response.text ?? "",
-          model,
-          usage: normalizeUsage3(response.usageMetadata),
-          latencyMs: Date.now() - start
-        };
-      } catch (err) {
-        throw normalizeGeminiError(err);
-      }
-    }, retryOpts);
+    return withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const geminiConfig = {};
+          if (system !== void 0) geminiConfig.systemInstruction = system;
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) geminiConfig.temperature = temperature;
+          const response = await Promise.race([
+            ai.models.generateContent({ model, contents, config: geminiConfig }),
+            makeAbortRacePromise(ctl.signal)
+          ]);
+          return {
+            content: response.text ?? "",
+            model,
+            usage: normalizeUsage3(response.usageMetadata),
+            latencyMs: Date.now() - start
+          };
+        } catch (err) {
+          throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
   }
   async function* stream(messages, options) {
     const model = options?.model ?? config.model;
     const { system, contents } = buildGeminiContents(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? configTimeoutMs;
+    const stallMs = options?.streamStallTimeoutMs ?? config.streamStallTimeoutMs ?? 3e4;
     const geminiConfig = {};
     if (system !== void 0) geminiConfig.systemInstruction = system;
     const maxTokens = options?.maxTokens ?? config.maxTokens;
     if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
     const temperature = options?.temperature ?? config.temperature;
     if (temperature !== void 0) geminiConfig.temperature = temperature;
+    const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
     let sdkStream;
     try {
-      sdkStream = await ai.models.generateContentStream({
-        model,
-        contents,
-        config: geminiConfig
-      });
+      sdkStream = await Promise.race([
+        ai.models.generateContentStream({ model, contents, config: geminiConfig }),
+        makeAbortRacePromise(ctl.signal)
+      ]);
     } catch (err) {
-      throw normalizeGeminiError(err);
+      ctl.dispose();
+      throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
     }
     let finalUsage;
     try {
-      for await (const chunk of sdkStream) {
+      for await (const chunk of withStallTimeout(sdkStream, stallMs, ctl, PROVIDER3)) {
         const text = chunk.text;
         if (text !== void 0 && text.length > 0) {
           yield { token: text };
@@ -569,13 +981,84 @@ function createGeminiProvider(config) {
         }
       }
     } catch (err) {
-      throw normalizeGeminiError(err);
+      throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+    } finally {
+      ctl.dispose();
     }
     if (finalUsage !== void 0) {
       yield { token: "", usage: finalUsage };
     }
   }
   async function structured(messages, schema, options) {
+    const structuredMode = options?.providerOptions?.["structuredMode"];
+    const useStrict = isZodSchema(schema) && structuredMode !== "prompt";
+    if (!useStrict) {
+      return structuredPromptFallback(messages, schema, options);
+    }
+    const responseSchemaObj = toProviderSchema(schema, "gemini");
+    const model = options?.model ?? config.model;
+    const { system, contents } = buildGeminiContents(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? configTimeoutMs;
+    const start = Date.now();
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const geminiConfig = {
+            responseMimeType: "application/json",
+            // responseSchema SDK type is permissive; cast through never to avoid SDK type mismatch
+            responseSchema: responseSchemaObj
+          };
+          if (system !== void 0) geminiConfig.systemInstruction = system;
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) geminiConfig.temperature = temperature;
+          return await Promise.race([
+            ai.models.generateContent({ model, contents, config: geminiConfig }),
+            makeAbortRacePromise(ctl.signal)
+          ]);
+        } catch (err) {
+          throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
+    const rawContent = rawResponse.text ?? "";
+    let parsed;
+    try {
+      const cleaned = rawContent.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+      parsed = JSON.parse(cleaned);
+    } catch (err) {
+      throw new LlmError({
+        message: `Gemini structured output: response is not valid JSON. Raw: ${rawContent.slice(0, 200)}`,
+        provider: PROVIDER3,
+        retryable: false,
+        cause: err
+      });
+    }
+    let data;
+    try {
+      data = schema.parse(parsed);
+    } catch (err) {
+      throw new LlmError({
+        message: `Gemini structured output: response failed schema validation. ${String(err)}`,
+        provider: PROVIDER3,
+        retryable: false,
+        cause: err
+      });
+    }
+    return {
+      data,
+      // Gemini does not return a request ID; model comes from response.modelVersion if available
+      model: rawResponse.modelVersion ?? model,
+      usage: normalizeUsage3(rawResponse.usageMetadata),
+      latencyMs: Date.now() - start
+    };
+  }
+  async function structuredPromptFallback(messages, schema, options) {
     const augmentedMessages = [
       {
         role: "system",
@@ -585,27 +1068,32 @@ function createGeminiProvider(config) {
     ];
     const model = options?.model ?? config.model;
     const { system, contents } = buildGeminiContents(augmentedMessages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? configTimeoutMs;
     const start = Date.now();
-    const rawResponse = await withRetry(async () => {
-      try {
-        const geminiConfig = {
-          // Instruct Gemini to return JSON directly
-          responseMimeType: "application/json"
-        };
-        if (system !== void 0) geminiConfig.systemInstruction = system;
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) geminiConfig.temperature = temperature;
-        return await ai.models.generateContent({
-          model,
-          contents,
-          config: geminiConfig
-        });
-      } catch (err) {
-        throw normalizeGeminiError(err);
-      }
-    }, retryOpts);
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const geminiConfig = {
+            responseMimeType: "application/json"
+          };
+          if (system !== void 0) geminiConfig.systemInstruction = system;
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) geminiConfig.maxOutputTokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) geminiConfig.temperature = temperature;
+          return await Promise.race([
+            ai.models.generateContent({ model, contents, config: geminiConfig }),
+            makeAbortRacePromise(ctl.signal)
+          ]);
+        } catch (err) {
+          throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
     const rawContent = rawResponse.text ?? "";
     let parsed;
     try {
@@ -632,6 +1120,7 @@ function createGeminiProvider(config) {
     }
     return {
       data,
+      model,
       usage: normalizeUsage3(rawResponse.usageMetadata),
       latencyMs: Date.now() - start
     };
@@ -703,34 +1192,43 @@ function createOpenAIProvider(config) {
   async function complete(messages, options) {
     const model = options?.model ?? config.model;
     const openAIMessages = buildOpenAIMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
-    return withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: openAIMessages,
-          stream: false
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        const response = await client.chat.completions.create(params);
-        const content = response.choices.map((c) => c.message.content ?? "").join("");
-        return {
-          content,
-          model: response.model,
-          usage: normalizeUsage4(response.usage),
-          latencyMs: Date.now() - start
-        };
-      } catch (err) {
-        throw normalizeOpenAIError(err);
-      }
-    }, retryOpts);
+    return withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: openAIMessages,
+            stream: false
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          const response = await client.chat.completions.create(params, { signal: ctl.signal });
+          const content = response.choices.map((c) => c.message.content ?? "").join("");
+          return {
+            content,
+            model: response.model,
+            usage: normalizeUsage4(response.usage),
+            latencyMs: Date.now() - start
+          };
+        } catch (err) {
+          throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
   }
   async function* stream(messages, options) {
     const model = options?.model ?? config.model;
     const openAIMessages = buildOpenAIMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const stallMs = options?.streamStallTimeoutMs ?? config.streamStallTimeoutMs ?? 3e4;
     const params = {
       model,
       messages: openAIMessages,
@@ -741,15 +1239,17 @@ function createOpenAIProvider(config) {
     if (maxTokens !== void 0) params.max_tokens = maxTokens;
     const temperature = options?.temperature ?? config.temperature;
     if (temperature !== void 0) params.temperature = temperature;
+    const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
     let sdkStream;
     try {
-      sdkStream = await client.chat.completions.create(params);
+      sdkStream = await client.chat.completions.create(params, { signal: ctl.signal });
     } catch (err) {
-      throw normalizeOpenAIError(err);
+      ctl.dispose();
+      throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
     }
     let finalUsage;
     try {
-      for await (const chunk of sdkStream) {
+      for await (const chunk of withStallTimeout(sdkStream, stallMs, ctl, PROVIDER4)) {
         const delta = chunk.choices[0]?.delta.content;
         if (delta !== void 0 && delta !== null && delta.length > 0) {
           yield { token: delta };
@@ -759,13 +1259,95 @@ function createOpenAIProvider(config) {
         }
       }
     } catch (err) {
-      throw normalizeOpenAIError(err);
+      throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+    } finally {
+      ctl.dispose();
     }
     if (finalUsage !== void 0) {
       yield { token: "", usage: finalUsage };
     }
   }
   async function structured(messages, schema, options) {
+    const structuredMode = options?.providerOptions?.["structuredMode"];
+    const useStrict = isZodSchema(schema) && structuredMode !== "prompt";
+    if (!useStrict) {
+      return structuredPromptFallback(messages, schema, options);
+    }
+    const jsonSchema = toProviderSchema(schema, "openai");
+    const model = options?.model ?? config.model;
+    const openAIMessages = buildOpenAIMessages(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const start = Date.now();
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: openAIMessages,
+            stream: false,
+            response_format: {
+              type: "json_schema",
+              json_schema: { name: "response", schema: jsonSchema, strict: true }
+            }
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          return await client.chat.completions.create(
+            params,
+            { signal: ctl.signal }
+          );
+        } catch (err) {
+          throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
+    const choice = rawResponse.choices[0];
+    if (choice?.message.refusal !== null && choice?.message.refusal !== void 0) {
+      throw new LlmError({
+        message: `OpenAI structured output: model refused to generate. Refusal: ${choice.message.refusal.slice(0, 200)}`,
+        provider: PROVIDER4,
+        retryable: false,
+        kind: "unknown"
+      });
+    }
+    const rawContent = choice?.message.content ?? "";
+    let parsed;
+    try {
+      parsed = JSON.parse(rawContent);
+    } catch (err) {
+      throw new LlmError({
+        message: `OpenAI structured output: response is not valid JSON. Raw: ${rawContent.slice(0, 200)}`,
+        provider: PROVIDER4,
+        retryable: false,
+        cause: err
+      });
+    }
+    let data;
+    try {
+      data = schema.parse(parsed);
+    } catch (err) {
+      throw new LlmError({
+        message: `OpenAI structured output: response failed schema validation. ${String(err)}`,
+        provider: PROVIDER4,
+        retryable: false,
+        cause: err
+      });
+    }
+    return {
+      data,
+      model: rawResponse.model,
+      id: rawResponse.id,
+      usage: normalizeUsage4(rawResponse.usage),
+      latencyMs: Date.now() - start
+    };
+  }
+  async function structuredPromptFallback(messages, schema, options) {
     const jsonSystemInstruction = {
       role: "system",
       content: "You must respond with valid JSON only. No explanations, no markdown code fences, no extra text. Your entire response must be valid JSON that can be parsed with JSON.parse()."
@@ -773,24 +1355,31 @@ function createOpenAIProvider(config) {
     const augmentedMessages = [jsonSystemInstruction, ...messages];
     const model = options?.model ?? config.model;
     const openAIMessages = buildOpenAIMessages(augmentedMessages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
-    const rawResponse = await withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: openAIMessages,
-          stream: false,
-          response_format: { type: "json_object" }
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        return await client.chat.completions.create(params);
-      } catch (err) {
-        throw normalizeOpenAIError(err);
-      }
-    }, retryOpts);
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: openAIMessages,
+            stream: false,
+            response_format: { type: "json_object" }
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          return await client.chat.completions.create(params, { signal: ctl.signal });
+        } catch (err) {
+          throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
     const rawContent = rawResponse.choices[0]?.message.content ?? "";
     let parsed;
     try {
@@ -816,6 +1405,8 @@ function createOpenAIProvider(config) {
     }
     return {
       data,
+      model: rawResponse.model,
+      id: rawResponse.id,
       usage: normalizeUsage4(rawResponse.usage),
       latencyMs: Date.now() - start
     };
@@ -906,42 +1497,52 @@ function createPerplexityProvider(config) {
   async function complete(messages, options) {
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages2(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
     const extraParams = extractProviderOptions(options?.providerOptions);
-    return withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: chatMessages,
-          stream: false,
-          ...extraParams
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        const rawResponse = await client.chat.completions.create(
-          params
-        );
-        const response = rawResponse;
-        const content = response.choices.map((c) => c.message.content ?? "").join("");
-        const result = {
-          content,
-          model: response.model,
-          usage: normalizeUsage5(response.usage),
-          latencyMs: Date.now() - start
-        };
-        const citations = extractCitations(response);
-        if (citations !== void 0) result.citations = citations;
-        return result;
-      } catch (err) {
-        throw normalizePerplexityError(err);
-      }
-    }, retryOpts);
+    return withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: chatMessages,
+            stream: false,
+            ...extraParams
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          const rawResponse = await client.chat.completions.create(
+            params,
+            { signal: ctl.signal }
+          );
+          const response = rawResponse;
+          const content = response.choices.map((c) => c.message.content ?? "").join("");
+          const result = {
+            content,
+            model: response.model,
+            usage: normalizeUsage5(response.usage),
+            latencyMs: Date.now() - start
+          };
+          const citations = extractCitations(response);
+          if (citations !== void 0) result.citations = citations;
+          return result;
+        } catch (err) {
+          throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
   }
   async function* stream(messages, options) {
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages2(messages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
+    const stallMs = options?.streamStallTimeoutMs ?? config.streamStallTimeoutMs ?? 3e4;
     const extraParams = extractProviderOptions(options?.providerOptions);
     const params = {
       model,
@@ -954,17 +1555,20 @@ function createPerplexityProvider(config) {
     if (maxTokens !== void 0) params.max_tokens = maxTokens;
     const temperature = options?.temperature ?? config.temperature;
     if (temperature !== void 0) params.temperature = temperature;
+    const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
     let sdkStream;
     try {
       sdkStream = await client.chat.completions.create(
-        params
+        params,
+        { signal: ctl.signal }
       );
     } catch (err) {
-      throw normalizePerplexityError(err);
+      ctl.dispose();
+      throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
     }
     let finalUsage;
     try {
-      for await (const chunk of sdkStream) {
+      for await (const chunk of withStallTimeout(sdkStream, stallMs, ctl, PROVIDER5)) {
         const delta = chunk.choices[0]?.delta.content;
         if (delta !== void 0 && delta !== null && delta.length > 0) {
           yield { token: delta };
@@ -974,7 +1578,9 @@ function createPerplexityProvider(config) {
         }
       }
     } catch (err) {
-      throw normalizePerplexityError(err);
+      throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
+    } finally {
+      ctl.dispose();
     }
     if (finalUsage !== void 0) {
       yield { token: "", usage: finalUsage };
@@ -988,28 +1594,37 @@ function createPerplexityProvider(config) {
     const augmentedMessages = [jsonSystemInstruction, ...messages];
     const model = options?.model ?? config.model;
     const chatMessages = buildMessages2(augmentedMessages);
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 3e4;
     const start = Date.now();
     const extraParams = extractProviderOptions(options?.providerOptions);
-    const rawResponse = await withRetry(async () => {
-      try {
-        const params = {
-          model,
-          messages: chatMessages,
-          stream: false,
-          ...extraParams
-        };
-        const maxTokens = options?.maxTokens ?? config.maxTokens;
-        if (maxTokens !== void 0) params.max_tokens = maxTokens;
-        const temperature = options?.temperature ?? config.temperature;
-        if (temperature !== void 0) params.temperature = temperature;
-        return await client.chat.completions.create(
-          params
-        );
-      } catch (err) {
-        throw normalizePerplexityError(err);
-      }
-    }, retryOpts);
-    const rawContent = rawResponse.choices[0]?.message.content ?? "";
+    const rawResponse = await withRetry(
+      async () => {
+        const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+        try {
+          const params = {
+            model,
+            messages: chatMessages,
+            stream: false,
+            ...extraParams
+          };
+          const maxTokens = options?.maxTokens ?? config.maxTokens;
+          if (maxTokens !== void 0) params.max_tokens = maxTokens;
+          const temperature = options?.temperature ?? config.temperature;
+          if (temperature !== void 0) params.temperature = temperature;
+          return await client.chat.completions.create(
+            params,
+            { signal: ctl.signal }
+          );
+        } catch (err) {
+          throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
+        } finally {
+          ctl.dispose();
+        }
+      },
+      mergeRetryOptsWithSignal(retryOpts, options?.signal)
+    );
+    const response = rawResponse;
+    const rawContent = response.choices[0]?.message.content ?? "";
     let parsed;
     try {
       const cleaned = rawContent.replace(/<think>[\s\S]*?<\/think>/i, "").replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
@@ -1033,11 +1648,16 @@ function createPerplexityProvider(config) {
         cause: err
       });
     }
-    return {
+    const citations = extractCitations(response);
+    const result = {
       data,
-      usage: normalizeUsage5(rawResponse.usage),
+      model: response.model,
+      id: response.id,
+      usage: normalizeUsage5(response.usage),
       latencyMs: Date.now() - start
     };
+    if (citations !== void 0) result.citations = citations;
+    return result;
   }
   return {
     config,