@codehz/ai 0.4.6 → 0.7.1

package/src/helpers/incremental-stream-parser.ts

@@ -1,142 +0,0 @@
-export type StreamSplitResult = {
-  items: string[];
-  rest: string;
-};
-
-export type StreamParseResult<T> = { status: "parsed"; value: T } | { status: "ignored" } | { status: "malformed" };
-
-export class IncrementalStreamParser<T> {
-  private buffer = "";
-  private readonly decoder = new TextDecoder();
-
-  constructor(
-    private readonly split: (buffer: string, allowEOF: boolean) => StreamSplitResult,
-    private readonly parse: (item: string) => StreamParseResult<T>,
-  ) {}
-
-  feed(value: Uint8Array): { items: T[]; malformed: number } {
-    this.buffer += this.decoder.decode(value, { stream: true });
-    return this.consume(false);
-  }
-
-  flush(): { items: T[]; malformed: number } {
-    this.buffer += this.decoder.decode();
-    return this.consume(true);
-  }
-
-  getRemaining(): string {
-    return this.buffer;
-  }
-
-  private consume(allowEOF: boolean): { items: T[]; malformed: number } {
-    const split = this.split(this.buffer, allowEOF);
-    this.buffer = split.rest;
-    const items: T[] = [];
-    let malformed = 0;
-
-    for (const rawItem of split.items) {
-      const result = this.parse(rawItem);
-      if (result.status === "parsed") items.push(result.value);
-      else if (result.status === "malformed") malformed++;
-    }
-
-    return { items, malformed };
-  }
-}
-
-export function splitLines(buffer: string, allowEOF: boolean): StreamSplitResult {
-  const items: string[] = [];
-  let cursor = 0;
-
-  while (true) {
-    const lineEnd = buffer.indexOf("\n", cursor);
-    if (lineEnd === -1) break;
-    items.push(buffer.slice(cursor, lineEnd));
-    cursor = lineEnd + 1;
-  }
-
-  if (allowEOF && cursor < buffer.length) {
-    items.push(buffer.slice(cursor));
-    cursor = buffer.length;
-  }
-
-  return { items, rest: buffer.slice(cursor) };
-}
-
-export function splitSSEFrames(buffer: string, allowEOF: boolean): StreamSplitResult {
-  const normalized = buffer.replaceAll("\r\n", "\n");
-  const items: string[] = [];
-  let cursor = 0;
-
-  while (true) {
-    const frameEnd = normalized.indexOf("\n\n", cursor);
-    if (frameEnd === -1) break;
-    items.push(normalized.slice(cursor, frameEnd));
-    cursor = frameEnd + 2;
-  }
-
-  if (allowEOF && cursor < normalized.length) {
-    items.push(normalized.slice(cursor));
-    cursor = normalized.length;
-  }
-
-  return { items, rest: normalized.slice(cursor) };
-}
-
-// ── 常用 parse 工厂 ───────────────────────────────────────────
-
-export type SseJsonEvent = { type: string; data: unknown };
-
-/** 解析标准 SSE frame（event: + data:），用于 Messages / Responses。 */
-export function parseSseJsonFrame(frame: string): StreamParseResult<SseJsonEvent> {
-  let eventType = "";
-  let dataStr = "";
-  for (const rawLine of frame.split("\n")) {
-    const line = rawLine.trim();
-    if (line.startsWith("event: ")) eventType = line.slice(7).trim();
-    else if (line.startsWith("data: ")) dataStr += line.slice(6);
-  }
-  if (!eventType) return { status: "ignored" };
-  try {
-    const data: unknown = JSON.parse(dataStr);
-    return { status: "parsed", value: { type: eventType, data } };
-  } catch {
-    return { status: "malformed" };
-  }
-}
-
-export function createSseJsonParser<T extends SseJsonEvent = SseJsonEvent>(): IncrementalStreamParser<T> {
-  return new IncrementalStreamParser(splitSSEFrames, (frame) => parseSseJsonFrame(frame) as StreamParseResult<T>);
-}
-
-/** OpenAI Chat Completions 简化 SSE：仅 `data: ...` 行，忽略 `[DONE]`。 */
-export function parseChatCompletionsDataLine(item: string): StreamParseResult<unknown> {
-  const trimmed = item.trim();
-  if (!trimmed.startsWith("data: ")) return { status: "ignored" };
-  const data = trimmed.slice(6).trim();
-  if (data === "[DONE]") return { status: "ignored" };
-  try {
-    return { status: "parsed", value: JSON.parse(data) as unknown };
-  } catch {
-    return { status: "malformed" };
-  }
-}
-
-export function createChatCompletionsSseParser<T>(): IncrementalStreamParser<T> {
-  return new IncrementalStreamParser(splitLines, (item) => parseChatCompletionsDataLine(item) as StreamParseResult<T>);
-}
-
-/** NDJSON 行解析（Ollama 等）：空行忽略，JSON 失败为 malformed。 */
-export function createNdjsonLineParser<T>(isValid: (value: unknown) => value is T): IncrementalStreamParser<T> {
-  return new IncrementalStreamParser<T>(splitLines, (item: string): StreamParseResult<T> => {
-    const trimmed = item.trim();
-    if (!trimmed) return { status: "ignored" };
-    try {
-      const parsed: unknown = JSON.parse(trimmed);
-      if (isValid(parsed)) return { status: "parsed", value: parsed };
-      return { status: "malformed" };
-    } catch {
-      return { status: "malformed" };
-    }
-  });
-}

