@codehz/ai 0.2.0 → 0.2.2

package/src/core/aggregator.ts

@@ -2,11 +2,14 @@
  * 流聚合器
  *
  * 将 AIStreamEvent 序列聚合为统一的 AIResponse。
+ *
  * 职责：
- * - 合并 message.delta / reasoning.delta / tool_call.delta
- * - 合并多次 response.auxiliary 补丁
- * - 生成 output / text / toolCalls
- * - 保持 output 顺序稳定
+ * - 严格 item 状态机：started 创建 active item，delta 累积，completed 构建 OutputItem
+ * - 校验：未 started 的 delta/completed、ID 重用、类型错配、response.completed 时 active items 非空
+ * - 响应级 sequence/responseId/started/completed 校验
+ * - usage/billing/auxiliary 仅来自 response.auxiliary
+ * - warning 仅来自 response.warning
+ * - 最终 AIResponse 由聚合器唯一构建
  *
  * 约束：
  * - replay 由 adapter 显式提供，聚合器不猜测
@@ -25,7 +28,35 @@ import type {
   AuxiliaryInfo,
   BackendTrace,
   StopReason,
+  ContentBlock,
 } from "../types/index.js";
+import { AIStreamError } from "./errors.js";
+import { mergeAuxiliary } from "./merge-auxiliary.js";
+
+// ── Active item types ─────────────────────────────────────────
+
+type ActiveMessage = {
+  type: "message";
+  id: string;
+  role: "assistant";
+  content: ContentBlock[];
+};
+
+type ActiveReasoning = {
+  type: "reasoning";
+  id: string;
+  visibility: "full" | "summary" | "redacted" | "opaque";
+  content: ContentBlock[];
+};
+
+type ActiveToolCall = {
+  type: "tool_call";
+  id: string;
+  name: string;
+  argumentsText: string;
+};
+
+type ActiveItem = ActiveMessage | ActiveReasoning | ActiveToolCall;
 
 // ── 聚合器状态 ────────────────────────────────────────────────
 
@@ -43,12 +74,17 @@ export interface AggregatorState {
   textParts: string[];
   toolCalls: ToolCallItem[];
   lastEventType?: AIStreamEvent["type"];
+  started: boolean;
+  completed: boolean;
+  nextSequence?: number;
+  activeItems: Map<string, ActiveItem>;
+  itemOrder: string[];
+  completedItems: Map<string, OutputItem>;
 
   /** adapter 在 response.completed 中提供的 replay */
   replayFromAdapter?: import("../types/index.js").ReplayItem[];
-  responseIdFromAdapter?: string;
   stopReasonFromAdapter?: StopReason;
-  backendFromAdapter?: BackendTrace;
+  backendFromAdapter?: Partial<BackendTrace>;
 }
 
 export function createAggregatorState(): AggregatorState {
@@ -59,12 +95,61 @@ export function createAggregatorState(): AggregatorState {
     output: [],
     textParts: [],
     toolCalls: [],
+    started: false,
+    completed: false,
+    activeItems: new Map(),
+    itemOrder: [],
+    completedItems: new Map(),
+  };
+}
+
+// ── Active item helpers ───────────────────────────────────────
+
+function getActiveItem(state: AggregatorState, itemId: string, expectedType: ActiveItem["type"]): ActiveItem {
+  const item = state.activeItems.get(itemId);
+  if (!item) {
+    throw streamProtocolError(`Received ${expectedType} delta/completed for unknown item: ${itemId}`);
+  }
+  if (item.type !== expectedType) {
+    throw streamProtocolError(`Item ${itemId} started as ${item.type} but received ${expectedType} event`);
+  }
+  return item;
+}
+
+function finalizeMessage(active: ActiveMessage): MessageItem {
+  return {
+    type: "message",
+    id: active.id,
+    role: active.role,
+    content: active.content,
+  };
+}
+
+function finalizeReasoning(active: ActiveReasoning): import("../types/index.js").ReasoningItem {
+  return {
+    type: "reasoning",
+    id: active.id,
+    visibility: active.visibility,
+    content: active.content,
+  };
+}
+
+function finalizeToolCall(active: ActiveToolCall): ToolCallItem {
+  return {
+    type: "tool_call",
+    id: active.id,
+    name: active.name,
+    argumentsText: active.argumentsText,
   };
 }
 
 // ── Event handlers ────────────────────────────────────────────
 
 function handleResponseStarted(state: AggregatorState, event: AIStreamEvent & { type: "response.started" }): void {
+  if (state.started) {
+    throw streamProtocolError("Stream must contain exactly one response.started event");
+  }
+  state.started = true;
   state.responseId = event.responseId;
   state.model = event.model;
   state.backendInfo = event.backend;
@@ -82,65 +167,132 @@ function handleResponseAuxiliary(state: AggregatorState, event: AIStreamEvent &
     state.billing = { ...state.billing, ...event.billing };
   }
   if (event.auxiliary) {
-    state.auxiliary = mergeAuxiliary(state.auxiliary, event.auxiliary);
+    state.auxiliary = mergeAuxiliary(state.auxiliary, event.auxiliary) ?? {};
   }
 }
 
