@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/providers/__tests__/request-timeout-contract.test.ts

@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Mock } from "vitest";
+
+import { anthropicChat } from "../anthropic.ts";
+import { geminiChat } from "../gemini.ts";
+import { deepseekChat } from "../deepseek.ts";
+import { moonshotChat } from "../moonshot.ts";
+import { zaiChat } from "../zhipu.ts";
+import { alibabaChat } from "../alibaba.ts";
+
+/**
+ * Returns a stalled ReadableStream that errors when `signal` aborts. Models a
+ * provider whose connection is open but never produces a chunk — exactly the
+ * condition the IdleTimeoutController is supposed to catch.
+ */
+function stalledBody(signal: AbortSignal | undefined): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (!signal) return;
+      signal.addEventListener(
+        "abort",
+        () => {
+          const reason = signal.reason;
+          controller.error(
+            reason instanceof Error
+              ? reason
+              : new DOMException("The user aborted a request.", "AbortError"),
+          );
+        },
+        { once: true },
+      );
+    },
+  });
+}
+
+const TIMEOUT_MS = 1_000;
+
+const baseMessages = [
+  { role: "system" as const, content: "You are helpful." },
+  { role: "user" as const, content: "Return JSON." },
+];
+
+/**
+ * Drives fake timers forward by exactly `requestTimeoutMs` and asserts the
+ * adapter's promise rejects. The 1ms-step split is what catches a hardcoded
+ * `DEFAULT_REQUEST_TIMEOUT_MS` (3_600_000): advancing by `TIMEOUT_MS - 1` must
+ * leave the promise pending, then crossing the threshold must reject it.
+ *
+ * The promise is never awaited directly — doing so would hang if the adapter
+ * ignored `requestTimeoutMs`. Instead we attach .then handlers and drain
+ * microtasks synchronously.
+ */
+async function expectRejectsAtTimeout(promise: Promise<unknown>): Promise<void> {
+  let state: "pending" | "resolved" | "rejected" = "pending";
+  promise.then(
+    () => {
+      state = "resolved";
+    },
+    () => {
+      state = "rejected";
+    },
+  );
+
+  vi.advanceTimersByTime(TIMEOUT_MS - 1);
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  if (state !== "pending") {
+    throw new Error(
+      `adapter settled before ${TIMEOUT_MS}ms (state=${state}); expected pending`,
+    );
+  }
+
+  vi.advanceTimersByTime(1);
+  for (let i = 0; i < 50; i++) await Promise.resolve();
+
+  if (state === "pending") {
+    throw new Error(
+      `adapter did not apply requestTimeoutMs=${TIMEOUT_MS} (promise still pending after threshold)`,
+    );
+  }
+  if (state === "resolved") {
+    throw new Error("adapter resolved; expected rejection at requestTimeoutMs");
+  }
+}
+
+describe("requestTimeoutMs contract (AC-12)", () => {
+  describe("fetch-based adapters", () => {
+    let originalFetch: typeof globalThis.fetch;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let fetchMock: Mock<(...args: any[]) => any>;
+    let capturedSignal: AbortSignal | undefined;
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+      originalFetch = globalThis.fetch;
+      fetchMock = vi.fn();
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+      capturedSignal = undefined;
+      process.env["ANTHROPIC_API_KEY"] = "test-key";
+      process.env["GEMINI_API_KEY"] = "test-key";
+      process.env["DEEPSEEK_API_KEY"] = "test-key";
+      process.env["MOONSHOT_API_KEY"] = "test-key";
+      process.env["ZAI_API_KEY"] = "test-key";
+      process.env["ALIBABA_API_KEY"] = "test-key";
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      delete process.env["ANTHROPIC_API_KEY"];
+      delete process.env["GEMINI_API_KEY"];
+      delete process.env["DEEPSEEK_API_KEY"];
+      delete process.env["MOONSHOT_API_KEY"];
+      delete process.env["ZAI_API_KEY"];
+      delete process.env["ALIBABA_API_KEY"];
+    });
+
+    function installStalledFetch(): void {
+      fetchMock.mockImplementation(
+        (_url: string, init?: RequestInit) => {
+          const signal = init?.signal ?? undefined;
+          capturedSignal = signal;
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            body: stalledBody(signal),
+          } as unknown as Response);
+        },
+      );
+    }
+
+    it("anthropic applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        anthropicChat({
+          messages: [...baseMessages],
+          responseFormat: "json",
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+
+    it("gemini applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        geminiChat({
+          messages: [...baseMessages],
+          responseFormat: "json",
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+
+    it("deepseek applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        deepseekChat({
+          messages: [...baseMessages],
+          responseFormat: "json",
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+
+    it("moonshot applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        moonshotChat({
+          messages: [...baseMessages],
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+
+    it("zhipu (zaiChat) applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        zaiChat({
+          messages: [...baseMessages],
+          responseFormat: "json",
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+
+    it("alibaba applies requestTimeoutMs to the idle abort", async () => {
+      installStalledFetch();
+
+      await expectRejectsAtTimeout(
+        alibabaChat({
+          messages: [...baseMessages],
+          responseFormat: "json",
+          requestTimeoutMs: TIMEOUT_MS,
+          maxRetries: 0,
+        }),
+      );
+
+      expect(capturedSignal).toBeInstanceOf(AbortSignal);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+  });
+});

package/src/providers/__tests__/stream-accumulator.test.ts

@@ -171,6 +171,36 @@ describe("parseOpenAiSse", () => {
     expect(deltas[0]!.done).toBe(true);
   });
 
+  it("preserves partial usage fields from terminal chunks", async () => {
+    const frames = framesToAsyncIterable([
+      {
+        event: "",
+        data: JSON.stringify({
+          choices: [{ delta: { content: "" }, finish_reason: "stop" }],
+          usage: { prompt_tokens: 10 },
+        }),
+      },
+      { event: "", data: "[DONE]" },
+    ]);
+    const deltas = await collectDeltas(parseOpenAiSse(frames));
+    expect(deltas[0]!.usage).toEqual({ prompt_tokens: 10 });
+  });
+
+  it("preserves total-only usage from terminal chunks", async () => {
+    const frames = framesToAsyncIterable([
+      {
+        event: "",
+        data: JSON.stringify({
+          choices: [{ delta: { content: "" }, finish_reason: "stop" }],
+          usage: { total_tokens: 30 },
+        }),
+      },
+      { event: "", data: "[DONE]" },
+    ]);
+    const deltas = await collectDeltas(parseOpenAiSse(frames));
+    expect(deltas[0]!.usage).toEqual({ total_tokens: 30 });
+  });
+
   it("handles chunks with no content in delta (empty string)", async () => {
     const frames = framesToAsyncIterable([
       { event: "", data: '{"choices":[{"delta":{}}]}' },
@@ -338,6 +368,28 @@ describe("parseGeminiSse", () => {
     });
   });
 
+  it("preserves partial usageMetadata without zero-filling absent fields", async () => {
+    const stream = makeStream([
+      "data: " +
+        JSON.stringify({
+          candidates: [
+            {
+              content: { parts: [{ text: "done" }] },
+              finishReason: "STOP",
+            },
+          ],
+          usageMetadata: {
+            promptTokenCount: 5,
+          },
+        }) +
+        "\n\n",
+    ]);
+    const deltas = await collectDeltas(parseGeminiSse(stream));
+    const final = deltas[deltas.length - 1]!;
+    expect(final.done).toBe(true);
+    expect(final.usage).toEqual({ prompt_tokens: 5 });
+  });
+
   it("handles multi-part candidates", async () => {
     const stream = makeStream([
       "data: " +

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

@@ -3,6 +3,9 @@ import {
   ProviderJsonModeError,
   ProviderJsonParseError,
   type ChatOptions,
+  type LLMRequestCompleteEvent,
+  type LLMRequestErrorEvent,
+  type NormalizedUsage,
   type OpenCodeOptions,
   type OpenCodePermissionAction,
   type OpenCodePermissionConfig,
@@ -10,6 +13,7 @@ import {
   type OpenCodePermissionName,
   type OpenCodePermissionRule,
   type OpenCodeRequestConfig,
+  type UsageSource,
 } from "../types.ts";
 
 describe("ProviderJsonModeError", () => {
@@ -87,6 +91,24 @@ describe("ProviderJsonParseError", () => {
     expect(err.sample).toBe("raw text");
   });
 
+  it("can carry failed JSON response usage for gateway repair accounting", () => {
+    const usage = { prompt_tokens: 3, completion_tokens: 4, total_tokens: 7 };
+    const err = new ProviderJsonParseError(
+      "openai",
+      "gpt-5",
+      "raw text",
+      undefined,
+      {
+        text: "raw text",
+        usage,
+        usageAvailable: true,
+      },
+    );
+    expect(err.text).toBe("raw text");
+    expect(err.usage).toBe(usage);
+    expect(err.usageAvailable).toBe(true);
+  });
+
   it("has name set to ProviderJsonParseError", () => {
     const err = new ProviderJsonParseError("mock", "mock-model", "sample");
     expect(err.name).toBe("ProviderJsonParseError");
@@ -169,3 +191,66 @@ describe("OpenCode types", () => {
     expect(keys).toHaveLength(15);
   });
 });
+
+describe("usage telemetry contracts", () => {
+  it("NormalizedUsage requires a source field", () => {
+    const usage: NormalizedUsage = {
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+      source: "reported",
+    };
+    expect(usage.source).toBe("reported");
+  });
+
+  it("UsageSource accepts all four classification values", () => {
+    const sources: UsageSource[] = [
+      "reported",
+      "estimated",
+      "unavailable",
+      "zero",
+    ];
+    expect(sources).toHaveLength(4);
+  });
+
+  it("LLMRequestCompleteEvent exposes usageSource and costEstimated", () => {
+    const event: LLMRequestCompleteEvent = {
+      id: "llm-1",
+      provider: "openai",
+      model: "gpt-5",
+      metadata: {},
+      timestamp: new Date().toISOString(),
+      duration: 42,
+      promptTokens: 10,
+      completionTokens: 20,
+      totalTokens: 30,
+      cost: 0.001,
+      usageSource: "reported",
+      costEstimated: false,
+    };
+    expect(event.usageSource).toBe("reported");
+    expect(event.costEstimated).toBe(false);
+  });
+
+  it("LLMRequestErrorEvent exposes usage, cost, usageSource, and costEstimated", () => {
+    const event: LLMRequestErrorEvent = {
+      id: "llm-2",
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      metadata: {},
+      timestamp: new Date().toISOString(),
+      duration: 5,
+      error: "rate limited",
+      promptTokens: 15,
+      completionTokens: 0,
+      totalTokens: 15,
+      cost: 0.000045,
+      usageSource: "estimated",
+      costEstimated: true,
+    };
+    expect(event.promptTokens).toBe(15);
+    expect(event.cost).toBe(0.000045);
+    expect(event.usageSource).toBe("estimated");
+    expect(event.costEstimated).toBe(true);
+  });
+});

package/src/providers/__tests__/zero-fill-guard.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { Glob } from "bun";
+
+const FORBIDDEN_PATTERNS = [
+  {
+    name: "ZERO_USAGE constant",
+    regex: /ZERO_USAGE/,
+    regression: "const ZERO_USAGE = { prompt_tokens: 0 }",
+  },
+  {
+    name: "nullish-coalesced zero-fill usage object (?? { <tokens>: 0 ... })",
+    regex: /\?\?\s*\{\s*(?:prompt|completion|total)_tokens\s*:\s*0/,
+    regression: "return { usage: raw ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 } };",
+  },
+  {
+    name: "nullish-coalesced zero on a usage field (<tokens> ?? 0)",
+    regex: /(?:prompt|completion|total|input|output)_tokens\s*\?\?\s*0/,
+    regression: "prompt_tokens: chunk.usage?.prompt_tokens ?? 0,",
+  },
+] as const;
+
+async function listAdapterSources(): Promise<string[]> {
+  const files: string[] = [];
+  for await (const path of new Glob("src/providers/**/*.ts").scan()) {
+    if (path.includes("__tests__")) continue;
+    files.push(path);
+  }
+  return files.sort();
+}
+
+describe("adapter zero-fill guard (AC-1, invariant I-1)", () => {
+  it("forbidden patterns match representative zero-fill snippets (self-test)", () => {
+    for (const { name, regex, regression } of FORBIDDEN_PATTERNS) {
+      expect(regex.test(regression), `${name} should match: ${regression}`).toBe(true);
+    }
+  });
+
+  it("no adapter source under src/providers/ contains a forbidden zero-fill pattern", async () => {
+    const files = await listAdapterSources();
+    expect(files.length).toBeGreaterThan(0);
+
+    const offenders: string[] = [];
+    for (const path of files) {
+      const text = await Bun.file(path).text();
+      for (const { name, regex } of FORBIDDEN_PATTERNS) {
+        if (regex.test(text)) offenders.push(`${path}: ${name}`);
+      }
+    }
+    expect(offenders, `zero-fill patterns returned:\n${offenders.join("\n")}`).toEqual([]);
+  });
+
+  it("src/providers/**/*.ts does not reference usageAvailable except types.ts (invariant I-1, C-2)", async () => {
+    const files = await listAdapterSources();
+    const offenders: string[] = [];
+    for (const path of files) {
+      if (path.endsWith("types.ts")) continue;
+      const text = await Bun.file(path).text();
+      if (text.includes("usageAvailable")) offenders.push(path);
+    }
+    expect(offenders).toEqual([]);
+  });
+});

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

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 import { zaiChat, zhipuChat } from "../zhipu.ts";
-import { ProviderJsonModeError, ProviderJsonParseError } from "../types.ts";
+import { ProviderJsonParseError } from "../types.ts";
 import type { ProviderOptions } from "../types.ts";
 import type { Mock } from "vitest";
 
@@ -272,17 +272,13 @@ describe("zhipuChat", () => {
     });
   });
 
-  it("handles missing usage by defaulting to zeros", async () => {
+  it("returns undefined usage when accumulated stream reports none", async () => {
     const events = makeOpenAiSseEvents([JSON.stringify({ ok: true })]);
     fetchMock.mockResolvedValue(mockStreamingResponse(events));
 
     const result = await zhipuChat(baseOptions);
 
-    expect(result.usage).toEqual({
-      prompt_tokens: 0,
-      completion_tokens: 0,
-      total_tokens: 0,
-    });
+    expect(result.usage).toBeUndefined();
   });
 
   it("throws immediately on 401 without retrying", async () => {
@@ -315,13 +311,30 @@ describe("zhipuChat", () => {
     expect(result.content).toEqual(jsonPayload);
   });
 
-  it("throws ProviderJsonModeError when responseFormat is invalid", async () => {
-    await expect(
-      zhipuChat({
-        ...baseOptions,
-        responseFormat: "text",
-      }),
-    ).rejects.toThrow(ProviderJsonModeError);
+  it("returns plain text content when responseFormat is omitted (AC-13)", async () => {
+    const events = makeOpenAiSseEvents(["not json, just text"]);
+    fetchMock.mockResolvedValue(mockStreamingResponse(events));
+
+    const result = await zhipuChat({
+      messages: [{ role: "user", content: "Give me json output please." }],
+    });
+
+    expect(typeof result.content).toBe("string");
+    expect(result.content).toBe("not json, just text");
+  });
+
+  it("does not set response_format when responseFormat is omitted even if the message says 'json' (AC-13)", async () => {
+    const events = makeOpenAiSseEvents(["ok"]);
+    fetchMock.mockResolvedValue(mockStreamingResponse(events));
+
+    await zhipuChat({
+      messages: [{ role: "user", content: "Return JSON please." }],
+    });
+
+    const body = JSON.parse(
+      (fetchMock.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    expect(body.response_format).toBeUndefined();
   });
 
   it("throws ProviderJsonParseError for non-JSON text in JSON mode", async () => {

package/src/providers/alibaba.ts

@@ -6,6 +6,7 @@ import {
   extractMessages,
   ensureMessagesPresent,
   ensureJsonResponseFormat,
+  isJsonResponseFormat,
   isRetryableError,
   sleep,
   stripMarkdownFences,
@@ -22,7 +23,6 @@ import { ProviderJsonParseError } from "./types.ts";
 import type {
   AlibabaOptions,
   AdapterResponse,
-  ResponseFormatObject,
 } from "./types.ts";
 
 const DEFAULT_MODEL = "qwen-plus";
@@ -30,23 +30,6 @@ const DEFAULT_TEMPERATURE = 0.7;
 const DEFAULT_THINKING: "enabled" | "disabled" = "enabled";
 const DEFAULT_MAX_RETRIES = 3;
 
-/**
- * Determines whether the response format indicates JSON mode.
- * Returns true for "json", "json_object", { type: "json_object" }, { json_schema: ... }.
- */
-function isJsonMode(
-  responseFormat: string | ResponseFormatObject | undefined,
-): boolean {
-  if (!responseFormat) return false;
-  if (typeof responseFormat === "string") {
-    return responseFormat === "json" || responseFormat === "json_object";
-  }
-  return (
-    responseFormat.type === "json_object" ||
-    responseFormat.json_schema != null
-  );
-}
-
 /**
  * Checks whether an error indicates response_format is unsupported in
  * streaming mode.
@@ -100,9 +83,9 @@ async function fetchNonStreaming(
   const data = (await response.json()) as {
     choices: Array<{ message: { content: string } }>;
     usage?: {
-      prompt_tokens: number;
-      completion_tokens: number;
-      total_tokens: number;
+      prompt_tokens?: number | null;
+      completion_tokens?: number | null;
+      total_tokens?: number | null;
     };
   };
 
@@ -117,9 +100,9 @@ function parseResponseData(
   data: {
     choices: Array<{ message: { content: string } }>;
     usage?: {
-      prompt_tokens: number;
-      completion_tokens: number;
-      total_tokens: number;
+      prompt_tokens?: number | null;
+      completion_tokens?: number | null;
+      total_tokens?: number | null;
     };
   },
   jsonMode: boolean,
@@ -134,22 +117,21 @@ function parseResponseData(
       "alibaba",
       model,
       parsed.slice(0, 200),
+      undefined,
+      {
+        text: rawText,
+        usage: data.usage,
+      },
     );
   }
 
-  const usage = data.usage ?? {
-    prompt_tokens: 0,
-    completion_tokens: 0,
-    total_tokens: 0,
-  };
-
   return {
     content:
       typeof parsed === "string"
         ? parsed
         : (parsed as Record<string, unknown>),
     text: rawText,
-    usage,
+    usage: data.usage,
     raw: data,
   };
 }
@@ -174,7 +156,7 @@ export async function alibabaChat(
 
   ensureMessagesPresent(messages, "alibaba");
 
-  const jsonMode = isJsonMode(responseFormat);
+  const jsonMode = isJsonResponseFormat(responseFormat);
 
   const { systemMsg, userMessages, assistantMessages } =
     extractMessages(messages);
@@ -270,22 +252,21 @@ export async function alibabaChat(
           "alibaba",
           model,
           parsed.slice(0, 200),
+          undefined,
+          {
+            text: rawText,
+            usage: accumulated.usage,
+          },
         );
       }
 
-      const usage = accumulated.usage ?? {
-        prompt_tokens: 0,
-        completion_tokens: 0,
-        total_tokens: 0,
-      };
-
       return {
         content:
           typeof parsed === "string"
             ? parsed
             : (parsed as Record<string, unknown>),
         text: rawText,
-        usage,
+        usage: accumulated.usage,
         raw: accumulated,
       };
     } catch (err) {