@diabolicallabs/llm-client 0.1.1 → 0.3.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,128 @@ 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";
+    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
+      });
+    case "caller":
+    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/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 +160,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 +197,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 +214,28 @@ 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 +243,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,8 +315,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const params = {
           model,
@@ -179,7 +330,7 @@ function createAnthropicProvider(config) {
         if (temperature !== void 0) {
           params.temperature = temperature;
         }
-        const response = await client.messages.create(params);
+        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,
@@ -188,13 +339,17 @@ function createAnthropicProvider(config) {
           latencyMs: Date.now() - start
         };
       } catch (err) {
-        throw normalizeAnthropicError(err);
+        throw normalizeAnthropicError(classifyAbort(err, ctl.abortReason(), PROVIDER));
+      } finally {
+        ctl.dispose();
       }
-    }, 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 +360,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,7 +385,9 @@ 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 };
@@ -334,8 +499,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const params = {
           model,
@@ -346,7 +513,7 @@ 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 response = await client.chat.completions.create(params);
+        const response = await client.chat.completions.create(params, { signal: ctl.signal });
         const content = response.choices.map((c) => c.message.content ?? "").join("");
         return {
           content,
@@ -355,13 +522,17 @@ function createDeepSeekProvider(config) {
           latencyMs: Date.now() - start
         };
       } catch (err) {
-        throw normalizeDeepSeekError(err);
+        throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, 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 +543,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 +563,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,8 +579,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const params = {
           model,
@@ -416,11 +593,13 @@ function createDeepSeekProvider(config) {
         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);
+        return await client.chat.completions.create(params, { signal: ctl.signal });
       } catch (err) {
-        throw normalizeDeepSeekError(err);
+        throw normalizeDeepSeekError(classifyAbort(err, ctl.abortReason(), PROVIDER2));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, mergeRetryOptsWithSignal(retryOpts, options?.signal));
     const rawContent = rawResponse.choices[0]?.message.content ?? "";
     let parsed;
     try {
@@ -498,11 +677,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,8 +707,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const geminiConfig = {};
         if (system !== void 0) geminiConfig.systemInstruction = system;
@@ -522,11 +718,10 @@ function createGeminiProvider(config) {
         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
-        });
+        const response = await Promise.race([
+          ai.models.generateContent({ model, contents, config: geminiConfig }),
+          makeAbortRacePromise(ctl.signal)
+        ]);
         return {
           content: response.text ?? "",
           model,
@@ -534,32 +729,37 @@ function createGeminiProvider(config) {
           latencyMs: Date.now() - start
         };
       } catch (err) {
-        throw normalizeGeminiError(err);
+        throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, 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,7 +769,9 @@ 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 };
@@ -585,8 +787,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const geminiConfig = {
           // Instruct Gemini to return JSON directly
@@ -597,15 +801,16 @@ function createGeminiProvider(config) {
         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
-        });
+        return await Promise.race([
+          ai.models.generateContent({ model, contents, config: geminiConfig }),
+          makeAbortRacePromise(ctl.signal)
+        ]);
       } catch (err) {
-        throw normalizeGeminiError(err);
+        throw normalizeGeminiError(classifyAbort(err, ctl.abortReason(), PROVIDER3));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, mergeRetryOptsWithSignal(retryOpts, options?.signal));
     const rawContent = rawResponse.text ?? "";
     let parsed;
     try {
@@ -703,8 +908,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const params = {
           model,
@@ -715,7 +922,7 @@ 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 response = await client.chat.completions.create(params);
+        const response = await client.chat.completions.create(params, { signal: ctl.signal });
         const content = response.choices.map((c) => c.message.content ?? "").join("");
         return {
           content,
@@ -724,13 +931,17 @@ function createOpenAIProvider(config) {
           latencyMs: Date.now() - start
         };
       } catch (err) {
-        throw normalizeOpenAIError(err);
+        throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, 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 +952,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,7 +972,9 @@ 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 };
@@ -773,8 +988,10 @@ 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 () => {
+      const ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
       try {
         const params = {
           model,
@@ -786,11 +1003,13 @@ function createOpenAIProvider(config) {
         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);
+        return await client.chat.completions.create(params, { signal: ctl.signal });
       } catch (err) {
-        throw normalizeOpenAIError(err);
+        throw normalizeOpenAIError(classifyAbort(err, ctl.abortReason(), PROVIDER4));
+      } finally {
+        ctl.dispose();
       }
-    }, retryOpts);
+    }, mergeRetryOptsWithSignal(retryOpts, options?.signal));
     const rawContent = rawResponse.choices[0]?.message.content ?? "";
     let parsed;
     try {
@@ -828,39 +1047,241 @@ function createOpenAIProvider(config) {
   };
 }
 
-// src/providers/stubs.ts
-function rejectingStream(err) {
-  const rejected = Promise.reject(err);
-  rejected.catch(() => void 0);
+// src/providers/perplexity.ts
+import OpenAI3 from "openai";
+var PROVIDER5 = "perplexity";
+var PERPLEXITY_BASE_URL = "https://api.perplexity.ai";
+function normalizeUsage5(usage) {
+  const inputTokens = usage?.prompt_tokens ?? 0;
+  const outputTokens = usage?.completion_tokens ?? 0;
   return {
-    next: () => rejected,
-    return: () => Promise.resolve({ value: void 0, done: true }),
-    throw: () => Promise.reject(err),
-    [Symbol.asyncIterator]() {
-      return this;
-    },
-    [Symbol.asyncDispose]: async () => void 0
+    inputTokens,
+    outputTokens,
+    totalTokens: usage?.total_tokens ?? inputTokens + outputTokens
   };
 }
-function notImplemented(provider) {
-  const err = new LlmError({
-    message: `[dlabs-toolkit] Provider '${provider}' is not yet implemented. Anthropic, OpenAI, Gemini, and DeepSeek are available; Perplexity ships in a later week.`,
-    provider,
-    retryable: false
+function buildMessages2(messages) {
+  return messages.map((m) => ({
+    role: m.role,
+    content: m.content
+  }));
+}
+function extractCitations(response) {
+  const rawCitations = response.citations;
+  if (rawCitations === void 0 || rawCitations.length === 0) return void 0;
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const url of rawCitations) {
+    if (!seen.has(url)) {
+      seen.add(url);
+      deduped.push({ url });
+    }
+  }
+  return deduped.length > 0 ? deduped : void 0;
+}
+function extractProviderOptions(providerOptions) {
+  if (providerOptions === void 0) return {};
+  return { ...providerOptions };
+}
+function normalizePerplexityError(err) {
+  if (err instanceof LlmError) return err;
+  if (typeof OpenAI3.APIConnectionError === "function" && err instanceof OpenAI3.APIConnectionError) {
+    return new LlmError({
+      message: err.message,
+      provider: PROVIDER5,
+      retryable: true,
+      cause: err
+    });
+  }
+  if (typeof OpenAI3.APIError === "function" && err instanceof OpenAI3.APIError) {
+    const status = err.status;
+    if (status !== void 0) {
+      const retryable = [429, 502, 503, 504].includes(status) || status >= 500;
+      return new LlmError({
+        message: err.message,
+        provider: PROVIDER5,
+        statusCode: status,
+        retryable,
+        cause: err
+      });
+    }
+    return new LlmError({ message: err.message, provider: PROVIDER5, retryable: false, cause: err });
+  }
+  return normalizeThrownError(err, PROVIDER5);
+}
+function createPerplexityProvider(config) {
+  const client = new OpenAI3({
+    apiKey: config.apiKey,
+    baseURL: PERPLEXITY_BASE_URL,
+    timeout: config.timeoutMs ?? 3e4,
+    maxRetries: 0
+    // Retries managed by withRetry
   });
+  const retryOpts = {
+    maxRetries: config.maxRetries ?? 3,
+    baseDelayMs: config.baseDelayMs ?? 1e3,
+    provider: PROVIDER5
+  };
+  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 () => {
+      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,
+      messages: chatMessages,
+      stream: true,
+      stream_options: { include_usage: true },
+      ...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 ctl = createAttemptController(options?.signal, effectiveTimeoutMs);
+    let sdkStream;
+    try {
+      sdkStream = await client.chat.completions.create(
+        params,
+        { signal: ctl.signal }
+      );
+    } catch (err) {
+      ctl.dispose();
+      throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
+    }
+    let finalUsage;
+    try {
+      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 };
+        }
+        if (chunk.usage !== void 0 && chunk.usage !== null) {
+          finalUsage = normalizeUsage5(chunk.usage);
+        }
+      }
+    } catch (err) {
+      throw normalizePerplexityError(classifyAbort(err, ctl.abortReason(), PROVIDER5));
+    } finally {
+      ctl.dispose();
+    }
+    if (finalUsage !== void 0) {
+      yield { token: "", usage: finalUsage };
+    }
+  }
+  async function structured(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()."
+    };
+    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 () => {
+      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 rawContent = rawResponse.choices[0]?.message.content ?? "";
+    let parsed;
+    try {
+      const cleaned = rawContent.replace(/<think>[\s\S]*?<\/think>/i, "").replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+      parsed = JSON.parse(cleaned);
+    } catch (err) {
+      throw new LlmError({
+        message: `Perplexity structured output: response is not valid JSON. Raw: ${rawContent.slice(0, 200)}`,
+        provider: PROVIDER5,
+        retryable: false,
+        cause: err
+      });
+    }
+    let data;
+    try {
+      data = schema.parse(parsed);
+    } catch (err) {
+      throw new LlmError({
+        message: `Perplexity structured output: response failed schema validation. ${String(err)}`,
+        provider: PROVIDER5,
+        retryable: false,
+        cause: err
+      });
+    }
+    return {
+      data,
+      usage: normalizeUsage5(rawResponse.usage),
+      latencyMs: Date.now() - start
+    };
+  }
   return {
-    get config() {
-      throw err;
-    },
-    complete: () => Promise.reject(err),
-    stream: () => rejectingStream(err),
-    structured: () => Promise.reject(err)
+    config,
+    complete,
+    stream,
+    structured
   };
 }
-function createPerplexityProvider(config) {
-  void config;
-  return notImplemented("perplexity");
-}
 
 // src/client.ts
 function createClient(config) {