package/src/helpers/index.ts

@@ -1,87 +0,0 @@
-/**
- * 共享工具模块
- *
- * 模块边界：adapter 间共享的映射 helper、adapter 基类、模拟流式、辅助信息采集等。
- */
-
-export {
-  mapStopReason,
-  mapReasoningVisibility,
-  textBlock,
-  jsonBlock,
-  imageBlock,
-  opaqueBlock,
-  blockToText,
-  contentBlocksToText,
-  extractText,
-  messageItem,
-  reasoningItem,
-  toolCallItem,
-  toolResultItem,
-  opaqueItem,
-  replayFromOutput,
-} from "./mapping.js";
-
-export { AdapterBase } from "./adapter-base.js";
-export type { StreamResult } from "./adapter-base.js";
-export { AdapterAuxiliaryState, emitMalformedStreamWarning } from "./adapter-auxiliary.js";
-export type { AuxiliaryFinalizeOptions, AuxiliaryFinalizeResult, BillingPostprocessHook } from "./adapter-auxiliary.js";
-export { syntheticStream } from "./synthetic-stream.js";
-export type { SyntheticStreamOptions } from "./synthetic-stream.js";
-export { AuxiliaryCollector } from "./auxiliary-collector.js";
-export type { UsageSource, BillingSource, LookupResult } from "./auxiliary-collector.js";
-export {
-  usageFromAnthropicMessages,
-  usageFromChatCompletions,
-  usageFromOllama,
-  usageFromOpenAIResponses,
-} from "./usage-mapping.js";
-
-export {
-  assertOpaqueReplayEnvelope,
-  extractProviderErrorMessage,
-  measureJsonDepth,
-  providerHttpError,
-  validateOpaqueReplayEnvelope,
-  MAX_OPAQUE_JSON_DEPTH,
-  MAX_OPAQUE_PAYLOAD_BYTES,
-  PROVIDER_ERROR_MESSAGE_MAX_LEN,
-  PROVIDER_ERROR_RAW_BODY_THRESHOLD,
-} from "./adapter-security.js";
-export type { OpaqueEnvelopeResult } from "./adapter-security.js";
-
-export {
-  IncrementalStreamParser,
-  splitLines,
-  splitSSEFrames,
-  parseSseJsonFrame,
-  createSseJsonParser,
-  parseChatCompletionsDataLine,
-  createChatCompletionsSseParser,
-  createNdjsonLineParser,
-} from "./incremental-stream-parser.js";
-export type { StreamSplitResult, StreamParseResult, SseJsonEvent } from "./incremental-stream-parser.js";
-
-export { openProviderJsonStream, iterateProviderStreamBatches, createCompletionGate } from "./provider-stream.js";
-export type {
-  OpenProviderJsonStreamOptions,
-  OpenedProviderStream,
-  ProviderStreamBatch,
-  ProviderStreamBatchOptions,
-} from "./provider-stream.js";
-
-export { mergeProviderHeaders, applyExtraBody } from "./provider-request-options.js";
-
-export {
-  REASONING_LEVELS,
-  REASONING_LEVEL_SET,
-  assertSupportedReasoningLevel,
-  mapResponsesReasoning,
-  mapChatCompletionsReasoningEffort,
-  mapMessagesThinkingBudget,
-  mapMessagesThinking,
-  mapOllamaThink,
-} from "./reasoning-level.js";
-export type { OpenAIReasoningEffort, MessagesThinkingConfig, OllamaThinkValue } from "./reasoning-level.js";
-
-export { NormalizedRequestMapper } from "./request-mapper.js";

