@codehz/ai 0.4.5 → 0.7.0

package/src/core/event-factory.ts

@@ -1,151 +0,0 @@
-/**
- * 共享事件工厂
- *
- * 负责创建带有统一 sequence / timestamp / responseId / backend 的事件对象。
- * 每个 factory 实例管理一个单调递增的 sequence 计数器。
- */
-
-import type {
-  ResponseStartedEvent,
-  ResponseWarningEvent,
-  ResponseAuxiliaryEvent,
-  ResponseCompletedEvent,
-  MessageStartedEvent,
-  MessageDeltaEvent,
-  MessageCompletedEvent,
-  ReasoningStartedEvent,
-  ReasoningDeltaEvent,
-  ReasoningCompletedEvent,
-  ToolCallStartedEvent,
-  ToolCallDeltaEvent,
-  ToolCallCompletedEvent,
-  ContentBlock,
-  Usage,
-  BillingInfo,
-  AuxiliaryInfo,
-  ReplayItem,
-  StopReason,
-  BackendTrace,
-  OpaqueItem,
-  ReasoningItem,
-} from "../types/index.js";
-
-export type EventFactoryBackend = {
-  kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  isSynthetic: boolean;
-};
-
-export type EventFactoryState = {
-  responseId: string;
-  backend: EventFactoryBackend;
-};
-
-function timestamp(): string {
-  return new Date().toISOString();
-}
-
-export function createEventFactory(state: EventFactoryState) {
-  let seq = 0;
-  const warnings: string[] = [];
-
-  function next(): number {
-    return seq++;
-  }
-
-  function base(): Pick<ResponseStartedEvent, "responseId" | "sequence" | "timestamp" | "backend"> {
-    return {
-      responseId: state.responseId,
-      sequence: next(),
-      timestamp: timestamp(),
-      backend: { ...state.backend },
-    };
-  }
-
-  return {
-    // ── 响应级事件 ──────────────────────────────────────────
-
-    responseStarted(model: string): ResponseStartedEvent {
-      return { ...base(), type: "response.started", model };
-    },
-
-    responseWarning(message: string, code?: string): ResponseWarningEvent {
-      warnings.push(message);
-      return { ...base(), type: "response.warning", message, code };
-    },
-
-    responseAuxiliary(data: {
-      usage?: Usage;
-      billing?: BillingInfo;
-      auxiliary?: Partial<AuxiliaryInfo>;
-    }): ResponseAuxiliaryEvent {
-      return { ...base(), type: "response.auxiliary", ...data };
-    },
-
-    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 };
-    },
-
-    // ── 消息流事件 ──────────────────────────────────────────
-
-    messageStarted(id: string): MessageStartedEvent {
-      return { ...base(), type: "message.started", item: { id, role: "assistant" } };
-    },
-
-    messageDelta(itemId: string, delta: ContentBlock): MessageDeltaEvent {
-      return { ...base(), type: "message.delta", itemId, delta };
-    },
-
-    messageCompleted(itemId: string): MessageCompletedEvent {
-      return { ...base(), type: "message.completed", itemId };
-    },
-
-    // ── 思维链流事件 ────────────────────────────────────────
-
-    reasoningStarted(id: string, visibility: ReasoningItem["visibility"]): ReasoningStartedEvent {
-      return { ...base(), type: "reasoning.started", item: { id, visibility } };
-    },
-
-    reasoningDelta(itemId: string, delta: ContentBlock): ReasoningDeltaEvent {
-      return { ...base(), type: "reasoning.delta", itemId, delta };
-    },
-
-    reasoningCompleted(itemId: string): ReasoningCompletedEvent {
-      return { ...base(), type: "reasoning.completed", itemId };
-    },
-
-    // ── 工具调用流事件 ──────────────────────────────────────
-
-    toolCallStarted(id: string, name: string): ToolCallStartedEvent {
-      return { ...base(), type: "tool_call.started", item: { id, name } };
-    },
-
-    toolCallDelta(itemId: string, delta: { argumentsText?: string }): ToolCallDeltaEvent {
-      return { ...base(), type: "tool_call.delta", itemId, delta };
-    },
-
-    toolCallCompleted(itemId: string): ToolCallCompletedEvent {
-      return { ...base(), type: "tool_call.completed", itemId };
-    },
-
-    /** 返回当前已发出的 sequence 计数（用于断言） */
-    get sequence(): number {
-      return seq;
-    },
-
-    /** 返回当前已记录的 warning 副本。 */
-    get warnings(): string[] {
-      return [...warnings];
-    },
-  };
-}
-
-export type EventFactory = ReturnType<typeof createEventFactory>;