+function handleMessageStarted(state: AggregatorState, event: AIStreamEvent & { type: "message.started" }): void {
+  const id = event.item.id;
+  if (state.activeItems.has(id)) {
+    throw streamProtocolError(`Item with id ${id} is already active`);
+  }
+  state.activeItems.set(id, {
+    type: "message",
+    id,
+    role: event.item.role,
+    content: [],
+  });
+  state.itemOrder.push(id);
+}
+
+function handleMessageDelta(state: AggregatorState, event: AIStreamEvent & { type: "message.delta" }): void {
+  const active = getActiveItem(state, event.itemId, "message") as ActiveMessage;
+  active.content.push(event.delta);
+}
+
 function handleMessageCompleted(state: AggregatorState, event: AIStreamEvent & { type: "message.completed" }): void {
-  state.output.push(event.item);
-  pushMessageText(state, event.item);
+  const active = getActiveItem(state, event.itemId, "message") as ActiveMessage;
+  state.activeItems.delete(event.itemId);
+  const item = finalizeMessage(active);
+  state.completedItems.set(event.itemId, item);
+  pushMessageText(state, item);
+}
+
+function handleReasoningStarted(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.started" }): void {
+  const id = event.item.id;
+  if (state.activeItems.has(id)) {
+    throw streamProtocolError(`Item with id ${id} is already active`);
+  }
+  state.activeItems.set(id, {
+    type: "reasoning",
+    id,
+    visibility: event.item.visibility,
+    content: [],
+  });
+  state.itemOrder.push(id);
+}
+
+function handleReasoningDelta(state: AggregatorState, event: AIStreamEvent & { type: "reasoning.delta" }): void {
+  const active = getActiveItem(state, event.itemId, "reasoning") as ActiveReasoning;
+  active.content.push(event.delta);
 }
 
 function handleReasoningCompleted(
   state: AggregatorState,
   event: AIStreamEvent & { type: "reasoning.completed" },
 ): void {
-  state.output.push(event.item);
+  const active = getActiveItem(state, event.itemId, "reasoning") as ActiveReasoning;
+  state.activeItems.delete(event.itemId);
+  state.completedItems.set(event.itemId, finalizeReasoning(active));
+}
+
+function handleToolCallStarted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.started" }): void {
+  const id = event.item.id;
+  if (state.activeItems.has(id)) {
+    throw streamProtocolError(`Item with id ${id} is already active`);
+  }
+  state.activeItems.set(id, {
+    type: "tool_call",
+    id,
+    name: event.item.name,
+    argumentsText: "",
+  });
+  state.itemOrder.push(id);
+}
+
+function handleToolCallDelta(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.delta" }): void {
+  const active = getActiveItem(state, event.itemId, "tool_call") as ActiveToolCall;
+  if (event.delta.argumentsText) {
+    active.argumentsText += event.delta.argumentsText;
+  }
 }
 
 function handleToolCallCompleted(state: AggregatorState, event: AIStreamEvent & { type: "tool_call.completed" }): void {
-  state.output.push(event.item);
-  state.toolCalls.push(event.item);
+  const active = getActiveItem(state, event.itemId, "tool_call") as ActiveToolCall;
+  state.activeItems.delete(event.itemId);
+  const item = finalizeToolCall(active);
+  state.completedItems.set(event.itemId, item);
+  state.toolCalls.push(item);
 }
 
 function handleResponseCompleted(state: AggregatorState, event: AIStreamEvent & { type: "response.completed" }): void {
-  state.replayFromAdapter = event.response.replay;
-  state.responseIdFromAdapter = event.response.id;
-  state.stopReasonFromAdapter = event.response.stopReason;
-  state.backendFromAdapter = event.response.backend;
-
-  // 从 response.completed 中提取 usage/billing（适配器可能未发 auxiliary 事件）
-  if (event.response.usage) {
-    state.usage = { ...state.usage, ...event.response.usage };
-  }
-  if (event.response.billing) {
-    state.billing = { ...state.billing, ...event.response.billing };
-  }
-  if (event.response.auxiliary) {
-    state.auxiliary = mergeAuxiliary(state.auxiliary, event.response.auxiliary);
-  }
-  if (event.response.warnings) {
-    pushWarnings(state, event.response.warnings);
+  if (state.activeItems.size > 0) {
+    throw streamProtocolError("response.completed received while active items still pending");
   }
+  state.completed = true;
+  state.replayFromAdapter = event.replay;
+  state.stopReasonFromAdapter = event.stopReason;
+  state.backendFromAdapter = event.trace;
+  if (event.usage) state.usage = { ...state.usage, ...event.usage };
+  if (event.billing) state.billing = { ...state.billing, ...event.billing };
+  if (event.auxiliary) state.auxiliary = mergeAuxiliary(state.auxiliary, event.auxiliary) ?? {};
+  if (event.warnings) pushWarnings(state, event.warnings);
+  if (event.opaqueOutput) state.output.push(...event.opaqueOutput);
 }
 
 // ── 从聚合状态构建最终 AIResponse ─────────────────────────────
 
 function buildResponse(state: AggregatorState): AIResponse {
-  // 合并 backend trace
-  const backendFromResponse = state.backendFromAdapter;
+  const backendFromCompleted = state.backendFromAdapter;
   const backend: BackendTrace = {
-    adapter: backendFromResponse?.adapter ?? state.backendInfo?.kind ?? ("unknown" as BackendTrace["adapter"]),
-    isSyntheticStream: backendFromResponse?.isSyntheticStream ?? state.backendInfo?.isSynthetic ?? false,
-    requestId: backendFromResponse?.requestId ?? state.responseId,
-    rawResponseId: backendFromResponse?.rawResponseId,
-    metadataSources: backendFromResponse?.metadataSources,
-    warnings: backendFromResponse?.warnings,
+    adapter: backendFromCompleted?.adapter ?? state.backendInfo?.kind ?? ("unknown" as BackendTrace["adapter"]),
+    isSyntheticStream: backendFromCompleted?.isSyntheticStream ?? state.backendInfo?.isSynthetic ?? false,
+    requestId: backendFromCompleted?.requestId ?? state.responseId,
+    rawResponseId: backendFromCompleted?.rawResponseId,
+    metadataSources: backendFromCompleted?.metadataSources,
+    warnings: backendFromCompleted?.warnings,
   };
+  const orderedOutput = state.itemOrder.map((id) => {
+    const item = state.completedItems.get(id);
+    if (!item) {
+      throw streamProtocolError(`Item ${id} was started but not completed`);
+    }
+    return item;
+  });
 
   return {
-    id: state.responseIdFromAdapter ?? state.responseId,
-    output: state.output,
+    id: state.responseId,
+    output: [...orderedOutput, ...state.output],
     replay: state.replayFromAdapter ?? [],
     text: state.textParts.join(""),
     toolCalls: state.toolCalls,
@@ -159,7 +311,7 @@ function buildResponse(state: AggregatorState): AIResponse {
  * 将事件数组聚合为 AIResponse。
  * 适用于测试和离线处理场景。
  */
-export function aggregateEvents(events: AIStreamEvent[]): AIResponse {
+export function aggregateEvents(events: readonly AIStreamEvent[]): AIResponse {
   const state = createAggregatorState();
   for (const event of events) {
     aggregateEvent(state, event);
@@ -168,6 +320,7 @@ export function aggregateEvents(events: AIStreamEvent[]): AIResponse {
 }
 
 export function aggregateEvent(state: AggregatorState, event: AIStreamEvent): void {
+  validateEventEnvelope(state, event);
   state.lastEventType = event.type;
 
   switch (event.type) {
@@ -181,18 +334,29 @@ export function aggregateEvent(state: AggregatorState, event: AIStreamEvent): vo
       handleResponseAuxiliary(state, event);
       break;
     case "message.started":
+      handleMessageStarted(state, event);
+      break;
     case "message.delta":
-    case "reasoning.started":
-    case "reasoning.delta":
-    case "tool_call.started":
-    case "tool_call.delta":
+      handleMessageDelta(state, event);
       break;
     case "message.completed":
       handleMessageCompleted(state, event);
       break;
+    case "reasoning.started":
+      handleReasoningStarted(state, event);
+      break;
+    case "reasoning.delta":
+      handleReasoningDelta(state, event);
+      break;
     case "reasoning.completed":
       handleReasoningCompleted(state, event);
       break;
+    case "tool_call.started":
+      handleToolCallStarted(state, event);
+      break;
+    case "tool_call.delta":
+      handleToolCallDelta(state, event);
+      break;
     case "tool_call.completed":
       handleToolCallCompleted(state, event);
       break;
@@ -203,27 +367,14 @@ export function aggregateEvent(state: AggregatorState, event: AIStreamEvent): vo
 }
 
 export function finalizeAggregation(state: AggregatorState): AIResponse {
-  if (state.lastEventType !== "response.completed") {
-    throw new Error("Stream must end with response.completed event to produce a valid AIResponse");
+  if (!state.started) {
+    throw streamProtocolError("Stream must start with response.started event");
   }
-
-  return buildResponse(state);
-}
-
-function mergeAuxiliary(base: AuxiliaryInfo, patch: Partial<AuxiliaryInfo>): AuxiliaryInfo {
-  const merged: AuxiliaryInfo = {
-    ...base,
-    ...patch,
-  };
-
-  if (base.providerMetadata || patch.providerMetadata) {
-    merged.providerMetadata = {
-      ...base.providerMetadata,
-      ...patch.providerMetadata,
-    };
+  if (!state.completed || state.lastEventType !== "response.completed") {
+    throw streamProtocolError("Stream must end with response.completed event to produce a valid AIResponse");
   }
 
-  return merged;
+  return buildResponse(state);
 }
 
 function pushWarnings(state: AggregatorState, warnings: readonly string[]): void {
@@ -242,3 +393,23 @@ function pushMessageText(state: AggregatorState, item: MessageItem): void {
     }
   }
 }
+
+function validateEventEnvelope(state: AggregatorState, event: AIStreamEvent): void {
+  if (state.completed) {
+    throw streamProtocolError("response.completed must be the final stream event");
+  }
+  if (!state.started && event.type !== "response.started") {
+    throw streamProtocolError("Stream must start with response.started event");
+  }
+  if (state.responseId !== undefined && event.responseId !== state.responseId) {
+    throw streamProtocolError("All stream events must use the same responseId");
+  }
+  if (state.nextSequence !== undefined && event.sequence !== state.nextSequence) {
+    throw streamProtocolError(`Expected event sequence ${state.nextSequence}, received ${event.sequence}`);
+  }
+  state.nextSequence = event.sequence + 1;
+}
+
+function streamProtocolError(message: string): AIStreamError {
+  return new AIStreamError(message, "STREAM_PROTOCOL_ERROR");
+}

package/src/core/errors.ts

@@ -40,7 +40,11 @@ export class AIError extends Error {
 
 /** 请求构造失败 — 参数校验不通过。在进入 adapter 前同步抛错。 */
 export class AIRequestError extends AIError {
-  constructor(message: string, code: ErrorCode) {
+  constructor(
+    message: string,
+    code: ErrorCode,
+    public readonly issues?: readonly { field: string; code: string; message: string }[],
+  ) {
     super(message, code, "AIRequestError");
   }
 }
@@ -96,4 +100,6 @@ export const WarningCode = {
   CAPABILITY_DOWNGRADE: "CAPABILITY_DOWNGRADE",
   /** 模拟流式 */
   SYNTHETIC_STREAM: "SYNTHETIC_STREAM",
+  /** 工具调用以批量方式到达（非 token 级流式） */
+  TOOL_CALL_BATCHED: "TOOL_CALL_BATCHED",
 } as const;

package/src/core/event-factory.ts

@@ -19,14 +19,15 @@ import type {
   ToolCallStartedEvent,
   ToolCallDeltaEvent,
   ToolCallCompletedEvent,
-  MessageItem,
-  ReasoningItem,
-  ToolCallItem,
   ContentBlock,
   Usage,
   BillingInfo,
   AuxiliaryInfo,
-  AIResponse,
+  ReplayItem,
+  StopReason,
+  BackendTrace,
+  OpaqueItem,
+  ReasoningItem,
 } from "../types/index.js";
 
 export type EventFactoryBackend = {
@@ -80,8 +81,17 @@ export function createEventFactory(state: EventFactoryState) {
       return { ...base(), type: "response.auxiliary", ...data };
     },
 
-    responseCompleted(response: AIResponse): ResponseCompletedEvent {
-      return { ...base(), type: "response.completed", response };
+    responseCompleted(completion: {
+      replay: ReplayItem[];
+      stopReason?: StopReason;
+      usage?: Usage;
+      billing?: BillingInfo;
+      auxiliary?: AuxiliaryInfo;
+      warnings?: string[];
+      opaqueOutput?: OpaqueItem[];
+      trace?: Partial<BackendTrace>;
+    }): ResponseCompletedEvent {
+      return { ...base(), type: "response.completed", ...completion };
     },
 
     // ── 消息流事件 ──────────────────────────────────────────
@@ -90,12 +100,12 @@ export function createEventFactory(state: EventFactoryState) {
       return { ...base(), type: "message.started", item: { id, role: "assistant" } };
     },
 
-    messageDelta(itemId: string, text: string): MessageDeltaEvent {
-      return { ...base(), type: "message.delta", itemId, delta: { type: "text", text } };
+    messageDelta(itemId: string, delta: ContentBlock): MessageDeltaEvent {
+      return { ...base(), type: "message.delta", itemId, delta };
     },
 
-    messageCompleted(item: MessageItem): MessageCompletedEvent {
-      return { ...base(), type: "message.completed", item };
+    messageCompleted(itemId: string): MessageCompletedEvent {
+      return { ...base(), type: "message.completed", itemId };
     },
 
     // ── 思维链流事件 ────────────────────────────────────────
@@ -108,8 +118,8 @@ export function createEventFactory(state: EventFactoryState) {
       return { ...base(), type: "reasoning.delta", itemId, delta };
     },
 
-    reasoningCompleted(item: ReasoningItem): ReasoningCompletedEvent {
-      return { ...base(), type: "reasoning.completed", item };
+    reasoningCompleted(itemId: string): ReasoningCompletedEvent {
+      return { ...base(), type: "reasoning.completed", itemId };
     },
 
     // ── 工具调用流事件 ──────────────────────────────────────
@@ -122,8 +132,8 @@ export function createEventFactory(state: EventFactoryState) {
       return { ...base(), type: "tool_call.delta", itemId, delta };
     },
 
-    toolCallCompleted(item: ToolCallItem): ToolCallCompletedEvent {
-      return { ...base(), type: "tool_call.completed", item };
+    toolCallCompleted(itemId: string): ToolCallCompletedEvent {
+      return { ...base(), type: "tool_call.completed", itemId };
     },
 
     /** 返回当前已发出的 sequence 计数（用于断言） */

package/src/core/merge-auxiliary.ts

@@ -0,0 +1,22 @@
+import type { AuxiliaryInfo } from "../types/index.js";
+
+export function mergeAuxiliary(
+  base?: Partial<AuxiliaryInfo>,
+  patch?: Partial<AuxiliaryInfo>,
+): AuxiliaryInfo | undefined {
+  if (!base && !patch) return undefined;
+
+  const merged: AuxiliaryInfo = {
+    ...base,
+    ...patch,
+  };
+
+  if (base?.providerMetadata || patch?.providerMetadata) {
+    merged.providerMetadata = {
+      ...base?.providerMetadata,
+      ...patch?.providerMetadata,
+    };
+  }
+
+  return merged;
+}

package/src/core/normalize.ts

@@ -6,7 +6,8 @@
  */
 
 import type { AIRequest, NormalizedRequest } from "../types/index.js";
-import { assertValidRequest } from "./validation.js";
+import { assertValidRequest, validateInclude } from "./validation.js";
+import { AIRequestError } from "./errors.js";
 
 export type NormalizeOptions = {
   model: string;
@@ -29,6 +30,19 @@ const DEFAULT_INCLUDE = {
 export function normalizeRequest(request: AIRequest, options: NormalizeOptions): NormalizedRequest {
   const { model, defaults } = options;
 
+  // 在展开 include 前先校验，防止非法值被合并掩盖
+  const earlyIncludeIssues: { field: string; code: string; message: string }[] = [];
+  if (request.include !== undefined) {
+    validateInclude(request.include, earlyIncludeIssues);
+  }
+  if (defaults?.include !== undefined) {
+    validateInclude(defaults.include, earlyIncludeIssues);
+  }
+  const firstIncludeIssue = earlyIncludeIssues[0];
+  if (firstIncludeIssue) {
+    throw new AIRequestError(firstIncludeIssue.message, firstIncludeIssue.code, earlyIncludeIssues);
+  }
+
   // 合并 defaults（浅合并，input/tools 由 request 完全覆盖）
   const merged: AIRequest = {
     ...defaults,

package/src/core/validation.ts

@@ -226,6 +226,31 @@ function validateToolChoice(toolChoice: unknown, issues: ValidationIssue[]): voi
   }
 }
 
+/** Validate include settings, appending issues to the given array. */
+export function validateInclude(include: unknown, issues: ValidationIssue[]): void {
+  if (!isRecord(include)) {
+    pushIssue(issues, "include", "INCLUDE_INVALID", "include must be an object");
+    return;
+  }
+  if (include.usage !== undefined && (typeof include.usage !== "string" || !INCLUDE_MODES.has(include.usage))) {
+    pushIssue(issues, "include.usage", "INCLUDE_USAGE_INVALID", "include.usage must be off or best_effort");
+  }
+  if (include.billing !== undefined && (typeof include.billing !== "string" || !INCLUDE_MODES.has(include.billing))) {
+    pushIssue(issues, "include.billing", "INCLUDE_BILLING_INVALID", "include.billing must be off or best_effort");
+  }
+  if (
+    include.providerMetadata !== undefined &&
+    (typeof include.providerMetadata !== "string" || !INCLUDE_MODES.has(include.providerMetadata))
+  ) {
+    pushIssue(
+      issues,
+      "include.providerMetadata",
+      "INCLUDE_PROVIDER_METADATA_INVALID",
+      "include.providerMetadata must be off or best_effort",
+    );
+  }
+}
+
 /**
  * 校验 AIRequest，返回校验问题列表。
  * 空数组表示无问题。
@@ -257,7 +282,7 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
 
   // temperature 范围
   if (request.temperature !== undefined) {
-    if (typeof request.temperature !== "number" || isNaN(request.temperature)) {
+    if (typeof request.temperature !== "number" || !Number.isFinite(request.temperature)) {
       issues.push({
         field: "temperature",
         code: "TEMPERATURE_NOT_NUMBER",
@@ -274,7 +299,7 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
 
   // maxOutputTokens 合法性
   if (request.maxOutputTokens !== undefined) {
-    if (typeof request.maxOutputTokens !== "number" || isNaN(request.maxOutputTokens)) {
+    if (typeof request.maxOutputTokens !== "number" || !Number.isFinite(request.maxOutputTokens)) {
       issues.push({
         field: "maxOutputTokens",
         code: "MAX_OUTPUT_TOKENS_NOT_NUMBER",
@@ -290,24 +315,7 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
   }
 
   if (request.include !== undefined) {
-    if (!isRecord(request.include)) {
-      pushIssue(issues, "include", "INCLUDE_INVALID", "include must be an object");
-    } else {
-      if (request.include.usage !== undefined && !INCLUDE_MODES.has(request.include.usage)) {
-        pushIssue(issues, "include.usage", "INCLUDE_USAGE_INVALID", "include.usage must be off or best_effort");
-      }
-      if (request.include.billing !== undefined && !INCLUDE_MODES.has(request.include.billing)) {
-        pushIssue(issues, "include.billing", "INCLUDE_BILLING_INVALID", "include.billing must be off or best_effort");
-      }
-      if (request.include.providerMetadata !== undefined && !INCLUDE_MODES.has(request.include.providerMetadata)) {
-        pushIssue(
-          issues,
-          "include.providerMetadata",
-          "INCLUDE_PROVIDER_METADATA_INVALID",
-          "include.providerMetadata must be off or best_effort",
-        );
-      }
-    }
+    validateInclude(request.include, issues);
   }
 
   if (request.metadata !== undefined) {
@@ -359,6 +367,6 @@ export function assertValidRequest(request: AIRequest): void {
   const issues = validateRequest(request);
   const first = issues[0];
   if (first) {
-    throw new AIRequestError(first.message, first.code);
+    throw new AIRequestError(first.message, first.code, issues);
   }
 }