package/src/helpers/mapping.ts

@@ -1,192 +0,0 @@
-/**
- * Adapter 共享映射 helper
- *
- * 提供 adapter 间通用的类型映射函数：
- * - stop reason 映射
- * - content block 映射
- * - item 映射
- * - warning 记录
- * - replay 构造工具
- */
-
-import type {
-  StopReason,
-  ContentBlock,
-  MessageItem,
-  ReasoningItem,
-  ToolCallItem,
-  ToolResultItem,
-  OpaqueItem,
-  InputItem,
-  OutputItem,
-  ReplayItem,
-} from "../types/index.js";
-
-// ── Stop reason 映射 ──────────────────────────────────────────
-
-/**
- * 常见 provider stop_reason / finish_reason 到 canonical StopReason 的映射表。
- * adapter 可先查此表，未覆盖时走 fallback 规则。
- */
-const STOP_REASON_MAP: Record<string, StopReason> = {
-  // OpenAI / Azure
-  stop: "end_turn",
-  length: "max_output_tokens",
-  content_filter: "content_filter",
-  tool_calls: "tool_call",
-  // Anthropic
-  end_turn: "end_turn",
-  max_tokens: "max_output_tokens",
-  tool_use: "tool_call",
-  // Generic
-  error: "error",
-};
-
-export function mapStopReason(providerReason: string): StopReason {
-  return STOP_REASON_MAP[providerReason] ?? "unknown";
-}
-
-// ── Reasoning visibility 映射 ──────────────────────────────────
-
-export function mapReasoningVisibility(hasThinking: boolean, hasRedacted: boolean): ReasoningItem["visibility"] {
-  if (hasRedacted) return "redacted";
-  if (hasThinking) return "full";
-  return "opaque";
-}
-
-// ── Content block 构造 helper ─────────────────────────────────
-
-export function textBlock(text: string): ContentBlock & { type: "text" } {
-  return { type: "text", text };
-}
-
-export function jsonBlock(json: unknown): ContentBlock & { type: "json" } {
-  return { type: "json", json };
-}
-
-export function imageBlock(imageUrl: string): ContentBlock & { type: "image" } {
-  return { type: "image", imageUrl };
-}
-
-export function opaqueBlock(payload: unknown): ContentBlock & { type: "opaque" } {
-  return { type: "opaque", payload };
-}
-
-// ── Item 构造 helper ──────────────────────────────────────────
-
-export function messageItem(
-  content: ContentBlock[],
-  overrides?: Partial<Omit<MessageItem, "type" | "content">>,
-): MessageItem {
-  return {
-    type: "message",
-    role: "assistant",
-    ...overrides,
-    content,
-  };
-}
-
-export function reasoningItem(
-  content: ContentBlock[],
-  visibility: ReasoningItem["visibility"] = "full",
-  id?: string,
-): ReasoningItem {
-  return {
-    type: "reasoning",
-    id,
-    visibility,
-    content,
-  };
-}
-
-export function toolCallItem(id: string, name: string, argumentsText: string): ToolCallItem {
-  return {
-    type: "tool_call",
-    id,
-    name,
-    argumentsText,
-  };
-}
-
-export function toolResultItem(
-  callId: string,
-  toolName: string,
-  outcome: ToolResultItem["outcome"],
-  content: ContentBlock[],
-): ToolResultItem {
-  return {
-    type: "tool_result",
-    callId,
-    toolName,
-    outcome,
-    content,
-  };
-}
-
-export function opaqueItem(
-  source: OpaqueItem["source"],
-  purpose: OpaqueItem["purpose"],
-  payload: unknown,
-  id?: string,
-): OpaqueItem {
-  return {
-    type: "opaque",
-    id,
-    source,
-    purpose,
-    payload,
-  };
-}
-
-// ── Replay 构造工具 ──────────────────────────────────────────
-
-/**
- * 从 output items 构建标准 replay items。
- * 简单场景下 replay 与 output 一致。
- * 复杂场景（需要 opaque continuation）由 adapter 自行扩展。
- */
-export function replayFromOutput(output: readonly OutputItem[]): ReplayItem[] {
-  return output.map((item): InputItem => {
-    switch (item.type) {
-      case "message":
-      case "reasoning":
-      case "tool_call":
-        return item as InputItem;
-      case "opaque":
-        return item;
-    }
-  });
-}
-
-// ── Content block 提取 helper ──────────────────────────────────
-
-/**
- * 将单个 ContentBlock 转为纯文本。
- * text 块直接返回文本，json 块序列化，其余返回空串。
- */
-export function blockToText(b: ContentBlock): string {
-  if (b.type === "text") return b.text;
-  if (b.type === "json") return JSON.stringify(b.json);
-  return "";
-}
-
-/**
- * 将 ContentBlock 数组拼接为纯文本，块间以换行符分隔。
- */
-export function contentBlocksToText(blocks: ContentBlock[]): string {
-  return blocks.map(blockToText).join("\n");
-}
-
-// ── Output 文本提取 ───────────────────────────────────────────
-
-/**
- * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
- */
-export function extractText(output: OutputItem[]): string {
-  return output
-    .filter((item): item is MessageItem => item.type === "message")
-    .flatMap((m) => m.content)
-    .filter((b): b is ContentBlock & { type: "text" } => b.type === "text")
-    .map((b) => b.text)
-    .join("");
-}