package/src/core/index.ts

@@ -1,18 +0,0 @@
-/**
- * 核心运行时
- *
- * 模块边界：客户端入口、请求归一化、事件工厂、流聚合器。
- * 不依赖具体 adapter 实现。
- */
-
-export { createAIClient } from "./client.js";
-export type { AIClient } from "./client.js";
-export { normalizeRequest } from "./normalize.js";
-export type { NormalizeOptions } from "./normalize.js";
-export { validateRequest, assertValidRequest } from "./validation.js";
-export type { ValidationIssue } from "./validation.js";
-export { AIError, AIRequestError, AIProviderError, AIStreamError, AIMappingError, WarningCode } from "./errors.js";
-export { createEventFactory } from "./event-factory.js";
-export type { EventFactory, EventFactoryState, EventFactoryBackend } from "./event-factory.js";
-export { aggregateEvents } from "./aggregator.js";
-export { collectStream } from "./collect-stream.js";

package/src/core/merge-auxiliary.ts

@@ -1,22 +0,0 @@
-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

@@ -1,65 +0,0 @@
-/**
- * 请求归一化
- *
- * 将 AIRequest + client 配置归一化为 NormalizedRequest，
- * 包括默认值合并、requestId 生成、include 默认值填充。
- */
-
-import type { AIRequest, NormalizedRequest } from "../types/index.js";
-import { assertValidRequest, validateInclude } from "./validation.js";
-import { AIRequestError } from "./errors.js";
-
-export type NormalizeOptions = {
-  model: string;
-  defaults?: Partial<AIRequest>;
-};
-
-const DEFAULT_INCLUDE = {
-  usage: "best_effort" as const,
-  billing: "best_effort" as const,
-  providerMetadata: "best_effort" as const,
-};
-
-/**
- * 归一化请求：
- * 1. 合并 defaults
- * 2. 填充 include 默认值
- * 3. 生成 requestId
- * 4. 校验请求合法性
- */
-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,
-    ...request,
-    include: {
-      ...DEFAULT_INCLUDE,
-      ...defaults?.include,
-      ...request.include,
-    },
-  };
-
-  // 校验
-  assertValidRequest(merged);
-
-  return {
-    ...merged,
-    model,
-    requestId: crypto.randomUUID(),
-  };
-}

package/src/core/validation.ts

