@codehz/ai 0.4.6 → 0.7.1

package/src/helpers/adapter-auxiliary.ts

@@ -1,155 +0,0 @@
-import { WarningCode } from "../core/errors.js";
-import type { EventFactory } from "../core/event-factory.js";
-import type { AIStreamEvent, BillingInfo, NormalizedRequest, Usage, AuxiliaryInfo } from "../types/index.js";
-import { AuxiliaryCollector, type BillingSource, type LookupResult, type UsageSource } from "./auxiliary-collector.js";
-
-type MaybePromise<T> = T | Promise<T>;
-
-export type BillingPostprocessHook = (context: {
-  request: NormalizedRequest;
-  usage?: Usage;
-  billing?: BillingInfo;
-  auxiliary?: AuxiliaryInfo;
-}) => MaybePromise<Partial<BillingInfo> | undefined>;
-
-export type AuxiliaryFinalizeOptions = {
-  lookup?: () => Promise<LookupResult>;
-  lookupTimeoutMs?: number;
-  postprocessBilling?: BillingPostprocessHook;
-  postprocessBillingSource?: BillingSource;
-};
-
-export type AuxiliaryFinalizeResult = {
-  events: AIStreamEvent[];
-  usage?: Usage;
-  billing?: BillingInfo;
-  auxiliary?: AuxiliaryInfo;
-  warnings?: string[];
-  metadataSources?: string[];
-};
-
-export class AdapterAuxiliaryState {
-  private readonly collector = new AuxiliaryCollector();
-  private readonly metadataSources = new Set<string>();
-
-  constructor(private readonly request: NormalizedRequest) {}
-
-  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): void {
-    if (this.request.include?.usage === "off" || isEmptyRecord(usage)) return;
-    this.collector.recordUsage(usage, source, raw);
-  }
-
-  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): void {
-    if (this.request.include?.billing === "off" || isEmptyRecord(billing)) return;
-    this.collector.recordBilling(billing, source, raw);
-  }
-
-  recordProviderMetadata(source: string, metadata: Record<string, unknown> | undefined): void {
-    if (this.request.include?.providerMetadata === "off" || !metadata || isEmptyRecord(metadata)) return;
-    this.collector.recordMetadata(metadata);
-    this.metadataSources.add(source);
-  }
-
-  async finalize(factory: EventFactory, options: AuxiliaryFinalizeOptions = {}): Promise<AuxiliaryFinalizeResult> {
-    if (options.lookup && this.shouldAttemptLookup()) {
-      await this.collector.tryLookup(options.lookup, options.lookupTimeoutMs);
-    }
-
-    if (this.request.include?.billing !== "off" && options.postprocessBilling) {
-      const snapshot = this.collector.build();
-      if (!snapshot.billing) {
-        const derived = await options.postprocessBilling({
-          request: this.request,
-          usage: snapshot.usage,
-          billing: snapshot.billing,
-          auxiliary: snapshot.auxiliary,
-        });
-        if (derived && !isEmptyRecord(derived)) {
-          this.collector.recordBilling(
-            {
-              ...derived,
-              isEstimated: derived.isEstimated ?? true,
-              source: derived.source ?? "derived",
-            },
-            options.postprocessBillingSource ?? "derived",
-            derived,
-          );
-        }
-      }
-    }
-
-    const built = this.collector.build();
-    const events: AIStreamEvent[] = [];
-
-    if (built.usage || built.billing || built.auxiliary) {
-      events.push(
-        factory.responseAuxiliary({
-          usage: built.usage,
-          billing: built.billing,
-          auxiliary: built.auxiliary,
-        }),
-      );
-    }
-
-    if (this.request.include?.usage !== "off" && !built.usage) {
-      events.push(
-        factory.responseWarning("Usage information was not provided by the provider", WarningCode.USAGE_MISSING),
-      );
-    }
-
-    if (this.request.include?.billing !== "off") {
-      if (!built.billing) {
-        events.push(
-          factory.responseWarning("Billing information was not provided by the provider", WarningCode.BILLING_MISSING),
-        );
-      } else if (built.billing.isEstimated) {
-        events.push(factory.responseWarning("Billing amount is an estimate", WarningCode.BILLING_ESTIMATED));
-      }
-    }
-
-    return {
-      events,
-      usage: built.usage,
-      billing: built.billing,
-      auxiliary: built.auxiliary,
-      warnings: built.warnings,
-      metadataSources: this.metadataSources.size > 0 ? [...this.metadataSources] : undefined,
-    };
-  }
-
-  private shouldAttemptLookup(): boolean {
-    if (
-      this.request.include?.usage === "off" &&
-      this.request.include?.billing === "off" &&
-      this.request.include?.providerMetadata === "off"
-    ) {
-      return false;
-    }
-
-    const snapshot = this.collector.build();
-    return (
-      (this.request.include?.usage !== "off" && !snapshot.usage) ||
-      (this.request.include?.billing !== "off" && !snapshot.billing) ||
-      (this.request.include?.providerMetadata !== "off" && !snapshot.auxiliary?.providerMetadata)
-    );
-  }
-}
-
-export function emitMalformedStreamWarning(
-  factory: EventFactory,
-  options: {
-    count: number;
-    providerLabel: string;
-    transportLabel: string;
-  },
-): AIStreamEvent | undefined {
-  if (options.count < 1) return undefined;
-  return factory.responseWarning(
-    `Skipped ${options.count} malformed ${options.providerLabel} ${options.transportLabel}`,
-    "STREAM_ERROR",
-  );
-}
-
-function isEmptyRecord(value: object): boolean {
-  return Object.keys(value).length === 0;
-}