package/src/helpers/provider-request-options.ts

@@ -1,25 +0,0 @@
-/**
- * Provider 请求 headers / body 扩展合并
- *
- * 供真实后端 adapter 构造选项 `headers` / `extraBody` 使用：
- * - headers：内置鉴权头为基，自定义后写覆盖
- * - extraBody：已构建 body 为基，额外字段浅层 spread，同名顶层键可覆盖
- */
-
-/** 合并内置 headers 与自定义 headers；自定义后写覆盖同名键。 */
-export function mergeProviderHeaders(
-  base: Record<string, string>,
-  custom?: Record<string, string>,
-): Record<string, string> {
-  if (!custom) return base;
-  return { ...base, ...custom };
-}
-
-/**
- * 将构造期 extraBody 浅层合并到已构建的 provider body。
- * 无 extraBody 时原样返回；有则允许覆盖同名顶层键。
- */
-export function applyExtraBody<T extends object>(body: T, extraBody?: Record<string, unknown>): T {
-  if (!extraBody) return body;
-  return { ...body, ...extraBody };
-}

package/src/helpers/provider-stream.ts

@@ -1,147 +0,0 @@
-/**
- * Provider HTTP 流公共脚手架
- *
- * 收敛 adapter 间重复的：
- * - JSON POST + 错误映射
- * - ReadableStream reader 生命周期
- * - IncrementalStreamParser feed/flush + malformed warning
- * - 不完整尾帧 warning
- */
-
-import { AIProviderError, AIStreamError } from "../core/errors.js";
-import type { EventFactory } from "../core/event-factory.js";
-import type { AIStreamEvent, FetchFn } from "../types/index.js";
-import { emitMalformedStreamWarning } from "./adapter-auxiliary.js";
-import { providerHttpError } from "./adapter-security.js";
-import type { IncrementalStreamParser } from "./incremental-stream-parser.js";
-
-export type OpenProviderJsonStreamOptions = {
-  fetchFn: FetchFn;
-  url: string;
-  headers: Record<string, string>;
-  body: unknown;
-  signal?: AbortSignal;
-};
-
-export type OpenedProviderStream = {
-  reader: ReadableStreamDefaultReader<Uint8Array>;
-  headers: Headers;
-};
-
-/** POST JSON 并返回可读 body reader + response headers；统一网络/HTTP/空 body 错误。 */
-export async function openProviderJsonStream(options: OpenProviderJsonStreamOptions): Promise<OpenedProviderStream> {
-  const { fetchFn, url, headers, body, signal } = options;
-
-  let response: Response;
-  try {
-    response = await fetchFn(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(body),
-      signal,
-    });
-  } catch (err) {
-    throw new AIProviderError(err instanceof Error ? err.message : String(err), "PROVIDER_ERROR");
-  }
-
-  if (!response.ok) {
-    const errorBody = await response.text().catch(() => "");
-    throw providerHttpError(response.status, errorBody);
-  }
-
-  const bodyStream = response.body;
-  if (!bodyStream) {
-    throw new AIStreamError("Response body is not readable", "STREAM_ERROR");
-  }
-
-  // Bun/DOM ReadableStreamDefaultReader 类型略有差异，按最小接口使用
-  return {
-    reader: bodyStream.getReader() as ReadableStreamDefaultReader<Uint8Array>,
-    headers: response.headers,
-  };
-}
-
-export type ProviderStreamBatchOptions<T> = {
-  reader: ReadableStreamDefaultReader<Uint8Array>;
-  parser: IncrementalStreamParser<T>;
-  factory: EventFactory;
-  providerLabel: string;
-  transportLabel: string;
-  incompleteMessage: string;
-};
-
-export type ProviderStreamBatch<T> = {
-  items: T[];
-  warnings: AIStreamEvent[];
-};
-
-/**
- * 读取并解析 provider 流。
- * 每个 batch 携带本轮解析出的 items 与（可选）malformed / incomplete warning。
- * 调用方应 `for await` 消费完毕；reader 在迭代结束时 cancel/release。
- */
-export async function* iterateProviderStreamBatches<T>(
-  options: ProviderStreamBatchOptions<T>,
-): AsyncGenerator<ProviderStreamBatch<T>, void, undefined> {
-  const { reader, parser, factory, providerLabel, transportLabel, incompleteMessage } = options;
-  let streamDone = false;
-
-  try {
-    while (true) {
-      const readResult = await reader.read().catch((err: unknown) => {
-        throw new AIStreamError(
-          `Failed to read response stream: ${err instanceof Error ? err.message : String(err)}`,
-          "STREAM_ERROR",
-        );
-      });
-      const { done, value } = readResult;
-      const { items, malformed } = done ? parser.flush() : parser.feed(value as Uint8Array);
-
-      const warnings: AIStreamEvent[] = [];
-      const malformedWarning = emitMalformedStreamWarning(factory, {
-        count: malformed,
-        providerLabel,
-        transportLabel,
-      });
-      if (malformedWarning) warnings.push(malformedWarning);
-
-      yield { items, warnings };
-
-      if (done) {
-        streamDone = true;
-        break;
-      }
-    }
-  } finally {
-    try {
-      if (!streamDone) await reader.cancel().catch(() => undefined);
-    } finally {
-      reader.releaseLock();
-    }
-  }
-
-  if (parser.getRemaining().trim().length > 0) {
-    yield {
-      items: [],
-      warnings: [factory.responseWarning(incompleteMessage, "STREAM_ERROR")],
-    };
-  }
-}
-
-/** 一次性 complete 守卫：首次成功，后续返回 false。 */
-export function createCompletionGate(): {
-  readonly completed: boolean;
-  tryComplete(): boolean;
-} {
-  let completed = false;
-  return {
-    get completed() {
-      return completed;
-    },
-    tryComplete() {
-      if (completed) return false;
-      completed = true;
-      return true;
-    },
-  };
-}