@@ -1,404 +0,0 @@
-/**
- * 请求校验
- *
- * 在请求进入 adapter 前对参数合法性做基础检查。
- * 校验失败时抛 AIRequestError。
- */
-
-import type { AIRequest } from "../types/index.js";
-import { AIRequestError } from "./errors.js";
-
-export type ValidationIssue = {
-  field: string;
-  code: string;
-  message: string;
-};
-
-const MESSAGE_ROLES = new Set(["user", "assistant"]);
-const REASONING_VISIBILITIES = new Set(["full", "summary", "redacted", "opaque"]);
-const TOOL_RESULT_OUTCOMES = new Set(["success", "error", "rejected"]);
-const INCLUDE_MODES = new Set(["off", "best_effort"]);
-const REASONING_LEVELS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function pushIssue(issues: ValidationIssue[], field: string, code: string, message: string): void {
-  issues.push({ field, code, message });
-}
-
-function validateContentBlock(block: unknown, field: string, issues: ValidationIssue[]): void {
-  if (!isRecord(block) || typeof block.type !== "string") {
-    pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field} must be a valid ContentBlock`);
-    return;
-  }
-
-  switch (block.type) {
-    case "text":
-      if (typeof block.text !== "string") {
-        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.text must be a string`);
-      }
-      return;
-    case "json":
-      if (!("json" in block)) {
-        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.json must be present`);
-      }
-      return;
-    case "image":
-      if (typeof block.imageUrl !== "string" || block.imageUrl.length === 0) {
-        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.imageUrl must be a non-empty string`);
-      }
-      return;
-    case "binary_ref":
-      if (typeof block.ref !== "string" || block.ref.length === 0) {
-        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.ref must be a non-empty string`);
-      }
-      return;
-    case "opaque":
-      if (!("payload" in block)) {
-        pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.payload must be present`);
-      }
-      return;
-    default:
-      pushIssue(issues, field, "CONTENT_BLOCK_INVALID", `${field}.type "${block.type}" is not supported`);
-  }
-}
-
-function validateContentArray(content: unknown, field: string, issues: ValidationIssue[], code: string): void {
-  if (!Array.isArray(content)) {
-    pushIssue(issues, field, code, `${field} must be a ContentBlock[]`);
-    return;
-  }
-
-  for (let i = 0; i < content.length; i++) {
-    validateContentBlock(content[i], `${field}[${i}]`, issues);
-  }
-}
-
-function validateInstructionArray(content: unknown, field: string, issues: ValidationIssue[]): void {
-  if (!Array.isArray(content)) {
-    pushIssue(issues, field, "INSTRUCTIONS_INVALID", `${field} must be an InstructionBlock[]`);
-    return;
-  }
-
-  for (let i = 0; i < content.length; i++) {
-    const block = content[i];
-    const blockField = `${field}[${i}]`;
-    validateContentBlock(block, blockField, issues);
-
-    if (!isRecord(block) || typeof block.type !== "string") continue;
-    if (block.type !== "text" && block.type !== "json") {
-      pushIssue(issues, blockField, "INSTRUCTIONS_INVALID", `${blockField} only supports text/json blocks`);
-    }
-  }
-}
-
-function validateInputItem(item: unknown, field: string, issues: ValidationIssue[]): void {
-  if (!isRecord(item)) {
-    pushIssue(issues, field, "INPUT_INVALID_ITEM", `${field} must be a valid InputItem`);
-    return;
-  }
-
-  if (typeof item.type !== "string") {
-    pushIssue(issues, field, "INPUT_ITEM_UNKNOWN_TYPE", `${field}.type must be a supported InputItem type`);
-    return;
-  }
-
-  switch (item.type) {
-    case "message":
-      if (typeof item.role !== "string" || !MESSAGE_ROLES.has(item.role)) {
-        pushIssue(issues, `${field}.role`, "MESSAGE_ROLE_INVALID", `${field}.role must be a valid message role`);
-      }
-      validateContentArray(item.content, `${field}.content`, issues, "MESSAGE_CONTENT_INVALID");
-      return;
-    case "reasoning":
-      if (typeof item.visibility !== "string" || !REASONING_VISIBILITIES.has(item.visibility)) {
-        pushIssue(
-          issues,
-          `${field}.visibility`,
-          "REASONING_VISIBILITY_INVALID",
-          `${field}.visibility must be a valid reasoning visibility`,
-        );
-      }
-      validateContentArray(item.content, `${field}.content`, issues, "REASONING_CONTENT_INVALID");
-      return;
-    case "tool_call":
-      if (typeof item.id !== "string" || item.id.length === 0) {
-        pushIssue(issues, `${field}.id`, "TOOL_CALL_ID_INVALID", `${field}.id must be a non-empty string`);
-      }
-      if (typeof item.name !== "string" || item.name.length === 0) {
-        pushIssue(issues, `${field}.name`, "TOOL_CALL_NAME_INVALID", `${field}.name must be a non-empty string`);
-      }
-      if (typeof item.argumentsText !== "string") {
-        pushIssue(
-          issues,
-          `${field}.argumentsText`,
-          "TOOL_CALL_ARGUMENTS_INVALID",
-          `${field}.argumentsText must be a string`,
-        );
-      } else {
-        try {
-          const parsed: unknown = JSON.parse(item.argumentsText);
-          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            pushIssue(
-              issues,
-              `${field}.argumentsText`,
-              "TOOL_CALL_ARGUMENTS_INVALID",
-              `${field}.argumentsText must encode a JSON object`,
-            );
-          }
-        } catch {
-          pushIssue(
-            issues,
-            `${field}.argumentsText`,
-            "TOOL_CALL_ARGUMENTS_INVALID",
-            `${field}.argumentsText must encode a JSON object`,
-          );
-        }
-      }
-      return;
-    case "tool_result":
-      if (typeof item.callId !== "string" || item.callId.length === 0) {
-        pushIssue(
-          issues,
-          `${field}.callId`,
-          "TOOL_RESULT_CALL_ID_INVALID",
-          `${field}.callId must be a non-empty string`,
-        );
-      }
-      if (typeof item.toolName !== "string" || item.toolName.length === 0) {
-        pushIssue(
-          issues,
-          `${field}.toolName`,
-          "TOOL_RESULT_NAME_INVALID",
-          `${field}.toolName must be a non-empty string`,
-        );
-      }
-      if (typeof item.outcome !== "string" || !TOOL_RESULT_OUTCOMES.has(item.outcome)) {
-        pushIssue(
-          issues,
-          `${field}.outcome`,
-          "TOOL_RESULT_OUTCOME_INVALID",
-          `${field}.outcome must be success, error, or rejected`,
-        );
-      }
-      validateContentArray(item.content, `${field}.content`, issues, "TOOL_RESULT_CONTENT_INVALID");
-      return;
-    case "opaque":
-      if (typeof item.source !== "string" || item.source.length === 0) {
-        pushIssue(issues, `${field}.source`, "OPAQUE_SOURCE_INVALID", `${field}.source must be a non-empty string`);
-      }
-      if (typeof item.purpose !== "string" || item.purpose.length === 0) {
-        pushIssue(issues, `${field}.purpose`, "OPAQUE_PURPOSE_INVALID", `${field}.purpose must be a non-empty string`);
-      }
-      return;
-    default:
-      pushIssue(issues, `${field}.type`, "INPUT_ITEM_UNKNOWN_TYPE", `${field}.type "${item.type}" is not supported`);
-  }
-}
-
-function validateTools(tools: unknown, issues: ValidationIssue[]): void {
-  if (tools === undefined) return;
-  if (!Array.isArray(tools)) {
-    pushIssue(issues, "tools", "TOOLS_INVALID", "tools must be an array");
-    return;
-  }
-
-  const seenNames = new Set<string>();
-  for (let i = 0; i < tools.length; i++) {
-    const tool = tools[i];
-    const field = `tools[${i}]`;
-    if (!isRecord(tool)) {
-      pushIssue(issues, field, "TOOL_INVALID", `${field} must be a valid ToolDefinition`);
-      continue;
-    }
-
-    if (typeof tool.name !== "string" || tool.name.length === 0) {
-      pushIssue(issues, `${field}.name`, "TOOL_NAME_INVALID", `${field}.name must be a non-empty string`);
-    } else {
-      if (seenNames.has(tool.name)) {
-        pushIssue(issues, `${field}.name`, "TOOLS_DUPLICATE_NAME", `tool name "${tool.name}" is duplicated`);
-      }
-      seenNames.add(tool.name);
-    }
-
-    if (tool.description !== undefined && typeof tool.description !== "string") {
-      pushIssue(issues, `${field}.description`, "TOOL_DESCRIPTION_INVALID", `${field}.description must be a string`);
-    }
-
-    if (!isRecord(tool.inputSchema)) {
-      pushIssue(issues, `${field}.inputSchema`, "TOOL_INPUT_SCHEMA_INVALID", `${field}.inputSchema must be an object`);
-    }
-  }
-}
-
-function validateToolChoice(toolChoice: unknown, issues: ValidationIssue[]): void {
-  if (toolChoice === undefined) return;
-  if (toolChoice === "auto" || toolChoice === "none") return;
-  if (
-    !isRecord(toolChoice) ||
-    toolChoice.type !== "tool" ||
-    typeof toolChoice.name !== "string" ||
-    toolChoice.name.length === 0
-  ) {
-    pushIssue(issues, "toolChoice", "TOOL_CHOICE_INVALID", 'toolChoice must be auto, none, or { type: "tool", name }');
-  }
-}
-
-/** 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，返回校验问题列表。
- * 空数组表示无问题。
- */
-export function validateRequest(request: AIRequest): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  if (request.instructions !== undefined) {
-    if (typeof request.instructions === "string") {
-      // no-op
-    } else if (Array.isArray(request.instructions)) {
-      validateInstructionArray(request.instructions, "instructions", issues);
-    } else {
-      pushIssue(issues, "instructions", "INSTRUCTIONS_INVALID", "instructions must be a string or InstructionBlock[]");
-    }
-  }
-
-  // input 非空约束
-  if (!Array.isArray(request.input) || request.input.length === 0) {
-    pushIssue(issues, "input", "INPUT_EMPTY", "input must be a non-empty array");
-  }
-
-  // input 元素类型检查
-  if (Array.isArray(request.input)) {
-    for (let i = 0; i < request.input.length; i++) {
-      validateInputItem(request.input[i], `input[${i}]`, issues);
-    }
-  }
-
-  // temperature 范围
-  if (request.temperature !== undefined) {
-    if (typeof request.temperature !== "number" || !Number.isFinite(request.temperature)) {
-      issues.push({
-        field: "temperature",
-        code: "TEMPERATURE_NOT_NUMBER",
-        message: "temperature must be a number",
-      });
-    } else if (request.temperature < 0 || request.temperature > 2) {
-      issues.push({
-        field: "temperature",
-        code: "TEMPERATURE_OUT_OF_RANGE",
-        message: "temperature must be between 0 and 2",
-      });
-    }
-  }
-
-  // maxOutputTokens 合法性
-  if (request.maxOutputTokens !== undefined) {
-    if (typeof request.maxOutputTokens !== "number" || !Number.isFinite(request.maxOutputTokens)) {
-      issues.push({
-        field: "maxOutputTokens",
-        code: "MAX_OUTPUT_TOKENS_NOT_NUMBER",
-        message: "maxOutputTokens must be a number",
-      });
-    } else if (!Number.isInteger(request.maxOutputTokens) || request.maxOutputTokens < 1) {
-      issues.push({
-        field: "maxOutputTokens",
-        code: "MAX_OUTPUT_TOKENS_INVALID",
-        message: "maxOutputTokens must be a positive integer",
-      });
-    }
-  }
-
-  // reasoningLevel 枚举
-  if (request.reasoningLevel !== undefined) {
-    if (typeof request.reasoningLevel !== "string" || !REASONING_LEVELS.has(request.reasoningLevel)) {
-      pushIssue(
-        issues,
-        "reasoningLevel",
-        "REASONING_LEVEL_INVALID",
-        'reasoningLevel must be one of: none, minimal, low, medium, high, xhigh',
-      );
-    }
-  }
-
-  if (request.include !== undefined) {
-    validateInclude(request.include, issues);
-  }
-
-  if (request.metadata !== undefined) {
-    if (!isRecord(request.metadata)) {
-      pushIssue(issues, "metadata", "METADATA_INVALID", "metadata must be an object");
-    } else {
-      for (const [key, value] of Object.entries(request.metadata)) {
-        if (typeof value !== "string") {
-          pushIssue(issues, `metadata.${key}`, "METADATA_VALUE_INVALID", `metadata.${key} must be a string`);
-        }
-      }
-    }
-  }
-
-  validateTools(request.tools, issues);
-  validateToolChoice(request.toolChoice, issues);
-
-  // toolChoice 与 tools 的一致性
-  if (
-    request.toolChoice &&
-    typeof request.toolChoice === "object" &&
-    "type" in request.toolChoice &&
-    request.toolChoice.type === "tool"
-  ) {
-    const chosenName = request.toolChoice.name;
-    if (!request.tools || request.tools.length === 0) {
-      issues.push({
-        field: "toolChoice",
-        code: "TOOL_CHOICE_NO_TOOLS",
-        message: `toolChoice specifies tool "${chosenName}" but no tools are defined`,
-      });
-    } else if (!request.tools.some((t) => t.name === chosenName)) {
-      issues.push({
-        field: "toolChoice",
-        code: "TOOL_CHOICE_UNKNOWN_TOOL",
-        message: `toolChoice specifies tool "${chosenName}" which is not in tools array`,
-      });
-    }
-  }
-
-  return issues;
-}
-
-/**
- * 校验请求并抛出首个问题。
- * 适用于客户端入口的快速失败检查。
- */
-export function assertValidRequest(request: AIRequest): void {
-  const issues = validateRequest(request);
-  const first = issues[0];
-  if (first) {
-    throw new AIRequestError(first.message, first.code, issues);
-  }
-}