package/src/helpers/adapter-base.ts

@@ -1,218 +0,0 @@
-/**
- * Adapter 抽象基类
- *
- * 约定 adapter 的内部职责分层（build / invoke / parse / emit）：
- * 1. buildRequest    — 将 NormalizedRequest 转换为 provider 请求格式
- * 2. invokeProvider  — 调用 provider API
- * 3. parseResponse   — 解析 provider 响应为 canonical 中间态
- * 4. emitEvents      — 产出 canonical 事件流
- *
- * 子类实现 buildRequest() 和 runStream()，
- * runStream 返回 AsyncIterable，事件实时发射给消费者。
- */
-
-import type {
-  NormalizedRequest,
-  BackendAdapter,
-  AIStreamEvent,
-  AIResponse,
-  AuxiliaryInfo,
-  OutputItem,
-  ReplayItem,
-  StopReason,
-  Usage,
-  BillingInfo,
-  ToolCallItem,
-} from "../types/index.js";
-import { createEventFactory } from "../core/event-factory.js";
-import { AIMappingError, AIProviderError, AIRequestError, AIStreamError } from "../core/errors.js";
-import type { EventFactory } from "../core/event-factory.js";
-import { extractText } from "./mapping.js";
-import { AdapterAuxiliaryState } from "./adapter-auxiliary.js";
-import { mergeAuxiliary } from "../core/merge-auxiliary.js";
-
-// ── Adapter 解析中间结果 ──────────────────────────────────────
-
-export type ProviderResponse = unknown;
-
-/**
- * adapter 完成一轮处理后返回的最终结果。
- * 用于 buildResponse() 构建 AIResponse。
- */
-export 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;
-};
-
-// ── 抽象基类 ──────────────────────────────────────────────────
-
-export abstract class AdapterBase implements BackendAdapter {
-  abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  abstract readonly isSyntheticStream: boolean;
-
-  /**
-   * stream 模板方法：
-   * 1. 创建事件工厂，发射 response.started
-   * 2. 构建 provider 请求
-   * 3. 委托 runStream 发射全部流事件（含 response.completed）
-   */
-  async *stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent> {
-    // 若请求已被 abort，不发出任何事件
-    request.signal?.throwIfAborted();
-
-    const factory = createEventFactory({
-      responseId: request.requestId,
-      backend: { kind: this.kind, isSynthetic: this.isSyntheticStream },
-    });
-
-    yield factory.responseStarted(request.model);
-
-    try {
-      const providerRequest = await this.buildRequest(request);
-      yield* this.runStream(providerRequest, factory, request);
-    } catch (err) {
-      if (err instanceof AIRequestError || err instanceof AIProviderError || err instanceof AIStreamError) {
-        throw err;
-      }
-
-      if (err instanceof AIMappingError) {
-        yield factory.responseWarning(err.message, "MAPPING_ERROR");
-        const errorResp = this.buildResponse(request, { output: [], replay: [] }, factory);
-        yield factory.responseCompleted({
-          replay: errorResp.replay,
-          stopReason: errorResp.stopReason,
-          trace: errorResp.backend,
-          usage: errorResp.usage,
-          billing: errorResp.billing,
-          auxiliary: errorResp.auxiliary,
-          warnings: errorResp.warnings,
-        });
-        return;
-      }
-
-      throw err;
-    }
-  }
-
-  // ── 子类必须实现 ──────────────────────────────────────────
-
-  /** 将 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 {
-    const text = extractText(result.output);
-    const warnings = mergeWarnings(result.warnings, _factory.warnings);
-    const auxiliary = mergeAuxiliary(
-      result.auxiliary,
-      result.providerMetadata ? { providerMetadata: result.providerMetadata } : undefined,
-    );
-
-    return {
-      id: request.requestId,
-      output: result.output,
-      replay: result.replay,
-      text,
-      toolCalls: result.output.filter((item): item is ToolCallItem => item.type === "tool_call"),
-      stopReason: result.stopReason,
-      usage: result.usage,
-      billing: result.billing,
-      auxiliary,
-      warnings,
-      backend: {
-        requestId: request.requestId,
-        rawResponseId: result.rawResponseId,
-        adapter: this.kind,
-        isSyntheticStream: this.isSyntheticStream,
-        metadataSources: result.metadataSources,
-        warnings,
-      },
-    };
-  }
-
-  /**
-   * 统一 finalize auxiliary → response.completed。
-   * adapter 在调用前组装 output / replay / stopReason 等业务字段。
-   */
-  protected async *emitStreamCompleted(
-    factory: EventFactory,
-    request: NormalizedRequest,
-    auxiliary: AdapterAuxiliaryState,
-    result: StreamResult,
-  ): AsyncIterable<AIStreamEvent> {
-    const auxiliaryResult = await auxiliary.finalize(factory);
-    for (const event of auxiliaryResult.events) {
-      yield event;
-    }
-
-    const finalResponse = this.buildResponse(
-      request,
-      {
-        ...result,
-        usage: result.usage ?? auxiliaryResult.usage,
-        billing: result.billing ?? auxiliaryResult.billing,
-        auxiliary: mergeAuxiliary(result.auxiliary, auxiliaryResult.auxiliary),
-        warnings: mergeWarnings(result.warnings, auxiliaryResult.warnings),
-        metadataSources: result.metadataSources ?? auxiliaryResult.metadataSources,
-      },
-      factory,
-    );
-
-    yield factory.responseCompleted({
-      replay: finalResponse.replay,
-      stopReason: finalResponse.stopReason,
-      trace: finalResponse.backend,
-      usage: finalResponse.usage,
-      billing: finalResponse.billing,
-      auxiliary: finalResponse.auxiliary,
-      warnings: finalResponse.warnings,
-    });
-  }
-
-  protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState {
-    return new AdapterAuxiliaryState(request);
-  }
-}
-
-function mergeWarnings(...groups: Array<string[] | undefined>): string[] | undefined {
-  const merged: string[] = [];
-
-  for (const group of groups) {
-    if (!group) continue;
-    for (const warning of group) {
-      if (!merged.includes(warning)) {
-        merged.push(warning);
-      }
-    }
-  }
-
-  return merged.length > 0 ? merged : undefined;
-}

