@ryanfw/prompt-orchestration-pipeline 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server/index.ts",

package/src/llm/__tests__/index.test.ts

@@ -514,10 +514,12 @@ describe("LLM Gateway", () => {
 
     it("dispatches to alibaba adapter without unknown-provider error", async () => {
       // Verify the callAdapter dispatch path resolves for provider "alibaba".
-      // The call will fail (no real API key), but NOT with "Unknown provider".
-      await expect(
-        chat({ provider: "alibaba", messages: baseMessages }),
-      ).rejects.not.toThrow(/unknown provider/i);
+      // The call may resolve or reject (no real API key), but NOT with "Unknown provider".
+      try {
+        await chat({ provider: "alibaba", messages: baseMessages });
+      } catch (err: unknown) {
+        expect(String(err)).not.toMatch(/unknown provider/i);
+      }
     });
   });
 

package/src/providers/__tests__/alibaba.test.ts

@@ -158,6 +158,29 @@ describe("alibabaChat", () => {
     expect(body.presence_penalty).toBe(0.2);
   });
 
+  it("passes an AbortSignal to fetch", async () => {
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeAlibabaResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await alibabaChat(baseOptions);
+
+    const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("uses custom requestTimeoutMs for the abort signal", async () => {
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeAlibabaResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await alibabaChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(5000);
+    timeoutSpy.mockRestore();
+  });
+
   it("sends enable_thinking true by default", async () => {
     fetchMock.mockResolvedValue(
       mockFetchResponse(makeAlibabaResponse(JSON.stringify({ ok: true }))),

package/src/providers/__tests__/anthropic.test.ts

@@ -224,6 +224,29 @@ describe("anthropicChat", () => {
     expect(body.stop_sequences).toEqual(["END", "STOP"]);
   });
 
+  it("passes an AbortSignal to fetch", async () => {
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeAnthropicResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await anthropicChat(baseOptions);
+
+    const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("uses custom requestTimeoutMs for the abort signal", async () => {
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeAnthropicResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await anthropicChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(5000);
+    timeoutSpy.mockRestore();
+  });
+
   it("handles markdown-fenced JSON responses", async () => {
     const fencedJson = '```json\n{"fenced": true}\n```';
     fetchMock.mockResolvedValue(

package/src/providers/__tests__/base.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   createProviderError,
+  DEFAULT_REQUEST_TIMEOUT_MS,
   ensureJsonResponseFormat,
   extractMessages,
   isRetryableError,
@@ -155,6 +156,18 @@ describe("isRetryableError", () => {
     });
     expect(isRetryableError(err)).toBe(false);
   });
+
+  it("returns true for TimeoutError (AbortSignal/fetch timeout)", () => {
+    const err = new DOMException("signal timed out", "TimeoutError");
+    expect(err.name).toBe("TimeoutError");
+    expect(isRetryableError(err)).toBe(true);
+  });
+});
+
+describe("DEFAULT_REQUEST_TIMEOUT_MS", () => {
+  it("is 120 000 ms", () => {
+    expect(DEFAULT_REQUEST_TIMEOUT_MS).toBe(120_000);
+  });
 });
 
 describe("sleep", () => {

package/src/providers/__tests__/deepseek.test.ts

@@ -234,6 +234,29 @@ describe("deepseekChat", () => {
       expect(body.frequency_penalty).toBe(0.5);
       expect(body.presence_penalty).toBe(0.2);
     });
+
+    it("passes an AbortSignal to fetch", async () => {
+      fetchMock.mockResolvedValue(
+        mockFetchResponse(makeDeepSeekResponse(JSON.stringify({ ok: true }))),
+      );
+
+      await deepseekChat(baseOptions);
+
+      const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+      expect(init.signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it("uses custom requestTimeoutMs for the abort signal", async () => {
+      const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+      fetchMock.mockResolvedValue(
+        mockFetchResponse(makeDeepSeekResponse(JSON.stringify({ ok: true }))),
+      );
+
+      await deepseekChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+      expect(timeoutSpy).toHaveBeenCalledWith(5000);
+      timeoutSpy.mockRestore();
+    });
   });
 
   describe("streaming", () => {
@@ -286,10 +309,21 @@ describe("deepseekChat", () => {
       );
 
       await expect(
-        deepseekChat({ ...baseOptions, stream: true }),
+        deepseekChat({ ...baseOptions, stream: true, maxRetries: 0 }),
       ).rejects.toMatchObject({ status: 500, message: "Server error" });
     });
 
+    it("normalizes negative maxRetries to zero in streaming mode", async () => {
+      fetchMock.mockResolvedValue(
+        mockFetchResponse({ error: { message: "Server error" } }, 500),
+      );
+
+      await expect(
+        deepseekChat({ ...baseOptions, stream: true, maxRetries: -2 }),
+      ).rejects.toMatchObject({ status: 500, message: "Server error" });
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
     it("skips SSE lines that are comments or empty", async () => {
       const sseEvents = [
         ": this is a comment\n\n",
@@ -313,6 +347,45 @@ describe("deepseekChat", () => {
       expect(chunks).toEqual(["only"]);
     });
 
+    it("retries on timeout then succeeds on second attempt", async () => {
+      const sseEvents = [
+        'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n',
+        "data: [DONE]\n\n",
+      ];
+
+      fetchMock
+        .mockRejectedValueOnce(
+          new DOMException("signal timed out", "TimeoutError"),
+        )
+        .mockResolvedValueOnce(mockStreamingResponse(sseEvents));
+
+      const generator = await deepseekChat({
+        ...baseOptions,
+        stream: true,
+        maxRetries: 1,
+      });
+
+      const chunks: string[] = [];
+      for await (const chunk of generator) {
+        chunks.push(chunk.content);
+      }
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(chunks).toEqual(["ok"]);
+    });
+
+    it("throws immediately on 401 without retrying", async () => {
+      fetchMock.mockResolvedValue(
+        mockFetchResponse({ error: { message: "Unauthorized" } }, 401),
+      );
+
+      await expect(
+        deepseekChat({ ...baseOptions, stream: true, maxRetries: 3 }),
+      ).rejects.toMatchObject({ status: 401, message: "Unauthorized" });
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
     it("skips chunks with no content in delta", async () => {
       const sseEvents = [
         'data: {"choices":[{"delta":{}}]}\n\n',

package/src/providers/__tests__/gemini.test.ts

@@ -345,6 +345,29 @@ describe("geminiChat", () => {
     expect(body.generationConfig.presencePenalty).toBeUndefined();
   });
 
+  it("passes an AbortSignal to fetch", async () => {
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeGeminiResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await geminiChat(baseOptions);
+
+    const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("uses custom requestTimeoutMs for the abort signal", async () => {
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeGeminiResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await geminiChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(5000);
+    timeoutSpy.mockRestore();
+  });
+
   it("handles missing usageMetadata by defaulting to zeros", async () => {
     const jsonPayload = { ok: true };
     const responseWithoutUsage = {

package/src/providers/__tests__/moonshot.test.ts

@@ -360,4 +360,27 @@ describe("moonshotChat", () => {
     const result = await moonshotChat(baseOptions);
     expect(result.content).toEqual({ fenced: true });
   });
+
+  it("passes an AbortSignal to fetch", async () => {
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeMoonshotResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await moonshotChat(baseOptions);
+
+    const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("uses custom requestTimeoutMs for the abort signal", async () => {
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeMoonshotResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await moonshotChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(5000);
+    timeoutSpy.mockRestore();
+  });
 });

package/src/providers/__tests__/openai.test.ts

@@ -297,9 +297,42 @@ describe("openaiChat", () => {
       organization: "org_test",
       baseURL: "https://example.test/v1",
       maxRetries: 0,
+      timeout: 120_000,
     });
   });
 
+  it("constructs the client with custom requestTimeoutMs", async () => {
+    mockChatCompletionsCreate.mockResolvedValue(
+      makeChatCompletion(JSON.stringify({ ok: true })),
+    );
+
+    await openaiChat({
+      ...baseOptions,
+      model: "gpt-4o",
+      requestTimeoutMs: 30_000,
+    });
+
+    expect(MockOpenAI).toHaveBeenCalledWith(
+      expect.objectContaining({ timeout: 30_000 }),
+    );
+  });
+
+  it("creates separate client instances for different timeout values", async () => {
+    mockChatCompletionsCreate.mockResolvedValue(
+      makeChatCompletion(JSON.stringify({ ok: true })),
+    );
+
+    await openaiChat({ ...baseOptions, model: "gpt-4o", requestTimeoutMs: 10_000 });
+    await openaiChat({ ...baseOptions, model: "gpt-4o", requestTimeoutMs: 60_000 });
+
+    // Two distinct timeout values should produce two client constructions
+    const timeouts = MockOpenAI.mock.calls.map(
+      (call: unknown[]) => (call[0] as { timeout: number }).timeout,
+    );
+    expect(timeouts).toContain(10_000);
+    expect(timeouts).toContain(60_000);
+  });
+
   it("passes json_schema to the Responses API when provided", async () => {
     mockResponsesCreate.mockResolvedValue(
       makeResponsesResult(JSON.stringify({ ok: true })),

package/src/providers/__tests__/zhipu.test.ts

@@ -365,6 +365,29 @@ describe("zhipuChat", () => {
     expect(body.stop).toBe("DONE");
   });
 
+  it("passes an AbortSignal to fetch", async () => {
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeZhipuResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await zhipuChat(baseOptions);
+
+    const init = (fetchMock.mock.calls[0] as [string, RequestInit])[1];
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("uses custom requestTimeoutMs for the abort signal", async () => {
+    const timeoutSpy = vi.spyOn(AbortSignal, "timeout");
+    fetchMock.mockResolvedValue(
+      mockFetchResponse(makeZhipuResponse(JSON.stringify({ ok: true }))),
+    );
+
+    await zhipuChat({ ...baseOptions, requestTimeoutMs: 5000 });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(5000);
+    timeoutSpy.mockRestore();
+  });
+
   it("exports zaiChat as the canonical adapter", () => {
     expect(zaiChat).toBe(zhipuChat);
   });

package/src/providers/alibaba.ts

@@ -2,6 +2,7 @@
 // Alibaba (DashScope) adapter using OpenAI-compatible chat completions API.
 
 import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
   extractMessages,
   ensureMessagesPresent,
   ensureJsonResponseFormat,
@@ -52,6 +53,7 @@ export async function alibabaChat(
     topP,
     stop,
     maxRetries = DEFAULT_MAX_RETRIES,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     frequencyPenalty,
     presencePenalty,
     thinking = DEFAULT_THINKING,
@@ -107,6 +109,7 @@ export async function alibabaChat(
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
+      const signal = AbortSignal.timeout(requestTimeoutMs);
       const response = await fetch(endpoint, {
         method: "POST",
         headers: {
@@ -114,6 +117,7 @@ export async function alibabaChat(
           Authorization: `Bearer ${apiKey ?? ""}`,
         },
         body: JSON.stringify(body),
+        signal,
       });
 
       if (!response.ok) {

package/src/providers/anthropic.ts

@@ -2,6 +2,7 @@
 // Anthropic Messages API adapter.
 
 import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
   extractMessages,
   isRetryableError,
   sleep,
@@ -33,6 +34,7 @@ export async function anthropicChat(
     topP,
     stop,
     maxRetries = DEFAULT_MAX_RETRIES,
+    requestTimeoutMs,
   } = options;
 
   // Validate JSON response format — if this throws, we are not in JSON mode
@@ -73,6 +75,7 @@ export async function anthropicChat(
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
+      const signal = AbortSignal.timeout(requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
       const response = await fetch(ANTHROPIC_API_URL, {
         method: "POST",
         headers: {
@@ -81,6 +84,7 @@ export async function anthropicChat(
           "x-api-key": apiKey ?? "",
         },
         body: JSON.stringify(body),
+        signal,
       });
 
       if (!response.ok) {

package/src/providers/base.ts

@@ -4,6 +4,8 @@
 import { ProviderJsonModeError, ProviderMessagesError } from "./types.ts";
 import type { ChatMessage, ExtractedMessages, ProviderError } from "./types.ts";
 
+export const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
 const RETRYABLE_ERROR_CODES = new Set([
   "ECONNRESET",
@@ -66,6 +68,9 @@ export function isRetryableError(err: unknown): boolean {
   // ProviderJsonParseError is never retryable
   if (err.name === "ProviderJsonParseError") return false;
 
+  // Fetch/AbortSignal timeout errors are always retryable
+  if (err.name === "TimeoutError") return true;
+
   // Check HTTP status codes
   const status = (err as { status?: number }).status;
   if (typeof status === "number") {

package/src/providers/deepseek.ts

@@ -2,6 +2,7 @@
 // DeepSeek adapter with streaming support via async generator.
 
 import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
   extractMessages,
   isRetryableError,
   sleep,
@@ -122,10 +123,14 @@ export async function deepseekChat(
     topP,
     stop,
     maxRetries = DEFAULT_MAX_RETRIES,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     frequencyPenalty,
     presencePenalty,
     stream = false,
   } = options;
+  const retryLimit = Number.isFinite(maxRetries)
+    ? Math.max(0, Math.trunc(maxRetries))
+    : DEFAULT_MAX_RETRIES;
 
   const jsonMode = !stream && isJsonMode(responseFormat);
 
@@ -169,43 +174,71 @@ export async function deepseekChat(
     body["response_format"] = responseFormatPayload;
   }
 
-  // Streaming mode: single fetch, return async generator
+  // Streaming mode: retry loop around the initial HTTP request
   if (stream) {
-    const response = await fetch(DEEPSEEK_API_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey ?? ""}`,
-      },
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      let errorBody: unknown;
+    let lastStreamError: unknown;
+
+    for (let attempt = 0; attempt <= retryLimit; attempt++) {
       try {
-        errorBody = await response.json();
-      } catch {
-        errorBody = await response.text();
-      }
-      throw createProviderError(
-        response.status,
-        errorBody,
-        `DeepSeek API error: ${response.status}`,
-      );
-    }
+        const signal = AbortSignal.timeout(requestTimeoutMs);
+        const response = await fetch(DEEPSEEK_API_URL, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey ?? ""}`,
+          },
+          body: JSON.stringify(body),
+          signal,
+        });
+
+        if (!response.ok) {
+          let errorBody: unknown;
+          try {
+            errorBody = await response.json();
+          } catch {
+            errorBody = await response.text();
+          }
+
+          const err = createProviderError(
+            response.status,
+            errorBody,
+            `DeepSeek API error: ${response.status}`,
+          );
 
-    if (!response.body) {
-      throw new Error("DeepSeek streaming response has no body");
+          // 401 is never retried
+          if (response.status === 401) {
+            throw err;
+          }
+
+          throw err;
+        }
+
+        if (!response.body) {
+          throw new Error("DeepSeek streaming response has no body");
+        }
+
+        return parseSSEStream(response.body);
+      } catch (err) {
+        lastStreamError = err;
+
+        if (!isRetryableError(err) || attempt >= retryLimit) {
+          throw err;
+        }
+
+        // Exponential backoff: 2^attempt * 1000ms
+        await sleep(Math.pow(2, attempt) * 1000);
+      }
     }
 
-    return parseSSEStream(response.body);
+    throw lastStreamError;
   }
 
   // Non-streaming mode: retry loop
   let lastError: unknown;
 
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+  for (let attempt = 0; attempt <= retryLimit; attempt++) {
     try {
+      const signal = AbortSignal.timeout(requestTimeoutMs);
       const response = await fetch(DEEPSEEK_API_URL, {
         method: "POST",
         headers: {
@@ -213,6 +246,7 @@ export async function deepseekChat(
           Authorization: `Bearer ${apiKey ?? ""}`,
         },
         body: JSON.stringify(body),
+        signal,
       });
 
       if (!response.ok) {
@@ -278,7 +312,7 @@ export async function deepseekChat(
     } catch (err) {
       lastError = err;
 
-      if (!isRetryableError(err) || attempt >= maxRetries) {
+      if (!isRetryableError(err) || attempt >= retryLimit) {
         throw err;
       }
 

package/src/providers/gemini.ts

@@ -2,6 +2,7 @@
 // Google Gemini GenerateContent adapter.
 
 import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
   extractMessages,
   isRetryableError,
   sleep,
@@ -76,6 +77,7 @@ export async function geminiChat(
     topP,
     stop,
     maxRetries = DEFAULT_MAX_RETRIES,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     // Gemini does not support these — destructure and discard
     frequencyPenalty: _frequencyPenalty,
     presencePenalty: _presencePenalty,
@@ -144,10 +146,12 @@ export async function geminiChat(
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
+      const signal = AbortSignal.timeout(requestTimeoutMs);
       const response = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
+        signal,
       });
 
       if (!response.ok) {

package/src/providers/moonshot.ts

@@ -2,6 +2,7 @@
 // Moonshot adapter with content-filter fallback to DeepSeek.
 
 import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
   extractMessages,
   ensureMessagesPresent,
   isRetryableError,
@@ -40,6 +41,7 @@ export async function moonshotChat(
     thinking = DEFAULT_THINKING,
     maxRetries = DEFAULT_MAX_RETRIES,
     responseFormat,
+    requestTimeoutMs,
   } = options;
 
   ensureMessagesPresent(messages, "moonshot");
@@ -79,6 +81,7 @@ export async function moonshotChat(
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
+      const signal = AbortSignal.timeout(requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
       const response = await fetch(MOONSHOT_API_URL, {
         method: "POST",
         headers: {
@@ -86,6 +89,7 @@ export async function moonshotChat(
           Authorization: `Bearer ${apiKey ?? ""}`,
         },
         body: JSON.stringify(body),
+        signal,
       });
 
       if (!response.ok) {