@codehz/ai 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -493,7 +493,6 @@ declare function emitMalformedStreamWarning(factory: EventFactory, options: {
   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;
@@ -540,8 +539,11 @@ declare abstract class AdapterBase implements BackendAdapter {
    * 子类可在返回前自定义覆盖。
    */
   protected buildResponse(request: NormalizedRequest, result: StreamResult, _factory: EventFactory): AIResponse;
-  /** 从 output items 中提取文本内容。 */
-  protected extractText(output: OutputItem[]): string;
+  /**
+   * 统一 finalize auxiliary → response.completed。
+   * adapter 在调用前组装 output / replay / stopReason 等业务字段。
+   */
+  protected emitStreamCompleted(factory: EventFactory, request: NormalizedRequest, auxiliary: AdapterAuxiliaryState, result: StreamResult): AsyncIterable<AIStreamEvent>;
   protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState;
 }
 //#endregion
@@ -982,60 +984,11 @@ declare function blockToText(b: ContentBlock): string;
  * 将 ContentBlock 数组拼接为纯文本，块间以换行符分隔。
  */
 declare function contentBlocksToText(blocks: ContentBlock[]): string;
-/**
- * 将 instructions（string | InstructionBlock[]）归一化为纯文本。
- */
-declare function instructionsToText(instructions: string | InstructionBlock[]): 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;
-};
-type ParseSSEOptions = {
-  allowEOF?: boolean;
-};
-/**
- * 将 SSE 文本块解析为事件数组。
- * 累积事件行直到遇到空行，支持 [DONE] 标记。
- * 返回已解析的事件和未处理的剩余 buffer（用于增量解析）。
- *
- * 关键行为：
- * - 只解析完整的 event（以空行结尾）
- * - 未完成的行保留在 rest 中，等待下次 chunk 补全
- * - 支持跨 chunk 的 event 分片
- */
-declare function parseSSEEvents(chunk: string, options?: ParseSSEOptions): SSEParseResult;
-//#endregion
 //#region src/helpers/synthetic-stream.d.ts
 type SyntheticStreamOptions = {
   model: string;
@@ -1173,6 +1126,56 @@ declare class IncrementalStreamParser<T> {
 }
 declare function splitLines(buffer: string, allowEOF: boolean): StreamSplitResult;
 declare function splitSSEFrames(buffer: string, allowEOF: boolean): StreamSplitResult;
+type SseJsonEvent = {
+  type: string;
+  data: unknown;
+};
+/** 解析标准 SSE frame（event: + data:），用于 Messages / Responses。 */
+declare function parseSseJsonFrame(frame: string): StreamParseResult<SseJsonEvent>;
+declare function createSseJsonParser<T extends SseJsonEvent = SseJsonEvent>(): IncrementalStreamParser<T>;
+/** OpenAI Chat Completions 简化 SSE：仅 `data: ...` 行，忽略 `[DONE]`。 */
+declare function parseChatCompletionsDataLine(item: string): StreamParseResult<unknown>;
+declare function createChatCompletionsSseParser<T>(): IncrementalStreamParser<T>;
+/** NDJSON 行解析（Ollama 等）：空行忽略，JSON 失败为 malformed。 */
+declare function createNdjsonLineParser<T>(isValid: (value: unknown) => value is T): IncrementalStreamParser<T>;
+//#endregion
+//#region src/helpers/provider-stream.d.ts
+type OpenProviderJsonStreamOptions = {
+  fetchFn: FetchFn;
+  url: string;
+  headers: Record<string, string>;
+  body: unknown;
+  signal?: AbortSignal;
+};
+type OpenedProviderStream = {
+  reader: ReadableStreamDefaultReader<Uint8Array>;
+  headers: Headers;
+};
+/** POST JSON 并返回可读 body reader + response headers；统一网络/HTTP/空 body 错误。 */
+declare function openProviderJsonStream(options: OpenProviderJsonStreamOptions): Promise<OpenedProviderStream>;
+type ProviderStreamBatchOptions<T> = {
+  reader: ReadableStreamDefaultReader<Uint8Array>;
+  parser: IncrementalStreamParser<T>;
+  factory: EventFactory;
+  providerLabel: string;
+  transportLabel: string;
+  incompleteMessage: string;
+};
+type ProviderStreamBatch<T> = {
+  items: T[];
+  warnings: AIStreamEvent[];
+};
+/**
+ * 读取并解析 provider 流。
+ * 每个 batch 携带本轮解析出的 items 与（可选）malformed / incomplete warning。
+ * 调用方应 `for await` 消费完毕；reader 在迭代结束时 cancel/release。
+ */
+declare function iterateProviderStreamBatches<T>(options: ProviderStreamBatchOptions<T>): AsyncGenerator<ProviderStreamBatch<T>, void, undefined>;
+/** 一次性 complete 守卫：首次成功，后续返回 false。 */
+declare function createCompletionGate(): {
+  readonly completed: boolean;
+  tryComplete(): boolean;
+};
 //#endregion
 //#region src/helpers/request-mapper.d.ts
 declare class NormalizedRequestMapper {
@@ -1183,12 +1186,24 @@ declare class NormalizedRequestMapper {
   ensureReasoningBlocks(blocks: ContentBlock[], field: string): Array<Extract<ContentBlock, {
     type: "text";
   }>>;
+  /** ensureTextBlocks + contentBlocksToText 的常见组合。 */
+  textFromBlocks(blocks: ContentBlock[], field: string): string;
   parseToolArguments(item: ToolCallItem): Record<string, unknown>;
   rollbackTrailingAssistantMessages<T extends {
     role: string;
   }>(messages: T[]): void;
+  mapToolsIfPresent<T>(tools: ToolDefinition[] | undefined, map: (tool: ToolDefinition) => T): T[] | undefined;
+  /**
+   * 将 canonical toolChoice 映射为 provider 形状。
+   * 返回 undefined 表示调用方无需写入 body 字段。
+   */
+  mapToolChoice<T>(toolChoice: ToolChoice | undefined, mappers: {
+    auto: T;
+    none: T;
+    tool: (name: string) => T;
+  }): T | undefined;
   private ensureBlocks;
 }
 //#endregion
-export { type AIClient, AIError, AIMappingError, AIProviderError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, IncrementalStreamParser, type InputItem, type InstructionBlock, type JsonContentBlock, type LookupResult, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockErrorStep, type MockHandler, type MockHandlerContext, type MockHistoryRecord, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockStaticHandler, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockWarningStep, type NormalizeOptions, type NormalizedRequest, NormalizedRequestMapper, OllamaAdapter, type OllamaAdapterOptions, type OpaqueEnvelopeResult, type OpaqueItem, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, 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 StreamParseResult, type StreamResult, type StreamSplitResult, type SyntheticStreamOptions, type TextContentBlock, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type Usage, type UsageSource, type ValidationIssue, WarningCode, aggregateEvents, assertMockRequest, assertOpaqueReplayEnvelope, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createEventFactory, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, instructionsToText, jsonBlock, mapReasoningVisibility, mapStopReason, measureJsonDepth, messageItem, metadataSourceList, normalizeRequest, opaqueBlock, opaqueItem, parseSSEEvents, providerHttpError, reasoningItem, replayFromOutput, splitLines, splitSSEFrames, syntheticStream, textBlock, toolCallItem, toolResultItem, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateOpaqueReplayEnvelope, validateRequest, withMockStreaming };
+export { type AIClient, AIError, AIMappingError, AIProviderError, type AIRequest, AIRequestError, type AIResponse, AIStreamError, type AIStreamEvent, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, type AuxiliaryFinalizeOptions, type AuxiliaryFinalizeResult, type AuxiliaryInfo, type BackendAdapter, type BackendTrace, type BillingInfo, type BillingPostprocessHook, type BillingSource, ChatCompletionsAdapter, type ChatCompletionsAdapterOptions, type ContentBlock, type CreateAIClientOptions, type EventFactory, type EventFactoryBackend, type EventFactoryState, type FetchFn, type IncludeSettings, IncrementalStreamParser, type InputItem, type InstructionBlock, type JsonContentBlock, type LookupResult, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, type MessageCompletedEvent, type MessageDeltaEvent, type MessageItem, type MessageStartedEvent, MessagesAdapter, type MessagesAdapterOptions, MockAdapter, type MockAdapterOptions, type MockAuxiliaryStep, type MockCompleteStep, type MockErrorStep, type MockHandler, type MockHandlerContext, type MockHistoryRecord, type MockInputExpectation, type MockInterruptStep, type MockMessageStep, type MockOutputStep, type MockReasoningStep, type MockRequestExpectation, type MockStaticHandler, type MockStep, type MockTextStreamOptions, type MockThrowStep, type MockToolCallStep, type MockWarningStep, type NormalizeOptions, type NormalizedRequest, NormalizedRequestMapper, OllamaAdapter, type OllamaAdapterOptions, type OpaqueEnvelopeResult, type OpaqueItem, type OpenProviderJsonStreamOptions, type OpenedProviderStream, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, type ProviderStreamBatch, type ProviderStreamBatchOptions, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningStartedEvent, type ReplayItem, type ResponseAuxiliaryEvent, type ResponseCompletedEvent, type ResponseStartedEvent, type ResponseWarningEvent, ResponsesAdapter, type ResponsesAdapterOptions, type SseJsonEvent, type StopReason, type StreamEventBase, type StreamParseResult, type StreamResult, type StreamSplitResult, type SyntheticStreamOptions, type TextContentBlock, type ToolCallCompletedEvent, type ToolCallDeltaEvent, type ToolCallItem, type ToolCallStartedEvent, type ToolChoice, type ToolDefinition, type ToolResultItem, type Usage, type UsageSource, type ValidationIssue, WarningCode, aggregateEvents, assertMockRequest, assertOpaqueReplayEnvelope, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createChatCompletionsSseParser, createCompletionGate, createEventFactory, createNdjsonLineParser, createSseJsonParser, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, iterateProviderStreamBatches, jsonBlock, mapReasoningVisibility, mapStopReason, measureJsonDepth, messageItem, normalizeRequest, opaqueBlock, opaqueItem, openProviderJsonStream, parseChatCompletionsDataLine, parseSseJsonFrame, providerHttpError, reasoningItem, replayFromOutput, splitLines, splitSSEFrames, syntheticStream, textBlock, toolCallItem, toolResultItem, usageFromAnthropicMessages, usageFromChatCompletions, usageFromOllama, usageFromOpenAIResponses, validateOpaqueReplayEnvelope, validateRequest, withMockStreaming };
 //# sourceMappingURL=index.d.mts.map