package/src/helpers/adapter-security.ts

@@ -1,126 +0,0 @@
-/**
- * Adapter 边界安全辅助
- *
- * - opaque replay 入站 envelope（大小 / 深度）
- * - provider HTTP 错误 body 出站脱敏
- */
-
-import { AIProviderError, AIRequestError } from "../core/errors.js";
-
-export const MAX_OPAQUE_PAYLOAD_BYTES = 65536;
-export const MAX_OPAQUE_JSON_DEPTH = 8;
-export const PROVIDER_ERROR_MESSAGE_MAX_LEN = 500;
-export const PROVIDER_ERROR_RAW_BODY_THRESHOLD = 200;
-
-export type OpaqueEnvelopeResult = { ok: true } | { ok: false; reason: string };
-
-/** 测量 JSON 值嵌套深度（对象/数组）；循环引用按已访问节点深度计。 */
-export function measureJsonDepth(value: unknown, seen = new WeakSet<object>()): number {
-  if (value === null || typeof value !== "object") {
-    return 0;
-  }
-
-  if (seen.has(value)) {
-    return 0;
-  }
-  seen.add(value);
-
-  let maxChild = 0;
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      maxChild = Math.max(maxChild, measureJsonDepth(item, seen));
-    }
-  } else {
-    for (const key of Object.keys(value as Record<string, unknown>)) {
-      maxChild = Math.max(maxChild, measureJsonDepth((value as Record<string, unknown>)[key], seen));
-    }
-  }
-
-  return 1 + maxChild;
-}
-
-/**
- * Opaque replay 通用 envelope：必须是 object、体积 ≤ 64KB、深度 ≤ 8。
- * 不校验 adapter 专用字段形状。
- */
-export function validateOpaqueReplayEnvelope(payload: unknown): OpaqueEnvelopeResult {
-  if (typeof payload !== "object" || payload === null) {
-    return { ok: false, reason: "payload must be an object" };
-  }
-
-  let raw: string;
-  try {
-    raw = JSON.stringify(payload);
-  } catch {
-    return { ok: false, reason: "payload is not JSON-serializable" };
-  }
-
-  if (raw === undefined) {
-    return { ok: false, reason: "payload is not JSON-serializable" };
-  }
-
-  if (raw.length > MAX_OPAQUE_PAYLOAD_BYTES) {
-    return {
-      ok: false,
-      reason: `opaque payload exceeds max size (${raw.length} > ${MAX_OPAQUE_PAYLOAD_BYTES})`,
-    };
-  }
-
-  const depth = measureJsonDepth(payload);
-  if (depth > MAX_OPAQUE_JSON_DEPTH) {
-    return {
-      ok: false,
-      reason: `opaque payload nesting depth (${depth}) exceeds max (${MAX_OPAQUE_JSON_DEPTH})`,
-    };
-  }
-
-  return { ok: true };
-}
-
-/** envelope 失败时抛 AIRequestError。 */
-export function assertOpaqueReplayEnvelope(payload: unknown): void {
-  const result = validateOpaqueReplayEnvelope(payload);
-  if (!result.ok) {
-    throw new AIRequestError(`Invalid opaque replay payload: ${result.reason}`, "INVALID_OPAQUE_REPLAY");
-  }
-}
-
-/**
- * 从 provider HTTP 错误 body 提取可对外暴露的短消息，避免泄漏 HTML / 内部路径等。
- */
-export function extractProviderErrorMessage(body: string, status: number): string {
-  if (!body) return `HTTP ${status}`;
-
-  try {
-    const parsed: unknown = JSON.parse(body);
-    if (parsed && typeof parsed === "object") {
-      const record = parsed as Record<string, unknown>;
-      const errorField = record.error;
-      let msg: unknown;
-      if (errorField && typeof errorField === "object" && errorField !== null) {
-        msg = (errorField as Record<string, unknown>).message;
-      }
-      if (typeof msg !== "string") {
-        msg = typeof errorField === "string" ? errorField : record.message;
-      }
-      if (typeof msg === "string" && msg.length > 0) {
-        return msg.slice(0, PROVIDER_ERROR_MESSAGE_MAX_LEN);
-      }
-    }
-  } catch {
-    // not JSON
-  }
-
-  const trimmed = body.trimStart();
-  if (trimmed.startsWith("<!") || trimmed.startsWith("<html") || body.length > PROVIDER_ERROR_RAW_BODY_THRESHOLD) {
-    return `HTTP ${status}. Body omitted (${body.length} bytes)`;
-  }
-
-  return body.slice(0, PROVIDER_ERROR_MESSAGE_MAX_LEN);
-}
-
-/** 统一构造脱敏后的 AIProviderError。 */
-export function providerHttpError(status: number, body: string): AIProviderError {
-  const safe = extractProviderErrorMessage(body, status);
-  return new AIProviderError(`Provider returned ${status}: ${safe}`, "PROVIDER_ERROR", status, safe);
-}