package/src/helpers/reasoning-level.ts

@@ -1,86 +0,0 @@
-/**
- * Portable reasoningLevel → provider wire 字段映射
- *
- * 第一版只处理 level 枚举；budget/summary 等特化字段不在此层。
- * 无法映射的 level 抛 AIRequestError(UNSUPPORTED_REASONING_LEVEL)。
- */
-
-import { AIRequestError } from "../core/errors.js";
-import type { ReasoningLevel } from "../types/request.js";
-
-export const REASONING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly ReasoningLevel[];
-
-export const REASONING_LEVEL_SET: ReadonlySet<string> = new Set(REASONING_LEVELS);
-
-const MESSAGES_BUDGET_RATIOS: Record<Exclude<ReasoningLevel, "none">, number> = {
-  minimal: 0.02,
-  low: 0.1,
-  medium: 0.3,
-  high: 0.6,
-  xhigh: 0.9,
-  max: 0.95,
-};
-
-const OLLAMA_SUPPORTED = new Set<ReasoningLevel>(["none", "low", "medium", "high"]);
-
-export type OpenAIReasoningEffort = ReasoningLevel;
-
-export type MessagesThinkingConfig =
-  | { type: "disabled" }
-  | { type: "enabled"; budget_tokens: number };
-
-export type OllamaThinkValue = false | "low" | "medium" | "high";
-
-/** 若 level 不在 supported 集合内则抛 AIRequestError。 */
-export function assertSupportedReasoningLevel(
-  level: ReasoningLevel,
-  supported: ReadonlySet<ReasoningLevel>,
-  adapterKind: string,
-): void {
-  if (supported.has(level)) return;
-  throw new AIRequestError(
-    `reasoningLevel "${level}" is not supported by the ${adapterKind} adapter`,
-    "UNSUPPORTED_REASONING_LEVEL",
-  );
-}
-
-/** Responses API：`reasoning: { effort }` */
-export function mapResponsesReasoning(level: ReasoningLevel): { effort: OpenAIReasoningEffort } {
-  return { effort: level };
-}
-
-/** Chat Completions：顶层 `reasoning_effort` */
-export function mapChatCompletionsReasoningEffort(level: ReasoningLevel): OpenAIReasoningEffort {
-  return level;
-}
-
-/**
- * Messages thinking budget。
- * 基于 maxTokens 按比例推导，clamp 到 [1024, max(1024, maxTokens - 1)]，
- * 满足 Anthropic budget_tokens < max_tokens。
- */
-export function mapMessagesThinkingBudget(level: Exclude<ReasoningLevel, "none">, maxTokens: number): number {
-  const ratio = MESSAGES_BUDGET_RATIOS[level];
-  const raw = Math.round(maxTokens * ratio);
-  const upper = Math.max(1024, maxTokens - 1);
-  return Math.min(Math.max(raw, 1024), upper);
-}
-
-/** Messages API：`thinking` 字段 */
-export function mapMessagesThinking(level: ReasoningLevel, maxTokens: number): MessagesThinkingConfig {
-  if (level === "none") {
-    return { type: "disabled" };
-  }
-  return {
-    type: "enabled",
-    budget_tokens: mapMessagesThinkingBudget(level, maxTokens),
-  };
-}
-
-/** Ollama：`think` 字段；minimal/xhigh/max 不支持 */
-export function mapOllamaThink(level: ReasoningLevel): OllamaThinkValue {
-  assertSupportedReasoningLevel(level, OLLAMA_SUPPORTED, "ollama");
-  if (level === "none") return false;
-  // narrow after assert: only low|medium|high remain
-  return level as Exclude<OllamaThinkValue, false>;
-}