@codehz/ai 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,978 @@
+//#region src/types/content.d.ts
+/**
+ * ContentBlock — 统一内容块类型
+ *
+ * 覆盖文本、JSON、图片、二进制引用和后端私有内容。
+ */
+type ContentBlock = {
+  type: "text";
+  text: string;
+} | {
+  type: "json";
+  json: unknown;
+} | {
+  type: "image";
+  imageUrl: string;
+} | {
+  type: "binary_ref";
+  ref: string;
+} | {
+  type: "opaque";
+  payload: unknown;
+};
+//#endregion
+//#region src/types/items.d.ts
+type MessageItem = {
+  type: "message";
+  id?: string;
+  role: "user" | "assistant" | "system" | "developer";
+  content: ContentBlock[];
+};
+type ReasoningItem = {
+  type: "reasoning";
+  id?: string;
+  visibility: "full" | "summary" | "redacted" | "opaque";
+  content: ContentBlock[];
+};
+type ToolCallItem = {
+  type: "tool_call";
+  id: string;
+  name: string;
+  argumentsText: string;
+  argumentsJson?: unknown;
+};
+type ToolResultItem = {
+  type: "tool_result";
+  callId: string;
+  toolName: string;
+  outcome: "success" | "error" | "rejected";
+  content: ContentBlock[];
+};
+type OpaqueItem = {
+  type: "opaque";
+  id?: string;
+  source: "responses" | "messages" | "chat.completions" | string;
+  purpose: "replay" | "provider_state" | "unknown";
+  payload: unknown;
+};
+/** 可出现在请求 input 中的 item 类型 */
+type InputItem = MessageItem | ReasoningItem | ToolCallItem | ToolResultItem | OpaqueItem;
+/** 可出现在响应 output 中的 item 类型（不含 ToolResultItem） */
+type OutputItem = MessageItem | ReasoningItem | ToolCallItem | OpaqueItem;
+/** replay 材料的类型等价于 InputItem */
+type ReplayItem = InputItem;
+//#endregion
+//#region src/types/request.d.ts
+type ToolDefinition = {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+};
+type ToolChoice = "auto" | "none" | {
+  type: "tool";
+  name: string;
+};
+type IncludeSettings = {
+  usage?: "off" | "best_effort";
+  billing?: "off" | "best_effort";
+  providerMetadata?: "off" | "best_effort";
+};
+type AIRequest = {
+  instructions?: string | ContentBlock[];
+  input: InputItem[];
+  tools?: ToolDefinition[];
+  toolChoice?: ToolChoice;
+  include?: IncludeSettings;
+  metadata?: Record<string, string>;
+  temperature?: number;
+  maxOutputTokens?: number;
+};
+//#endregion
+//#region src/types/response.d.ts
+type StopReason = "end_turn" | "tool_call" | "max_output_tokens" | "content_filter" | "error" | "unknown";
+type Usage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  totalTokens?: number;
+  cachedInputTokens?: number;
+  cacheWriteInputTokens?: number;
+  billableInputTokens?: number;
+  billableOutputTokens?: number;
+};
+type BillingInfo = {
+  amount?: number;
+  currency?: string;
+  isEstimated: boolean;
+  source: "provider" | "lookup" | "derived" | "unknown";
+  raw?: unknown;
+};
+type AuxiliaryInfo = {
+  usageSource?: "stream" | "final" | "header" | "lookup" | "derived";
+  billingSource?: "stream" | "final" | "header" | "lookup" | "derived";
+  providerUsage?: unknown;
+  providerBilling?: unknown;
+  providerMetadata?: Record<string, unknown>;
+};
+type BackendTrace = {
+  requestId?: string;
+  rawResponseId?: string;
+  adapter: "chat-completions" | "messages" | "responses" | "ollama";
+  isSyntheticStream: boolean;
+  metadataSources?: string[];
+  warnings?: string[];
+};
+type AIResponse = {
+  id?: string;
+  output: OutputItem[];
+  replay: ReplayItem[];
+  text: string;
+  toolCalls: ToolCallItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  warnings?: string[];
+  backend: BackendTrace;
+};
+//#endregion
+//#region src/types/events.d.ts
+type StreamEventBase = {
+  type: string;
+  responseId?: string;
+  sequence: number;
+  timestamp: string;
+  backend: {
+    kind: "chat-completions" | "messages" | "responses" | "ollama";
+    isSynthetic: boolean;
+  };
+};
+type ResponseStartedEvent = StreamEventBase & {
+  type: "response.started";
+  model: string;
+};
+type ResponseWarningEvent = StreamEventBase & {
+  type: "response.warning";
+  message: string;
+  code?: string;
+};
+type ResponseAuxiliaryEvent = StreamEventBase & {
+  type: "response.auxiliary";
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: Partial<AuxiliaryInfo>;
+};
+type ResponseCompletedEvent = StreamEventBase & {
+  type: "response.completed";
+  response: AIResponse;
+};
+type MessageStartedEvent = StreamEventBase & {
+  type: "message.started";
+  item: {
+    id: string;
+    role: "assistant";
+  };
+};
+type MessageDeltaEvent = StreamEventBase & {
+  type: "message.delta";
+  itemId: string;
+  delta: {
+    type: "text";
+    text: string;
+  };
+};
+type MessageCompletedEvent = StreamEventBase & {
+  type: "message.completed";
+  item: MessageItem;
+};
+type ReasoningStartedEvent = StreamEventBase & {
+  type: "reasoning.started";
+  item: {
+    id: string;
+    visibility: "full" | "summary" | "redacted" | "opaque";
+  };
+};
+type ReasoningDeltaEvent = StreamEventBase & {
+  type: "reasoning.delta";
+  itemId: string;
+  delta: ContentBlock;
+};
+type ReasoningCompletedEvent = StreamEventBase & {
+  type: "reasoning.completed";
+  item: ReasoningItem;
+};
+type ToolCallStartedEvent = StreamEventBase & {
+  type: "tool_call.started";
+  item: {
+    id: string;
+    name: string;
+  };
+};
+type ToolCallDeltaEvent = StreamEventBase & {
+  type: "tool_call.delta";
+  itemId: string;
+  delta: {
+    argumentsText?: string;
+  };
+};
+type ToolCallCompletedEvent = StreamEventBase & {
+  type: "tool_call.completed";
+  item: ToolCallItem;
+};
+type AIStreamEvent = ResponseStartedEvent | ResponseWarningEvent | ResponseAuxiliaryEvent | MessageStartedEvent | MessageDeltaEvent | MessageCompletedEvent | ReasoningStartedEvent | ReasoningDeltaEvent | ReasoningCompletedEvent | ToolCallStartedEvent | ToolCallDeltaEvent | ToolCallCompletedEvent | ResponseCompletedEvent;
+//#endregion
+//#region src/types/adapter.d.ts
+/** HTTP fetch 函数签名，用于注入自定义请求实现（测试／代理） */
+type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
+type NormalizedRequest = AIRequest & {
+  model: string;
+  requestId: string;
+};
+type AdapterCapabilities = {
+  nativeStreaming: boolean;
+  messageStreaming: boolean;
+  reasoningStreaming: boolean;
+  toolCallStreaming: boolean;
+  hiddenReasoningReplay: "full" | "partial" | "none";
+  replayFidelity: "high" | "medium" | "low";
+  tools: boolean;
+  usage: "full" | "partial" | "none";
+  billing: "direct" | "lookup" | "derived" | "none";
+  providerMetadata: boolean;
+};
+declare const CAPABILITY_MATRIX: {
+  readonly responses: {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: true;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "full";
+    readonly replayFidelity: "high";
+    readonly tools: true;
+    readonly usage: "full";
+    readonly billing: "lookup";
+    readonly providerMetadata: true;
+  };
+  readonly messages: {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "partial";
+    readonly replayFidelity: "medium";
+    readonly tools: true;
+    readonly usage: "full";
+    readonly billing: "lookup";
+    readonly providerMetadata: true;
+  };
+  readonly "chat.completions": {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: false;
+    readonly hiddenReasoningReplay: "none";
+    readonly replayFidelity: "low";
+    readonly tools: true;
+    readonly usage: "full";
+    readonly billing: "derived";
+    readonly providerMetadata: false;
+  };
+  readonly ollama: {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: false;
+    readonly hiddenReasoningReplay: "none";
+    readonly replayFidelity: "low";
+    readonly tools: true;
+    readonly usage: "partial";
+    readonly billing: "none";
+    readonly providerMetadata: false;
+  };
+};
+interface BackendAdapter {
+  readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  readonly capabilities: AdapterCapabilities;
+  stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+}
+type CreateAIClientOptions = {
+  adapter: BackendAdapter;
+  model: string;
+  defaults?: Partial<AIRequest>;
+};
+interface AIClient {
+  stream(request: AIRequest): AsyncIterable<AIStreamEvent>;
+}
+//#endregion
+//#region src/core/client.d.ts
+declare function createAIClient(options: CreateAIClientOptions): AIClient;
+//#endregion
+//#region src/core/normalize.d.ts
+type NormalizeOptions = {
+  model: string;
+  defaults?: Partial<AIRequest>;
+};
+/**
+ * 归一化请求：
+ * 1. 合并 defaults
+ * 2. 填充 include 默认值
+ * 3. 生成 requestId
+ * 4. 校验请求合法性
+ */
+declare function normalizeRequest(request: AIRequest, options: NormalizeOptions): NormalizedRequest;
+//#endregion
+//#region src/core/validation.d.ts
+type ValidationIssue = {
+  field: string;
+  code: string;
+  message: string;
+};
+/**
+ * 校验 AIRequest，返回校验问题列表。
+ * 空数组表示无问题。
+ */
+declare function validateRequest(request: AIRequest): ValidationIssue[];
+/**
+ * 校验请求并抛出首个问题。
+ * 适用于客户端入口的快速失败检查。
+ */
+declare function assertValidRequest(request: AIRequest): void;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * 公共错误模型
+ *
+ * 把失败、降级、断流三类情况明确区分：
+ * - 致命错误 → 同步抛错或迭代器抛错
+ * - 非致命差异 → warning 通道
+ * - 流中断 → 不伪造 response.completed
+ */
+type ErrorCode = "INPUT_EMPTY" | "TEMPERATURE_OUT_OF_RANGE" | "MAX_OUTPUT_TOKENS_INVALID" | "TOOL_CHOICE_NO_TOOLS" | "TOOL_CHOICE_UNKNOWN_TOOL" | "PROVIDER_ERROR" | "AUTH_ERROR" | "STREAM_ERROR" | "MAPPING_ERROR" | "STREAM_INCOMPLETE" | "LOOKUP_FAILED" | "LOOKUP_TIMEOUT" | string;
+declare class AIError extends Error {
+  readonly code: ErrorCode;
+  readonly name: string;
+  constructor(message: string, code: ErrorCode, name?: string);
+}
+/** 请求构造失败 — 参数校验不通过。在进入 adapter 前同步抛错。 */
+declare class AIRequestError extends AIError {
+  constructor(message: string, code: ErrorCode);
+}
+/** Provider 调用失败 — HTTP 非 2xx、网络错误。由 AdapterBase 捕获转为 warning。 */
+declare class AIProviderError extends AIError {
+  readonly statusCode?: number | undefined;
+  readonly responseBody?: string | undefined;
+  constructor(message: string, code: ErrorCode, statusCode?: number | undefined, responseBody?: string | undefined);
+}
+/** 流协议损坏 — SSE 解析失败、chunk 格式异常。 */
+declare class AIStreamError extends AIError {
+  constructor(message: string, code: ErrorCode);
+}
+/** Canonical 映射失败 — 无法将 provider 响应映射到 canonical 类型。 */
+declare class AIMappingError extends AIError {
+  constructor(message: string, code: ErrorCode);
+}
+/**
+ * 标准 warning 代码列表。
+ * 用于非致命差异的记录。
+ */
+declare const WarningCode: {
+  /** replay fidelity 低于预期 */readonly REPLAY_FIDELITY_LOW: "REPLAY_FIDELITY_LOW"; /** usage 字段缺失 */
+  readonly USAGE_MISSING: "USAGE_MISSING"; /** billing 字段缺失 */
+  readonly BILLING_MISSING: "BILLING_MISSING"; /** billing 只能给估算值 */
+  readonly BILLING_ESTIMATED: "BILLING_ESTIMATED"; /** follow-up lookup 失败 */
+  readonly LOOKUP_FAILED: "LOOKUP_FAILED"; /** lookup 超时 */
+  readonly LOOKUP_TIMEOUT: "LOOKUP_TIMEOUT"; /** 流提前中断 */
+  readonly STREAM_INCOMPLETE: "STREAM_INCOMPLETE"; /** 能力降级 */
+  readonly CAPABILITY_DOWNGRADE: "CAPABILITY_DOWNGRADE"; /** 模拟流式 */
+  readonly SYNTHETIC_STREAM: "SYNTHETIC_STREAM";
+};
+//#endregion
+//#region src/core/event-factory.d.ts
+type EventFactoryBackend = {
+  kind: "chat-completions" | "messages" | "responses" | "ollama";
+  isSynthetic: boolean;
+};
+type EventFactoryState = {
+  responseId: string;
+  backend: EventFactoryBackend;
+};
+declare function createEventFactory(state: EventFactoryState): {
+  responseStarted(model: string): ResponseStartedEvent;
+  responseWarning(message: string, code?: string): ResponseWarningEvent;
+  responseAuxiliary(data: {
+    usage?: Usage;
+    billing?: BillingInfo;
+    auxiliary?: Partial<AuxiliaryInfo>;
+  }): ResponseAuxiliaryEvent;
+  responseCompleted(response: AIResponse): ResponseCompletedEvent;
+  messageStarted(id: string): MessageStartedEvent;
+  messageDelta(itemId: string, text: string): MessageDeltaEvent;
+  messageCompleted(item: MessageItem): MessageCompletedEvent;
+  reasoningStarted(id: string, visibility: ReasoningItem["visibility"]): ReasoningStartedEvent;
+  reasoningDelta(itemId: string, delta: ContentBlock): ReasoningDeltaEvent;
+  reasoningCompleted(item: ReasoningItem): ReasoningCompletedEvent;
+  toolCallStarted(id: string, name: string): ToolCallStartedEvent;
+  toolCallDelta(itemId: string, delta: {
+    argumentsText?: string;
+  }): ToolCallDeltaEvent;
+  toolCallCompleted(item: ToolCallItem): ToolCallCompletedEvent; /** 返回当前已发出的 sequence 计数（用于断言） */
+  readonly sequence: number; /** 返回当前已记录的 warning 副本。 */
+  readonly warnings: string[];
+};
+type EventFactory = ReturnType<typeof createEventFactory>;
+//#endregion
+//#region src/core/aggregator.d.ts
+/**
+ * 将事件数组聚合为 AIResponse。
+ * 适用于测试和离线处理场景。
+ */
+declare function aggregateEvents(events: AIStreamEvent[]): AIResponse;
+//#endregion
+//#region src/core/collect-stream.d.ts
+declare function collectStream(stream: AsyncIterable<AIStreamEvent>): Promise<AIResponse>;
+//#endregion
+//#region src/helpers/auxiliary-collector.d.ts
+type UsageSource = NonNullable<AuxiliaryInfo["usageSource"]>;
+type BillingSource = NonNullable<AuxiliaryInfo["billingSource"]>;
+type LookupResult = {
+  usage?: Partial<Usage>;
+  billing?: Partial<BillingInfo>;
+  providerMetadata?: Record<string, unknown>;
+};
+declare class AuxiliaryCollector {
+  private usage;
+  private usageSource;
+  private billing;
+  private billingSource;
+  private providerMetadata;
+  private providerUsage;
+  private providerBilling;
+  private warnings;
+  private lookupAttempted;
+  /**
+   * 记录 usage 信息。
+   * 后调用的覆盖先调用的（优先级由调用方控制）。
+   */
+  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): this;
+  /**
+   * 记录 billing 信息。
+   * 后调用的覆盖先调用的。
+   */
+  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): this;
+  /**
+   * 记录 provider 元数据（非 canonical 的 key-value 信息）。
+   */
+  recordMetadata(metadata: Record<string, unknown>): this;
+  /**
+   * 记录一条 warning。
+   */
+  recordWarning(message: string): this;
+  /**
+   * 执行一次有界 follow-up lookup。
+   * 最多调用一次；后续调用被忽略。
+   * lookup 失败（抛错）仅记录 warning，不传播异常。
+   */
+  tryLookup(lookupFn: () => Promise<LookupResult>, timeoutMs?: number): Promise<void>;
+  /**
+   * 构建最终的 usage / billing / auxiliary。
+   * 所有字段均为可选的 — 拿不到就不给。
+   */
+  build(): {
+    usage?: Usage;
+    billing?: BillingInfo;
+    auxiliary?: AuxiliaryInfo;
+    warnings?: string[];
+  };
+  /**
+   * 已使用的来源列表（用于 debugging）。
+   */
+  get sources(): {
+    usage?: UsageSource;
+    billing?: BillingSource;
+  };
+}
+//#endregion
+//#region src/helpers/adapter-auxiliary.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type BillingPostprocessHook = (context: {
+  request: NormalizedRequest;
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  capabilities: AdapterCapabilities;
+}) => MaybePromise<Partial<BillingInfo> | undefined>;
+type AuxiliaryFinalizeOptions = {
+  lookup?: () => Promise<LookupResult>;
+  lookupTimeoutMs?: number;
+  postprocessBilling?: BillingPostprocessHook;
+  postprocessBillingSource?: BillingSource;
+};
+type AuxiliaryFinalizeResult = {
+  events: AIStreamEvent[];
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  warnings?: string[];
+  metadataSources?: string[];
+};
+declare class AdapterAuxiliaryState {
+  private readonly request;
+  private readonly capabilities;
+  private readonly collector;
+  private readonly metadataSources;
+  constructor(request: NormalizedRequest, capabilities: AdapterCapabilities);
+  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): void;
+  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): void;
+  recordProviderMetadata(source: string, metadata: Record<string, unknown> | undefined): void;
+  finalize(factory: EventFactory, options?: AuxiliaryFinalizeOptions): Promise<AuxiliaryFinalizeResult>;
+  private shouldAttemptLookup;
+}
+declare function emitMalformedStreamWarning(factory: EventFactory, options: {
+  count: number;
+  providerLabel: string;
+  transportLabel: string;
+}): AIStreamEvent | undefined;
+declare function metadataSourceList(...groups: Array<Array<NonNullable<BackendTrace["metadataSources"]>[number]> | undefined>): string[] | undefined;
+//#endregion
+//#region src/helpers/adapter-base.d.ts
+type ProviderResponse = unknown;
+/**
+ * adapter 完成一轮处理后返回的最终结果。
+ * 用于 buildResponse() 构建 AIResponse。
+ */
+type StreamResult = {
+  output: OutputItem[];
+  replay: ReplayItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  providerMetadata?: Record<string, unknown>;
+  auxiliary?: Partial<AuxiliaryInfo>;
+  warnings?: string[];
+  metadataSources?: string[];
+  rawResponseId?: string;
+};
+declare abstract class AdapterBase implements BackendAdapter {
+  abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  abstract readonly capabilities: AdapterCapabilities;
+  /**
+   * stream 模板方法：
+   * 1. 创建事件工厂，发射 response.started
+   * 2. 构建 provider 请求
+   * 3. 委托 runStream 发射全部流事件（含 response.completed）
+   */
+  stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+  /** 将 NormalizedRequest 转换为 provider 请求格式。 */
+  protected abstract buildRequest(request: NormalizedRequest): ProviderResponse | Promise<ProviderResponse>;
+  /**
+   * 执行流式请求，发射全部事件（含 response.completed）。
+   * 子类负责：
+   * - 调用 provider
+   * - 解析每个 chunk
+   * - 通过 factory 发射 item 事件
+   * - 构建 StreamResult
+   * - 发射 factory.responseCompleted(buildResponse(…))
+   */
+  protected abstract runStream(providerRequest: ProviderResponse, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+  /**
+   * 从 StreamResult 构建完整 AIResponse。
+   * 子类可在返回前自定义覆盖。
+   */
+  protected buildResponse(request: NormalizedRequest, result: StreamResult, _factory: EventFactory): AIResponse;
+  /** 从 output items 中提取文本内容。 */
+  protected extractText(output: OutputItem[]): string;
+  protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState;
+}
+//#endregion
+//#region src/adapters/responses.d.ts
+type ResponsesAdapterOptions = {
+  apiKey: string;
+  baseUrl?: string; /** 可注入自定义 fetch 实现（用于测试／代理） */
+  fetch?: FetchFn;
+};
+type ResponsesAPIRequest = {
+  model: string;
+  input: ResponsesInputItem[];
+  instructions?: string;
+  tools?: ResponsesTool[];
+  tool_choice?: "auto" | "none" | {
+    type: "function";
+    name: string;
+  };
+  metadata?: Record<string, string>;
+  temperature?: number;
+  max_output_tokens?: number;
+  stream: true;
+};
+type ResponsesInputItem = {
+  type: "message";
+  role: "user" | "assistant" | "system" | "developer";
+  content: string;
+} | {
+  type: "message";
+  role: "assistant";
+  content: ResponsesContentBlock[];
+} | {
+  type: "function_call";
+  id: string;
+  name: string;
+  arguments: string;
+  call_id?: string;
+} | {
+  type: "function_call_output";
+  call_id: string;
+  output: string;
+} | {
+  type: "reasoning";
+  content: ResponsesContentBlock[];
+} | {
+  type: "item_reference";
+  id: string;
+};
+type ResponsesContentBlock = {
+  type: "text";
+  text: string;
+} | {
+  type: "reasoning";
+  text: string;
+} | {
+  type: "refusal";
+  refusal: string;
+};
+type ResponsesTool = {
+  type: "function";
+  name: string;
+  description?: string;
+  input_schema: Record<string, unknown>;
+};
+declare class ResponsesAdapter extends AdapterBase {
+  readonly kind: "responses";
+  readonly capabilities: {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: true;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "full";
+    readonly replayFidelity: "high";
+    readonly tools: true;
+    readonly usage: "full";
+    readonly billing: "lookup";
+    readonly providerMetadata: true;
+  };
+  private apiKey;
+  private baseUrl;
+  private fetchFn;
+  constructor(options: ResponsesAdapterOptions);
+  protected buildRequest(request: NormalizedRequest): ResponsesAPIRequest;
+  protected runStream(providerRequest: ResponsesAPIRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+  private inferStopReason;
+}
+//#endregion
+//#region src/adapters/messages.d.ts
+type MessagesAdapterOptions = {
+  apiKey: string;
+  apiVersion?: string;
+  baseUrl?: string; /** 可注入自定义 fetch 实现（用于测试／代理） */
+  fetch?: FetchFn;
+};
+type MessagesAPIRequest = {
+  model: string;
+  max_tokens: number;
+  messages: MessagesAPIMessage[];
+  system?: string;
+  tools?: MessagesAPITool[];
+  tool_choice?: {
+    type: "auto" | "none";
+  } | {
+    type: "tool";
+    name: string;
+  };
+  temperature?: number;
+  thinking?: {
+    type: "enabled";
+    budget_tokens: number;
+  };
+  stream: true;
+};
+type MessagesAPIMessage = {
+  role: "user" | "assistant";
+  content: string | MessagesAPIContentBlock[];
+};
+type MessagesAPIContentBlock = {
+  type: "text";
+  text: string;
+} | {
+  type: "thinking";
+  thinking: string;
+  signature?: string;
+} | {
+  type: "redacted_thinking";
+  data: string;
+} | {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+} | {
+  type: "tool_result";
+  tool_use_id: string;
+  content: string | MessagesAPIContentBlock[];
+  is_error?: boolean;
+};
+type MessagesAPITool = {
+  name: string;
+  description?: string;
+  input_schema: Record<string, unknown>;
+};
+declare class MessagesAdapter extends AdapterBase {
+  readonly kind: "messages";
+  readonly capabilities: {
+    readonly nativeStreaming: true;
+    readonly messageStreaming: true;
+    readonly reasoningStreaming: false;
+    readonly toolCallStreaming: true;
+    readonly hiddenReasoningReplay: "partial";
+    readonly replayFidelity: "medium";
+    readonly tools: true;
+    readonly usage: "full";
+    readonly billing: "lookup";
+    readonly providerMetadata: true;
+  };
+  private apiKey;
+  private apiVersion;
+  private baseUrl;
+  private fetchFn;
+  private warningAccumulator;
+  constructor(options: MessagesAdapterOptions);
+  protected warn(message: string, _code?: string): void;
+  protected buildRequest(request: NormalizedRequest): MessagesAPIRequest;
+  protected runStream(providerRequest: MessagesAPIRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+}
+//#endregion
+//#region src/adapters/chat-completions.d.ts
+type ChatCompletionsAdapterOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  fetch?: FetchFn;
+};
+type ChatRequest = {
+  model: string;
+  messages: ChatMessage[];
+  tools?: ChatTool[];
+  tool_choice?: "auto" | "none" | {
+    type: "function";
+    function: {
+      name: string;
+    };
+  };
+  metadata?: Record<string, string>;
+  temperature?: number;
+  max_tokens?: number;
+  stream: true;
+};
+type ChatMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string | null;
+  tool_calls?: ChatToolCall[];
+  tool_call_id?: string;
+  name?: string;
+  [key: string]: unknown;
+};
+type ChatToolCall = {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+};
+type ChatTool = {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+};
+declare class ChatCompletionsAdapter extends AdapterBase {
+  readonly kind: "chat-completions";
+  readonly capabilities: AdapterCapabilities;
+  private apiKey;
+  private baseUrl;
+  private fetchFn;
+  private markReasoningCompatibility;
+  constructor(options: ChatCompletionsAdapterOptions);
+  protected buildRequest(request: NormalizedRequest): ChatRequest;
+  protected runStream(providerRequest: ChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+}
+//#endregion
+//#region src/adapters/ollama.d.ts
+type OllamaAdapterOptions = {
+  /** Ollama 服务地址，默认 http://localhost:11434 */baseUrl?: string; /** 可选 API key（用于需要认证的代理场景） */
+  apiKey?: string; /** 可注入自定义 fetch 实现 */
+  fetch?: FetchFn;
+};
+type OllamaChatRequest = {
+  model: string;
+  messages: OllamaMessage[];
+  stream: true;
+  tools?: OllamaTool[];
+  options?: {
+    temperature?: number;
+    num_predict?: number;
+    [key: string]: unknown;
+  };
+};
+type OllamaMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  images?: string[];
+  tool_calls?: OllamaToolCall[];
+};
+type OllamaToolCall = {
+  function: {
+    name: string;
+    arguments: Record<string, unknown>;
+  };
+};
+type OllamaTool = {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+};
+declare class OllamaAdapter extends AdapterBase {
+  readonly kind: "ollama";
+  readonly capabilities: AdapterCapabilities;
+  private baseUrl;
+  private apiKey;
+  private fetchFn;
+  constructor(options?: OllamaAdapterOptions);
+  protected buildRequest(request: NormalizedRequest): OllamaChatRequest;
+  protected runStream(providerRequest: OllamaChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+}
+//#endregion
+//#region src/helpers/mapping.d.ts
+declare function mapStopReason(providerReason: string): StopReason;
+declare function mapReasoningVisibility(hasThinking: boolean, hasRedacted: boolean): ReasoningItem["visibility"];
+declare function textBlock(text: string): ContentBlock & {
+  type: "text";
+};
+declare function jsonBlock(json: unknown): ContentBlock & {
+  type: "json";
+};
+declare function imageBlock(imageUrl: string): ContentBlock & {
+  type: "image";
+};
+declare function opaqueBlock(payload: unknown): ContentBlock & {
+  type: "opaque";
+};
+declare function messageItem(content: ContentBlock[], overrides?: Partial<Omit<MessageItem, "type" | "content">>): MessageItem;
+declare function reasoningItem(content: ContentBlock[], visibility?: ReasoningItem["visibility"], id?: string): ReasoningItem;
+declare function toolCallItem(id: string, name: string, argumentsText: string, argumentsJson?: unknown): ToolCallItem;
+declare function toolResultItem(callId: string, toolName: string, outcome: ToolResultItem["outcome"], content: ContentBlock[]): ToolResultItem;
+declare function opaqueItem(source: OpaqueItem["source"], purpose: OpaqueItem["purpose"], payload: unknown, id?: string): OpaqueItem;
+/**
+ * 从 output items 构建标准 replay items。
+ * 简单场景下 replay 与 output 一致。
+ * 复杂场景（需要 opaque continuation）由 adapter 自行扩展。
+ */
+declare function replayFromOutput(output: readonly OutputItem[]): ReplayItem[];
+/**
+ * 将单个 ContentBlock 转为纯文本。
+ * text 块直接返回文本，json 块序列化，其余返回空串。
+ */
+declare function blockToText(b: ContentBlock): string;
+/**
+ * 将 ContentBlock 数组拼接为纯文本，块间以换行符分隔。
+ */
+declare function contentBlocksToText(blocks: ContentBlock[]): string;
+/**
+ * 将 instructions（string | ContentBlock[]）归一化为纯文本。
+ */
+declare function instructionsToText(instructions: string | ContentBlock[]): string;
+/**
+ * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
+ */
+declare function extractText(output: OutputItem[]): string;
+//#endregion
+//#region src/helpers/sse-parser.d.ts
+/**
+ * 通用 SSE (Server-Sent Events) 解析器
+ *
+ * 解析标准 SSE 格式（event: + data: 行），适用于：
+ * - Anthropic Messages API (messages.ts)
+ * - OpenAI Responses API (responses.ts)
+ *
+ * 注意：OpenAI Chat Completions API 使用简化 SSE（仅有 data: 行），
+ * 由 chat-completions.ts 中的 parseChatSSE 处理。
+ *
+ * 用法：
+ * ```ts
+ * const { events, rest } = parseSSEEvents(buffer);
+ * for (const ev of events) {
+ *   // ev.type — 事件类型字符串
+ *   // ev.data — 已解析的 JSON 数据
+ * }
+ * // rest 是未处理的剩余 buffer，需要累积到下次调用
+ * ```
+ */
+type SSEEvent = {
+  type: string;
+  data: unknown;
+};
+type SSEParseResult = {
+  events: SSEEvent[];
+  rest: string;
+  malformedEvents: number;
+};
+/**
+ * 将 SSE 文本块解析为事件数组。
+ * 累积事件行直到遇到空行，支持 [DONE] 标记。
+ * 返回已解析的事件和未处理的剩余 buffer（用于增量解析）。
+ *
+ * 关键行为：
+ * - 只解析完整的 event（以空行结尾）
+ * - 未完成的行保留在 rest 中，等待下次 chunk 补全
+ * - 支持跨 chunk 的 event 分片
+ */
+declare function parseSSEEvents(chunk: string): SSEParseResult;
+//#endregion
+//#region src/helpers/synthetic-stream.d.ts
+type SyntheticStreamOptions = {
+  model: string;
+  responseId: string;
+  backend: {
+    kind: "chat-completions" | "messages" | "responses";
+  };
+  output: OutputItem[];
+  replay?: ReplayItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  providerMetadata?: Record<string, unknown>;
+  rawResponseId?: string;
+  warnings?: string[];
+};
+/**
+ * 将已解析的 output items 包装为完整规范事件流。
+ *
+ * 用法示例（在 adapter 的 runStream 中）：
+ * ```ts
+ * const result = parseNonStreamingResponse(data);
+ * yield* syntheticStream({
+ *   model: request.model,
+ *   responseId: request.requestId,
+ *   backend: { kind: "chat-completions" },
+ *   output: result.output,
+ *   stopReason: result.stopReason,
+ *   usage: result.usage,
+ * });
+ * ```
+ */
+declare function syntheticStream(options: SyntheticStreamOptions): AsyncIterable<AIStreamEvent>;
+//#endregion
+export { type AIClient, AIError, AIMappingError, AIProviderError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, AdapterAuxiliaryState, AdapterBase, type AdapterCapabilities, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, CAPABILITY_MATRIX, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, type InputItem, type LookupResult, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, type NormalizeOptions, type NormalizedRequest, OllamaAdapter, type OllamaAdapterOptions, type OpaqueItem, type OutputItem, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type SSEEvent, type StopReason, type StreamEventBase, type StreamResult, type SyntheticStreamOptions, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type Usage, type UsageSource, type ValidationIssue, WarningCode, aggregateEvents, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, reasoningItem, replayFromOutput, syntheticStream, textBlock, toolCallItem, toolResultItem, validateRequest };
+//# sourceMappingURL=index.d.mts.map