package/src/helpers/auxiliary-collector.ts

@@ -1,166 +0,0 @@
-/**
- * 辅助信息采集器 (AuxiliaryCollector)
- *
- * 为 usage、billing、providerMetadata 提供统一的 best-effort 采集。
- *
- * 采集优先级（分层）：
- *   1. 主响应 body / terminal event
- *   2. headers / trailers
- *   3. SDK metadata
- *   4. 一次 follow-up lookup
- *   5. derived estimate
- *
- * 约束：
- *   - lookup 最多一次有界补查
- *   - lookup 失败只记录 warning
- *   - 不阻断主生成链路
- */
-
-import type { Usage, BillingInfo, AuxiliaryInfo } from "../types/index.js";
-
-// ── 来源类型 ──────────────────────────────────────────────────
-
-export type UsageSource = NonNullable<AuxiliaryInfo["usageSource"]>;
-export type BillingSource = NonNullable<AuxiliaryInfo["billingSource"]>;
-
-export type LookupResult = {
-  usage?: Partial<Usage>;
-  billing?: Partial<BillingInfo>;
-  providerMetadata?: Record<string, unknown>;
-};
-
-// ── Collector ─────────────────────────────────────────────────
-
-export class AuxiliaryCollector {
-  private usage: Partial<Usage> = {};
-  private usageSource: UsageSource | undefined;
-  private billing: Partial<BillingInfo> | undefined;
-  private billingSource: BillingSource | undefined;
-  private providerMetadata: Record<string, unknown> = {};
-  private providerUsage: unknown;
-  private providerBilling: unknown;
-  private warnings: string[] = [];
-  private lookupAttempted = false;
-
-  // ── 记录方法 ──────────────────────────────────────────────
-
-  /**
-   * 记录 usage 信息。
-   * 后调用的覆盖先调用的（优先级由调用方控制）。
-   */
-  recordUsage(usage: Partial<Usage>, source: UsageSource, raw?: unknown): this {
-    this.usage = { ...this.usage, ...usage };
-    this.usageSource = source;
-    if (raw !== undefined) this.providerUsage = raw;
-    return this;
-  }
-
-  /**
-   * 记录 billing 信息。
-   * 后调用的覆盖先调用的。
-   */
-  recordBilling(billing: Partial<BillingInfo>, source: BillingSource, raw?: unknown): this {
-    this.billing = { ...this.billing, ...billing };
-    this.billingSource = source;
-    if (raw !== undefined) this.providerBilling = raw;
-    return this;
-  }
-
-  /**
-   * 记录 provider 元数据（非 canonical 的 key-value 信息）。
-   */
-  recordMetadata(metadata: Record<string, unknown>): this {
-    this.providerMetadata = { ...this.providerMetadata, ...metadata };
-    return this;
-  }
-
-  /**
-   * 记录一条 warning。
-   */
-  recordWarning(message: string): this {
-    this.warnings.push(message);
-    return this;
-  }
-
-  // ── 有界 Lookup ───────────────────────────────────────────
-
-  /**
-   * 执行一次有界 follow-up lookup。
-   * 最多调用一次；后续调用被忽略。
-   * lookup 失败（抛错）仅记录 warning，不传播异常。
-   */
-  async tryLookup(lookupFn: () => Promise<LookupResult>, timeoutMs = 5_000): Promise<void> {
-    if (this.lookupAttempted) return;
-    this.lookupAttempted = true;
-
-    try {
-      const result = await withTimeout(lookupFn(), timeoutMs);
-      if (result.usage) {
-        this.recordUsage(result.usage, "lookup", result.usage);
-      }
-      if (result.billing) {
-        const bill: Partial<BillingInfo> = {
-          ...result.billing,
-          source: result.billing?.source ?? "lookup",
-        };
-        this.recordBilling(bill, "lookup", result.billing);
-      }
-      if (result.providerMetadata) {
-        this.recordMetadata(result.providerMetadata);
-      }
-    } catch (err) {
-      this.recordWarning(`Auxiliary lookup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  // ── 构建最终结果 ──────────────────────────────────────────
-
-  /**
-   * 构建最终的 usage / billing / auxiliary。
-   * 所有字段均为可选的 — 拿不到就不给。
-   */
-  build(): { usage?: Usage; billing?: BillingInfo; auxiliary?: AuxiliaryInfo; warnings?: string[] } {
-    const result: { usage?: Usage; billing?: BillingInfo; auxiliary?: AuxiliaryInfo; warnings?: string[] } = {};
-
-    if (Object.keys(this.usage).length > 0) {
-      result.usage = this.usage as Usage;
-    }
-
-    if (this.billing) {
-      result.billing = this.billing as BillingInfo;
-    }
-
-    const aux: AuxiliaryInfo = {};
-    if (this.usageSource) aux.usageSource = this.usageSource;
-    if (this.billingSource) aux.billingSource = this.billingSource;
-    if (this.providerUsage !== undefined) aux.providerUsage = this.providerUsage;
-    if (this.providerBilling !== undefined) aux.providerBilling = this.providerBilling;
-    if (Object.keys(this.providerMetadata).length > 0) aux.providerMetadata = this.providerMetadata;
-
-    if (Object.keys(aux).length > 0) {
-      result.auxiliary = aux;
-    }
-
-    if (this.warnings.length > 0) {
-      result.warnings = [...this.warnings];
-    }
-
-    return result;
-  }
-
-  /**
-   * 已使用的来源列表（用于 debugging）。
-   */
-  get sources(): { usage?: UsageSource; billing?: BillingSource } {
-    return { usage: this.usageSource, billing: this.billingSource };
-  }
-}
-
-// ── Helper ────────────────────────────────────────────────────
-
-function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  return Promise.race([
-    promise,
-    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(`Lookup timed out after ${ms}ms`)), ms)),
-  ]);
-}