@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/providers/openai.ts

@@ -10,6 +10,8 @@ import {
   stripMarkdownFences,
   tryParseJSON,
   ensureJsonResponseFormat,
+  isJsonResponseFormat,
+  extractResponseSchema,
 } from "./base.ts";
 import { IdleTimeoutController } from "./stream-accumulator.ts";
 import { ProviderJsonParseError } from "./types.ts";
@@ -18,7 +20,6 @@ import type { Response as OAIResponse } from "openai/resources/responses/respons
 import type { ChatCompletion } from "openai/resources/chat/completions/completions.mjs";
 
 const DEFAULT_MODEL = "gpt-5-chat-latest";
-const DEFAULT_RESPONSE_FORMAT = "json_object";
 const DEFAULT_MAX_RETRIES = 3;
 const GPT5_PATTERN = /^gpt-5/i;
 
@@ -114,15 +115,14 @@ async function callResponsesAPI(
   const stripped = stripMarkdownFences(rawText);
   const parsed = tryParseJSON(stripped);
 
-  // Estimate usage at ~4 chars/token since Responses API may not return usage
-  const inputTokens = response.usage?.input_tokens ?? Math.ceil(userMsg.length / 4);
-  const outputTokens = response.usage?.output_tokens ?? Math.ceil(rawText.length / 4);
-
-  const usage = {
-    prompt_tokens: inputTokens,
-    completion_tokens: outputTokens,
-    total_tokens: inputTokens + outputTokens,
-  };
+  const u = response.usage;
+  const usage: AdapterUsage | undefined = u
+    ? {
+        prompt_tokens: typeof u.input_tokens === "number" ? u.input_tokens : null,
+        completion_tokens: typeof u.output_tokens === "number" ? u.output_tokens : null,
+        total_tokens: typeof u.total_tokens === "number" ? u.total_tokens : null,
+      }
+    : undefined;
 
   return {
     content: typeof parsed === "string" ? parsed : (parsed as Record<string, unknown>),
@@ -161,7 +161,12 @@ async function callChatCompletionsAPI(
     max_tokens: maxTokens,
   };
 
-  if (responseSchema != null || responseFormat === "json_object" || responseFormat === "json") {
+  if (responseSchema != null) {
+    params["response_format"] = {
+      type: "json_schema",
+      json_schema: { name: "Response", schema: responseSchema },
+    };
+  } else if (responseFormat === "json_object" || responseFormat === "json") {
     params["response_format"] = { type: "json_object" };
   }
 
@@ -180,11 +185,14 @@ async function callChatCompletionsAPI(
   const stripped = stripMarkdownFences(rawText);
   const parsed = tryParseJSON(stripped);
 
-  const usage = {
-    prompt_tokens: completion.usage?.prompt_tokens ?? 0,
-    completion_tokens: completion.usage?.completion_tokens ?? 0,
-    total_tokens: completion.usage?.total_tokens ?? 0,
-  };
+  const u = completion.usage;
+  const usage: AdapterUsage | undefined = u
+    ? {
+        prompt_tokens: typeof u.prompt_tokens === "number" ? u.prompt_tokens : null,
+        completion_tokens: typeof u.completion_tokens === "number" ? u.completion_tokens : null,
+        total_tokens: typeof u.total_tokens === "number" ? u.total_tokens : null,
+      }
+    : undefined;
 
   return {
     content: typeof parsed === "string" ? parsed : (parsed as Record<string, unknown>),
@@ -203,6 +211,7 @@ async function callStreamingResponsesAPI(
   maxTokens: number,
   responseFormat: string,
   responseSchema: unknown | undefined,
+  timeoutMs: number,
 ): Promise<AdapterResponse> {
   const params: Record<string, unknown> = {
     model,
@@ -228,7 +237,7 @@ async function callStreamingResponsesAPI(
     params["text"] = { format: { type: "json_object" } };
   }
 
-  const idle = new IdleTimeoutController(DEFAULT_REQUEST_TIMEOUT_MS);
+  const idle = new IdleTimeoutController(timeoutMs);
 
   const stream = await openai.responses.create({
     ...(params as Parameters<typeof openai.responses.create>[0]),
@@ -247,12 +256,19 @@ async function callStreamingResponsesAPI(
         text += (event as { delta?: string }).delta ?? "";
       } else if (type === "response.completed") {
         const resp = event.response as Record<string, unknown> | undefined;
-        const u = resp?.usage as Record<string, number> | undefined;
-        if (u) {
+        const u = resp?.usage as
+          | { input_tokens?: number; output_tokens?: number; total_tokens?: number }
+          | undefined;
+        if (
+          u &&
+          (typeof u.input_tokens === "number" ||
+            typeof u.output_tokens === "number" ||
+            typeof u.total_tokens === "number")
+        ) {
           usage = {
-            prompt_tokens: u.input_tokens ?? 0,
-            completion_tokens: u.output_tokens ?? 0,
-            total_tokens: (u.input_tokens ?? 0) + (u.output_tokens ?? 0),
+            prompt_tokens: typeof u.input_tokens === "number" ? u.input_tokens : null,
+            completion_tokens: typeof u.output_tokens === "number" ? u.output_tokens : null,
+            total_tokens: typeof u.total_tokens === "number" ? u.total_tokens : null,
           };
         }
       }
@@ -261,16 +277,6 @@ async function callStreamingResponsesAPI(
     idle.cleanup();
   }
 
-  if (!usage) {
-    const inputTokens = Math.ceil(userMsg.length / 4);
-    const outputTokens = Math.ceil(text.length / 4);
-    usage = {
-      prompt_tokens: inputTokens,
-      completion_tokens: outputTokens,
-      total_tokens: inputTokens + outputTokens,
-    };
-  }
-
   const stripped = stripMarkdownFences(text);
   const parsed = tryParseJSON(stripped);
 
@@ -295,6 +301,7 @@ async function callStreamingChatCompletionsAPI(
   presencePenalty: number | undefined,
   topP: number | undefined,
   stop: string | string[] | undefined,
+  timeoutMs: number,
 ): Promise<AdapterResponse> {
   const messages: Array<{ role: "system" | "user"; content: string }> = [];
 
@@ -312,7 +319,12 @@ async function callStreamingChatCompletionsAPI(
     stream_options: { include_usage: true },
   };
 
-  if (responseSchema != null || responseFormat === "json_object" || responseFormat === "json") {
+  if (responseSchema != null) {
+    params["response_format"] = {
+      type: "json_schema",
+      json_schema: { name: "Response", schema: responseSchema },
+    };
+  } else if (responseFormat === "json_object" || responseFormat === "json") {
     params["response_format"] = { type: "json_object" };
   }
 
@@ -322,7 +334,7 @@ async function callStreamingChatCompletionsAPI(
   if (topP !== undefined) params["top_p"] = topP;
   if (stop !== undefined) params["stop"] = stop;
 
-  const idle = new IdleTimeoutController(DEFAULT_REQUEST_TIMEOUT_MS);
+  const idle = new IdleTimeoutController(timeoutMs);
 
   const stream = await openai.chat.completions.create({
     ...(params as unknown as Parameters<typeof openai.chat.completions.create>[0]),
@@ -341,12 +353,20 @@ async function callStreamingChatCompletionsAPI(
         | undefined;
       text += choices?.[0]?.delta?.content ?? "";
 
-      const u = chunk.usage as Record<string, number> | undefined;
-      if (u && typeof u.prompt_tokens === "number") {
+      const u = chunk.usage as
+        | { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number }
+        | undefined;
+      if (
+        u &&
+        (typeof u.prompt_tokens === "number" ||
+          typeof u.completion_tokens === "number" ||
+          typeof u.total_tokens === "number")
+      ) {
         usage = {
-          prompt_tokens: u.prompt_tokens,
-          completion_tokens: u.completion_tokens ?? 0,
-          total_tokens: u.total_tokens ?? (u.prompt_tokens + (u.completion_tokens ?? 0)),
+          prompt_tokens: typeof u.prompt_tokens === "number" ? u.prompt_tokens : null,
+          completion_tokens:
+            typeof u.completion_tokens === "number" ? u.completion_tokens : null,
+          total_tokens: typeof u.total_tokens === "number" ? u.total_tokens : null,
         };
       }
     }
@@ -354,10 +374,6 @@ async function callStreamingChatCompletionsAPI(
     idle.cleanup();
   }
 
-  if (!usage) {
-    usage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
-  }
-
   const stripped = stripMarkdownFences(text);
   const parsed = tryParseJSON(stripped);
 
@@ -376,7 +392,7 @@ export async function openaiChat(
     model = DEFAULT_MODEL,
     temperature = 0.7,
     maxTokens = 4096,
-    responseFormat = DEFAULT_RESPONSE_FORMAT,
+    responseFormat,
     maxRetries = DEFAULT_MAX_RETRIES,
     seed,
     frequencyPenalty,
@@ -390,18 +406,16 @@ export async function openaiChat(
     ...rest
   } = options;
 
-  ensureJsonResponseFormat(responseFormat, "openai");
+  const jsonMode = isJsonResponseFormat(responseFormat);
+  if (jsonMode) {
+    ensureJsonResponseFormat(responseFormat, "openai");
+  }
 
   const formatStr =
     typeof responseFormat === "string"
       ? responseFormat
-      : (responseFormat as { type?: string }).type ?? "json_object";
-  const responseSchema =
-    typeof responseFormat === "object" &&
-    responseFormat !== null &&
-    "json_schema" in responseFormat
-      ? (responseFormat as { json_schema?: unknown }).json_schema
-      : undefined;
+      : (responseFormat as { type?: string })?.type ?? "";
+  const responseSchema = extractResponseSchema(responseFormat);
 
   const { systemMsg, userMsg } = extractMessages(messages);
   const timeoutMs = requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -415,18 +429,18 @@ export async function openaiChat(
       if (useResponsesAPI) {
         try {
           const result = await callStreamingResponsesAPI(
-            openai, model, systemMsg, userMsg, temperature, maxTokens, formatStr, responseSchema,
+            openai, model, systemMsg, userMsg, temperature, maxTokens, formatStr, responseSchema, timeoutMs,
           );
-          checkJsonParse(result, model, formatStr);
+          checkJsonParse(result, model, jsonMode);
           return result;
         } catch (responsesErr) {
           // On "unsupported" error, fall back to streaming Chat Completions within same attempt
           if (isUnsupportedError(responsesErr)) {
             const result = await callStreamingChatCompletionsAPI(
               openai, model, systemMsg, userMsg, temperature, maxTokens, formatStr, responseSchema,
-              seed, frequencyPenalty, presencePenalty, topP, stop,
+              seed, frequencyPenalty, presencePenalty, topP, stop, timeoutMs,
             );
-            checkJsonParse(result, model, formatStr);
+            checkJsonParse(result, model, jsonMode);
             return result;
           }
           throw responsesErr;
@@ -435,9 +449,9 @@ export async function openaiChat(
 
       const result = await callStreamingChatCompletionsAPI(
         openai, model, systemMsg, userMsg, temperature, maxTokens, formatStr, responseSchema,
-        seed, frequencyPenalty, presencePenalty, topP, stop,
+        seed, frequencyPenalty, presencePenalty, topP, stop, timeoutMs,
       );
-      checkJsonParse(result, model, formatStr);
+      checkJsonParse(result, model, jsonMode);
       return result;
     } catch (err) {
       lastError = err;
@@ -457,14 +471,18 @@ export async function openaiChat(
 function checkJsonParse(
   result: AdapterResponse,
   model: string,
-  formatStr: string,
+  jsonMode: boolean,
 ): void {
-  const isJsonMode = formatStr === "json" || formatStr === "json_object";
-  if (isJsonMode && typeof result.content === "string") {
+  if (jsonMode && typeof result.content === "string") {
     throw new ProviderJsonParseError(
       "openai",
       model,
       (result.content as string).slice(0, 200),
+      undefined,
+      {
+        text: result.content as string,
+        usage: result.usage,
+      },
     );
   }
 }

package/src/providers/opencode.ts

@@ -5,6 +5,8 @@ import { createOpencodeClient } from "@opencode-ai/sdk/v2";
 import type { OpencodeClient } from "@opencode-ai/sdk/v2";
 import {
   DEFAULT_REQUEST_TIMEOUT_MS,
+  isJsonResponseFormat,
+  extractResponseSchema,
   isRetryableError,
   sleep,
   stripMarkdownFences,
@@ -23,6 +25,9 @@ import type {
   ResponseFormatObject,
 } from "./types.ts";
 
+export const isJsonMode = isJsonResponseFormat;
+export const jsonSchemaFromResponseFormat = extractResponseSchema;
+
 export type ParsedOpenCodeModel =
   | { providerID: string; modelID: string }
   | null;
@@ -65,35 +70,6 @@ export function buildOpenCodePromptText(messages: ChatMessage[]): string {
     .join("\n\n");
 }
 
-export function isJsonMode(
-  responseFormat: string | ResponseFormatObject | undefined,
-): boolean {
-  if (responseFormat === undefined) return false;
-
-  if (typeof responseFormat === "string") {
-    return responseFormat === "json" || responseFormat === "json_object";
-  }
-
-  return (
-    responseFormat.type === "json_object" ||
-    responseFormat.json_schema != null
-  );
-}
-
-export function jsonSchemaFromResponseFormat(
-  responseFormat: string | ResponseFormatObject | undefined,
-): unknown | undefined {
-  if (
-    responseFormat !== undefined &&
-    typeof responseFormat === "object" &&
-    responseFormat.json_schema != null
-  ) {
-    return responseFormat.json_schema;
-  }
-
-  return undefined;
-}
-
 export function defaultOpenCodePermission(): OpenCodePermissionConfig {
   return { "*": "deny" };
 }
@@ -288,11 +264,12 @@ function extractOpenCodeContent(
   raw: unknown,
   responseFormat: string | ResponseFormatObject | undefined,
   model: string,
+  context: { text?: string; usage?: AdapterUsage } = {},
 ): Record<string, unknown> | string {
   const structured = extractOpenCodeStructuredOutput(raw);
   if (structured != null) return structured;
 
-  const text = extractOpenCodeText(raw);
+  const text = context.text ?? extractOpenCodeText(raw);
   const jsonMode = isJsonMode(responseFormat);
 
   if (jsonMode) {
@@ -307,6 +284,11 @@ function extractOpenCodeContent(
       "opencode",
       model || "default",
       cleaned.slice(0, 200),
+      undefined,
+      {
+        text,
+        usage: context.usage,
+      },
     );
   }
 
@@ -469,13 +451,14 @@ export async function opencodeChat(
             }
 
             const raw = result.data;
+            const text = extractOpenCodeText(raw);
+            const usage = normalizeOpenCodeUsage(raw);
             const content = extractOpenCodeContent(
               raw,
               responseFormat,
               modelString,
+              { text, usage },
             );
-            const text = extractOpenCodeText(raw);
-            const usage = normalizeOpenCodeUsage(raw);
 
             return { content, text, usage, raw };
           } catch (err) {
@@ -531,8 +514,8 @@ export async function opencodeChat(
 
       const cliResult = await runOpenCodeCli(args, env, requestTimeoutMs);
       const raw = { events: cliResult.events };
-      const content = extractOpenCodeContent(raw, responseFormat, modelString);
       const text = extractOpenCodeText(raw);
+      const content = extractOpenCodeContent(raw, responseFormat, modelString, { text });
 
       return { content, text, raw };
     } catch (err) {

package/src/providers/stream-accumulator.ts

@@ -175,20 +175,20 @@ export async function* parseOpenAiSse(
 function parseOpenAiUsage(raw: unknown): AdapterUsage | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const u = raw as Record<string, unknown>;
-  if (
-    typeof u.prompt_tokens === "number" &&
-    typeof u.completion_tokens === "number"
-  ) {
-    return {
-      prompt_tokens: u.prompt_tokens,
-      completion_tokens: u.completion_tokens,
-      total_tokens:
-        typeof u.total_tokens === "number"
-          ? u.total_tokens
-          : u.prompt_tokens + u.completion_tokens,
-    };
+  const usage: AdapterUsage = {};
+  const prompt = u.prompt_tokens;
+  const completion = u.completion_tokens;
+  const total = u.total_tokens;
+
+  if (typeof prompt === "number") usage.prompt_tokens = prompt;
+  if (typeof completion === "number") usage.completion_tokens = completion;
+  if (typeof total === "number") {
+    usage.total_tokens = total;
+  } else if (typeof prompt === "number" && typeof completion === "number") {
+    usage.total_tokens = prompt + completion;
   }
-  return undefined;
+
+  return Object.keys(usage).length > 0 ? usage : undefined;
 }
 
 // ─── Step 3: Anthropic event parser ──────────────────────────────────────────
@@ -291,14 +291,20 @@ export async function* parseGeminiSse(
     // Capture usage from usageMetadata (present on final chunk)
     const meta = parsed.usageMetadata as Record<string, unknown> | undefined;
     if (meta) {
-      const prompt = (meta.promptTokenCount as number) ?? 0;
-      const completion = (meta.candidatesTokenCount as number) ?? 0;
-      lastUsage = {
-        prompt_tokens: prompt,
-        completion_tokens: completion,
-        total_tokens:
-          (meta.totalTokenCount as number) ?? prompt + completion,
-      };
+      const prompt = meta.promptTokenCount;
+      const completion = meta.candidatesTokenCount;
+      const total = meta.totalTokenCount;
+      const usage: AdapterUsage = {};
+
+      if (typeof prompt === "number") usage.prompt_tokens = prompt;
+      if (typeof completion === "number") usage.completion_tokens = completion;
+      if (typeof total === "number") {
+        usage.total_tokens = total;
+      } else if (typeof prompt === "number" && typeof completion === "number") {
+        usage.total_tokens = prompt + completion;
+      }
+
+      lastUsage = Object.keys(usage).length > 0 ? usage : undefined;
     }
 
     // Gemini signals completion when candidates have a finishReason

package/src/providers/types.ts

@@ -26,11 +26,15 @@ export interface ProviderOptions {
   requestTimeoutMs?: number;
 }
 
-/** Token usage at the adapter level (snake_case). */
+/** Classification of where a usage figure came from. */
+export type UsageSource = "reported" | "estimated" | "unavailable" | "zero";
+
+/** Token usage at the adapter level (snake_case). Fields are optional/null-tolerant
+ *  because providers may report partial usage or omit fields entirely. */
 export interface AdapterUsage {
-  prompt_tokens: number;
-  completion_tokens: number;
-  total_tokens: number;
+  prompt_tokens?: number | null;
+  completion_tokens?: number | null;
+  total_tokens?: number | null;
 }
 
 /** Response returned by provider adapters. */
@@ -38,6 +42,7 @@ export interface AdapterResponse {
   content: Record<string, unknown> | string;
   text?: string;
   usage?: AdapterUsage;
+  usageAvailable?: boolean;
   raw?: unknown;
 }
 
@@ -51,6 +56,7 @@ export interface NormalizedUsage {
   promptTokens: number;
   completionTokens: number;
   totalTokens: number;
+  source: UsageSource;
 }
 
 /** Response returned by the chat() gateway. */
@@ -209,12 +215,20 @@ export interface LLMRequestCompleteEvent extends LLMRequestStartEvent {
   completionTokens: number;
   totalTokens: number;
   cost: number;
+  usageSource: UsageSource;
+  costEstimated: boolean;
 }
 
 /** Telemetry event: request error. */
 export interface LLMRequestErrorEvent extends LLMRequestStartEvent {
   duration: number;
   error: string;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cost: number;
+  usageSource: UsageSource;
+  costEstimated: boolean;
 }
 
 /** Provider availability map. */
@@ -335,12 +349,20 @@ export class ProviderJsonParseError extends Error {
   provider: string;
   model: string;
   sample: string;
+  text?: string;
+  usage?: AdapterUsage;
+  usageAvailable?: boolean;
 
   constructor(
     provider: string,
     model: string,
     sample: string,
     message?: string,
+    options: {
+      text?: string;
+      usage?: AdapterUsage;
+      usageAvailable?: boolean;
+    } = {},
   ) {
     super(
       message ??
@@ -350,5 +372,8 @@ export class ProviderJsonParseError extends Error {
     this.provider = provider;
     this.model = model;
     this.sample = sample;
+    this.text = options.text;
+    this.usage = options.usage;
+    this.usageAvailable = options.usageAvailable;
   }
 }

package/src/providers/zhipu.ts

@@ -10,6 +10,8 @@ import {
   tryParseJSON,
   createProviderError,
   ensureJsonResponseFormat,
+  isJsonResponseFormat,
+  extractResponseSchema,
 } from "./base.ts";
 import {
   IdleTimeoutController,
@@ -18,43 +20,14 @@ import {
   accumulateStream,
 } from "./stream-accumulator.ts";
 import { ProviderJsonParseError } from "./types.ts";
-import type { ProviderOptions, AdapterResponse, ResponseFormatObject } from "./types.ts";
+import type { ProviderOptions, AdapterResponse } from "./types.ts";
 
 const ZAI_API_URL = "https://api.z.ai/api/paas/v4/chat/completions";
 const DEFAULT_MODEL = "glm-5";
 const DEFAULT_TEMPERATURE = 0.7;
 const DEFAULT_MAX_TOKENS = 8192;
-const DEFAULT_RESPONSE_FORMAT = "json";
 const DEFAULT_MAX_RETRIES = 3;
 
-/** Returns true when responseFormat indicates JSON output. */
-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
-  );
-}
-
-/** Extracts a JSON schema object from responseFormat, if present. */
-function extractJsonSchema(
-  responseFormat: string | ResponseFormatObject | undefined,
-): unknown | undefined {
-  if (
-    responseFormat &&
-    typeof responseFormat === "object" &&
-    responseFormat.json_schema != null
-  ) {
-    return responseFormat.json_schema;
-  }
-  return undefined;
-}
-
 export async function zaiChat(
   options: ProviderOptions,
 ): Promise<AdapterResponse> {
@@ -63,23 +36,22 @@ export async function zaiChat(
     model = DEFAULT_MODEL,
     temperature = DEFAULT_TEMPERATURE,
     maxTokens = DEFAULT_MAX_TOKENS,
-    responseFormat = DEFAULT_RESPONSE_FORMAT,
+    responseFormat,
     topP,
     stop,
     maxRetries = DEFAULT_MAX_RETRIES,
     requestTimeoutMs,
   } = options;
 
-  const jsonMode = isJsonMode(responseFormat);
-
-  // Validate JSON response format
-  ensureJsonResponseFormat(responseFormat, "zai");
+  const jsonMode = isJsonResponseFormat(responseFormat);
+  if (jsonMode) {
+    ensureJsonResponseFormat(responseFormat, "zai");
+  }
 
   const { systemMsg, userMessages, assistantMessages } =
     extractMessages(messages);
 
-  // Build system message with optional JSON schema injection
-  const jsonSchema = extractJsonSchema(responseFormat);
+  const jsonSchema = extractResponseSchema(responseFormat);
   let systemText = systemMsg;
   if (jsonSchema) {
     const schemaStr = JSON.stringify(jsonSchema, null, 2);
@@ -180,19 +152,18 @@ export async function zaiChat(
           "zai",
           model,
           parsed.slice(0, 200),
+          undefined,
+          {
+            text: rawText,
+            usage: accumulated.usage,
+          },
         );
       }
 
-      const usage = {
-        prompt_tokens: accumulated.usage?.prompt_tokens ?? 0,
-        completion_tokens: accumulated.usage?.completion_tokens ?? 0,
-        total_tokens: accumulated.usage?.total_tokens ?? 0,
-      };
-
       return {
         content: typeof parsed === "string" ? parsed : (parsed as Record<string, unknown>),
         text: rawText,
-        usage,
+        usage: accumulated.usage,
         raw: accumulated,
       };
     } catch (err) {