@codehz/ai 0.4.4 → 0.4.6

package/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write # required for npm trusted publishing (OIDC)
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Verify tag matches package.json version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(node -p "require('./package.json').version")"
+          if [ "$tag" != "$version" ]; then
+            echo "Tag v${tag} does not match package.json version ${version}"
+            exit 1
+          fi
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Test
+        run: bun test
+
+      # Trusted publishing requires npm CLI (OIDC); other package managers cannot publish this way.
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false # never cache package manager state for release builds
+
+      - name: Ensure npm CLI supports trusted publishing
+        run: npm install -g npm@latest
+
+      - name: Publish to npm
+        # No NPM_TOKEN: npm CLI exchanges the GitHub OIDC token automatically.
+        # Provenance is generated automatically for trusted publishing from public repos.
+        run: npm publish --access public

package/README.md

@@ -45,10 +45,21 @@ type AIRequest = {
   toolChoice?: ToolChoice; // 工具选择策略
   temperature?: number; // 温度 (0–2)
   maxOutputTokens?: number; // 最大输出 token
+  reasoningLevel?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; // 可移植思考力度
   include?: { usage?; billing?; providerMetadata? };
 };
 ```
 
+`reasoningLevel` 是 portable 枚举，由各 adapter 映射到 provider 原生字段；未设置时不写相关 wire 字段。adapter 无法映射的 level（如 Ollama 的 `minimal` / `xhigh` / `max`）会抛 `AIRequestError`（`UNSUPPORTED_REASONING_LEVEL`）。需要 budget / summary 等特化参数时，仍可用构造期 `extraBody` 覆盖同名顶层键。
+
+| Adapter | 映射 |
+| --- | --- |
+| `ResponsesAdapter` | `reasoning: { effort }` |
+| `ChatCompletionsAdapter` | 顶层 `reasoning_effort` |
+| `MessagesAdapter` | `thinking: { type: "disabled" }` 或 `{ type: "enabled", budget_tokens }`（由 `maxOutputTokens` 按比例推导，默认 4096） |
+| `OllamaAdapter` | `think: false \| "low" \| "medium" \| "high"` |
+| `MockAdapter` | 透传到 `MockHandlerContext.reasoningLevel` |
+
 `input` 是 item 数组，每个 item 可以是：
 
 | Item 类型     | 用途                                |
@@ -133,16 +144,33 @@ import {
 } from "@codehz/ai";
 
 // OpenAI Responses API
-const responses = new ResponsesAdapter({ apiKey: "sk-..." });
+const responses = new ResponsesAdapter({
+  apiKey: "sk-...",
+  // 可选：自定义请求头 / body 额外顶层字段（构造期静态，后写覆盖内置鉴权头与同名 body 键）
+  headers: { "OpenAI-Organization": "org-..." },
+  extraBody: { top_p: 0.9 },
+});
 
 // Anthropic Messages API
-const messages = new MessagesAdapter({ apiKey: "sk-ant-..." });
+const messages = new MessagesAdapter({
+  apiKey: "sk-ant-...",
+  headers: { "anthropic-beta": "..." },
+  extraBody: { top_p: 0.9 },
+});
 
 // OpenAI Chat Completions
-const chat = new ChatCompletionsAdapter({ apiKey: "sk-..." });
+const chat = new ChatCompletionsAdapter({
+  apiKey: "sk-...",
+  headers: { "OpenAI-Organization": "org-..." },
+  extraBody: { top_p: 0.9 },
+});
 
 // Ollama
-const ollama = new OllamaAdapter({ baseUrl: "http://localhost:11434" });
+const ollama = new OllamaAdapter({
+  baseUrl: "http://localhost:11434",
+  headers: { "X-Custom": "..." },
+  extraBody: { keep_alive: "10m" },
+});
 
 // 面向测试的回调驱动 mock backend
 const mock = new MockAdapter({

package/dist/index.d.mts

@@ -79,6 +79,8 @@ type IncludeSettings = {
   billing?: "off" | "best_effort";
   providerMetadata?: "off" | "best_effort";
 };
+/** Portable reasoning / thinking effort. Mapped per-adapter to provider wire fields. */
+type ReasoningLevel = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type AIRequest = {
   instructions?: string | InstructionBlock[];
   input: InputItem[];
@@ -87,7 +89,13 @@ type AIRequest = {
   include?: IncludeSettings;
   metadata?: Record<string, string>;
   temperature?: number;
-  maxOutputTokens?: number; /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
+  maxOutputTokens?: number;
+  /**
+   * Portable reasoning effort. Adapters map this to provider-native fields
+   * (e.g. Responses `reasoning.effort`, Chat Completions `reasoning_effort`,
+   * Messages `thinking`, Ollama `think`). Unsupported levels throw.
+   */
+  reasoningLevel?: ReasoningLevel; /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
   signal?: AbortSignal;
 };
 //#endregion
@@ -551,7 +559,9 @@ declare abstract class AdapterBase implements BackendAdapter {
 type ResponsesAdapterOptions = {
   apiKey: string;
   baseUrl?: string; /** 可注入自定义 fetch 实现（用于测试／代理） */
-  fetch?: FetchFn;
+  fetch?: FetchFn; /** 额外请求头；后写覆盖内置 Authorization / Content-Type */
+  headers?: Record<string, string>; /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 type ResponsesAPIRequest = {
   model: string;
@@ -564,7 +574,10 @@ type ResponsesAPIRequest = {
   };
   metadata?: Record<string, string>;
   temperature?: number;
-  max_output_tokens?: number; /** 服务端多轮续写；opaque replay 的 response id 映射到此字段，而非 item_reference */
+  max_output_tokens?: number; /** Portable reasoningLevel → effort；summary 等特化字段不在此层 */
+  reasoning?: {
+    effort: string;
+  }; /** 服务端多轮续写；opaque replay 的 response id 映射到此字段，而非 item_reference */
   previous_response_id?: string;
   stream: true;
 };
@@ -637,6 +650,8 @@ declare class ResponsesAdapter extends AdapterBase {
   private apiKey;
   private baseUrl;
   private fetchFn;
+  private headers;
+  private extraBody;
   constructor(options: ResponsesAdapterOptions);
   protected buildRequest(request: NormalizedRequest): ResponsesAPIRequest;
   protected runStream(providerRequest: ResponsesAPIRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
@@ -648,7 +663,9 @@ type MessagesAdapterOptions = {
   apiKey: string;
   apiVersion?: string;
   baseUrl?: string; /** 可注入自定义 fetch 实现（用于测试／代理） */
-  fetch?: FetchFn;
+  fetch?: FetchFn; /** 额外请求头；后写覆盖内置 x-api-key / Content-Type / anthropic-version */
+  headers?: Record<string, string>; /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 type MessagesAPIRequest = {
   model: string;
@@ -666,6 +683,8 @@ type MessagesAPIRequest = {
   thinking?: {
     type: "enabled";
     budget_tokens: number;
+  } | {
+    type: "disabled";
   };
   stream: true;
 };
@@ -706,6 +725,8 @@ declare class MessagesAdapter extends AdapterBase {
   private apiVersion;
   private baseUrl;
   private fetchFn;
+  private headers;
+  private extraBody;
   constructor(options: MessagesAdapterOptions);
   protected buildRequest(request: NormalizedRequest): MessagesAPIRequest;
   protected runStream(providerRequest: MessagesAPIRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
@@ -715,7 +736,9 @@ declare class MessagesAdapter extends AdapterBase {
 type ChatCompletionsAdapterOptions = {
   apiKey: string;
   baseUrl?: string;
-  fetch?: FetchFn;
+  fetch?: FetchFn; /** 额外请求头；后写覆盖内置 Authorization / Content-Type */
+  headers?: Record<string, string>; /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 type ChatRequest = {
   model: string;
@@ -729,7 +752,8 @@ type ChatRequest = {
   };
   metadata?: Record<string, string>;
   temperature?: number;
-  max_tokens?: number;
+  max_tokens?: number; /** Portable reasoningLevel → reasoning_effort */
+  reasoning_effort?: string;
   stream: true;
   n: 1;
 };
@@ -763,6 +787,8 @@ declare class ChatCompletionsAdapter extends AdapterBase {
   private apiKey;
   private baseUrl;
   private fetchFn;
+  private headers;
+  private extraBody;
   constructor(options: ChatCompletionsAdapterOptions);
   protected buildRequest(request: NormalizedRequest): ChatRequest;
   protected runStream(providerRequest: ChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
@@ -772,13 +798,16 @@ declare class ChatCompletionsAdapter extends AdapterBase {
 type OllamaAdapterOptions = {
   /** Ollama 服务地址，默认 http://localhost:11434 */baseUrl?: string; /** 可选 API key（用于需要认证的代理场景） */
   apiKey?: string; /** 可注入自定义 fetch 实现 */
-  fetch?: FetchFn;
+  fetch?: FetchFn; /** 额外请求头；后写覆盖内置 Content-Type / Authorization */
+  headers?: Record<string, string>; /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 type OllamaChatRequest = {
   model: string;
   messages: OllamaMessage[];
   stream: true;
-  tools?: OllamaTool[];
+  tools?: OllamaTool[]; /** Portable reasoningLevel → think；minimal/xhigh/max 不支持 */
+  think?: boolean | "low" | "medium" | "high";
   options?: {
     temperature?: number;
     num_predict?: number;
@@ -811,6 +840,8 @@ declare class OllamaAdapter extends AdapterBase {
   private baseUrl;
   private apiKey;
   private fetchFn;
+  private headers;
+  private extraBody;
   constructor(options?: OllamaAdapterOptions);
   protected buildRequest(request: NormalizedRequest): OllamaChatRequest;
   protected runStream(providerRequest: OllamaChatRequest, factory: EventFactory, request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
@@ -857,7 +888,8 @@ type MockHandlerContext = {
   previousReplay: ReplayItem[];
   pendingToolCalls: readonly ToolCallItem[];
   history: readonly MockHistoryRecord[]; /** 请求的 AbortSignal，handler 可检查 signal.aborted 提前退出。 */
-  signal?: AbortSignal;
+  signal?: AbortSignal; /** 当前请求的 portable reasoningLevel（若设置）。 */
+  reasoningLevel?: ReasoningLevel;
 };
 type MockWarningStep = {
   type: "warning";
@@ -1200,6 +1232,52 @@ declare function createCompletionGate(): {
   tryComplete(): boolean;
 };
 //#endregion
+//#region src/helpers/provider-request-options.d.ts
+/**
+ * Provider 请求 headers / body 扩展合并
+ *
+ * 供真实后端 adapter 构造选项 `headers` / `extraBody` 使用：
+ * - headers：内置鉴权头为基，自定义后写覆盖
+ * - extraBody：已构建 body 为基，额外字段浅层 spread，同名顶层键可覆盖
+ */
+/** 合并内置 headers 与自定义 headers；自定义后写覆盖同名键。 */
+declare function mergeProviderHeaders(base: Record<string, string>, custom?: Record<string, string>): Record<string, string>;
+/**
+ * 将构造期 extraBody 浅层合并到已构建的 provider body。
+ * 无 extraBody 时原样返回；有则允许覆盖同名顶层键。
+ */
+declare function applyExtraBody<T extends object>(body: T, extraBody?: Record<string, unknown>): T;
+//#endregion
+//#region src/helpers/reasoning-level.d.ts
+declare const REASONING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+declare const REASONING_LEVEL_SET: ReadonlySet<string>;
+type OpenAIReasoningEffort = ReasoningLevel;
+type MessagesThinkingConfig = {
+  type: "disabled";
+} | {
+  type: "enabled";
+  budget_tokens: number;
+};
+type OllamaThinkValue = false | "low" | "medium" | "high";
+/** 若 level 不在 supported 集合内则抛 AIRequestError。 */
+declare function assertSupportedReasoningLevel(level: ReasoningLevel, supported: ReadonlySet<ReasoningLevel>, adapterKind: string): void;
+/** Responses API：`reasoning: { effort }` */
+declare function mapResponsesReasoning(level: ReasoningLevel): {
+  effort: OpenAIReasoningEffort;
+};
+/** Chat Completions：顶层 `reasoning_effort` */
+declare function mapChatCompletionsReasoningEffort(level: ReasoningLevel): OpenAIReasoningEffort;
+/**
+ * Messages thinking budget。
+ * 基于 maxTokens 按比例推导，clamp 到 [1024, max(1024, maxTokens - 1)]，
+ * 满足 Anthropic budget_tokens < max_tokens。
+ */
+declare function mapMessagesThinkingBudget(level: Exclude<ReasoningLevel, "none">, maxTokens: number): number;
+/** Messages API：`thinking` 字段 */
+declare function mapMessagesThinking(level: ReasoningLevel, maxTokens: number): MessagesThinkingConfig;
+/** Ollama：`think` 字段；minimal/xhigh/max 不支持 */
+declare function mapOllamaThink(level: ReasoningLevel): OllamaThinkValue;
+//#endregion
 //#region src/helpers/request-mapper.d.ts
 declare class NormalizedRequestMapper {
   readonly kind: string;
@@ -1228,5 +1306,5 @@ declare class NormalizedRequestMapper {
   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 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 };
+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, type MessagesThinkingConfig, 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 OllamaThinkValue, type OpaqueEnvelopeResult, type OpaqueItem, type OpenAIReasoningEffort, type OpenProviderJsonStreamOptions, type OpenedProviderStream, type OutputItem, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, type ProviderStreamBatch, type ProviderStreamBatchOptions, REASONING_LEVELS, REASONING_LEVEL_SET, type ReasoningCompletedEvent, type ReasoningDeltaEvent, type ReasoningItem, type ReasoningLevel, 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, applyExtraBody, assertMockRequest, assertOpaqueReplayEnvelope, assertSupportedReasoningLevel, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createChatCompletionsSseParser, createCompletionGate, createEventFactory, createNdjsonLineParser, createSseJsonParser, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, iterateProviderStreamBatches, jsonBlock, mapChatCompletionsReasoningEffort, mapMessagesThinking, mapMessagesThinkingBudget, mapOllamaThink, mapReasoningVisibility, mapResponsesReasoning, mapStopReason, measureJsonDepth, mergeProviderHeaders, 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

package/dist/index.mjs

@@ -80,6 +80,15 @@ const TOOL_RESULT_OUTCOMES = /* @__PURE__ */ new Set([
 	"rejected"
 ]);
 const INCLUDE_MODES = /* @__PURE__ */ new Set(["off", "best_effort"]);
+const REASONING_LEVELS$1 = /* @__PURE__ */ new Set([
+	"none",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+]);
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -248,6 +257,9 @@ function validateRequest(request) {
 			message: "maxOutputTokens must be a positive integer"
 		});
 	}
+	if (request.reasoningLevel !== void 0) {
+		if (typeof request.reasoningLevel !== "string" || !REASONING_LEVELS$1.has(request.reasoningLevel)) pushIssue(issues, "reasoningLevel", "REASONING_LEVEL_INVALID", "reasoningLevel must be one of: none, minimal, low, medium, high, xhigh, max");
+	}
 	if (request.include !== void 0) validateInclude(request.include, issues);
 	if (request.metadata !== void 0) {
 		if (!isRecord(request.metadata)) pushIssue(issues, "metadata", "METADATA_INVALID", "metadata must be an object");
@@ -1660,6 +1672,104 @@ function createCompletionGate() {
 	};
 }
 //#endregion
+//#region src/helpers/provider-request-options.ts
+/**
+* Provider 请求 headers / body 扩展合并
+*
+* 供真实后端 adapter 构造选项 `headers` / `extraBody` 使用：
+* - headers：内置鉴权头为基，自定义后写覆盖
+* - extraBody：已构建 body 为基，额外字段浅层 spread，同名顶层键可覆盖
+*/
+/** 合并内置 headers 与自定义 headers；自定义后写覆盖同名键。 */
+function mergeProviderHeaders(base, custom) {
+	if (!custom) return base;
+	return {
+		...base,
+		...custom
+	};
+}
+/**
+* 将构造期 extraBody 浅层合并到已构建的 provider body。
+* 无 extraBody 时原样返回；有则允许覆盖同名顶层键。
+*/
+function applyExtraBody(body, extraBody) {
+	if (!extraBody) return body;
+	return {
+		...body,
+		...extraBody
+	};
+}
+//#endregion
+//#region src/helpers/reasoning-level.ts
+/**
+* Portable reasoningLevel → provider wire 字段映射
+*
+* 第一版只处理 level 枚举；budget/summary 等特化字段不在此层。
+* 无法映射的 level 抛 AIRequestError(UNSUPPORTED_REASONING_LEVEL)。
+*/
+const REASONING_LEVELS = [
+	"none",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+const REASONING_LEVEL_SET = new Set(REASONING_LEVELS);
+const MESSAGES_BUDGET_RATIOS = {
+	minimal: .02,
+	low: .1,
+	medium: .3,
+	high: .6,
+	xhigh: .9,
+	max: .95
+};
+const OLLAMA_SUPPORTED = /* @__PURE__ */ new Set([
+	"none",
+	"low",
+	"medium",
+	"high"
+]);
+/** 若 level 不在 supported 集合内则抛 AIRequestError。 */
+function assertSupportedReasoningLevel(level, supported, adapterKind) {
+	if (supported.has(level)) return;
+	throw new AIRequestError(`reasoningLevel "${level}" is not supported by the ${adapterKind} adapter`, "UNSUPPORTED_REASONING_LEVEL");
+}
+/** Responses API：`reasoning: { effort }` */
+function mapResponsesReasoning(level) {
+	return { effort: level };
+}
+/** Chat Completions：顶层 `reasoning_effort` */
+function mapChatCompletionsReasoningEffort(level) {
+	return level;
+}
+/**
+* Messages thinking budget。
+* 基于 maxTokens 按比例推导，clamp 到 [1024, max(1024, maxTokens - 1)]，
+* 满足 Anthropic budget_tokens < max_tokens。
+*/
+function mapMessagesThinkingBudget(level, maxTokens) {
+	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` 字段 */
+function mapMessagesThinking(level, maxTokens) {
+	if (level === "none") return { type: "disabled" };
+	return {
+		type: "enabled",
+		budget_tokens: mapMessagesThinkingBudget(level, maxTokens)
+	};
+}
+/** Ollama：`think` 字段；minimal/xhigh/max 不支持 */
+function mapOllamaThink(level) {
+	assertSupportedReasoningLevel(level, OLLAMA_SUPPORTED, "ollama");
+	if (level === "none") return false;
+	return level;
+}
+//#endregion
 //#region src/helpers/request-mapper.ts
 var NormalizedRequestMapper = class {
 	kind;
@@ -1836,11 +1946,15 @@ var ResponsesAdapter = class extends AdapterBase {
 	apiKey;
 	baseUrl;
 	fetchFn;
+	headers;
+	extraBody;
 	constructor(options) {
 		super();
 		this.apiKey = options.apiKey;
 		this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
 		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.headers = options.headers;
+		this.extraBody = options.extraBody;
 	}
 	buildRequest(request) {
 		const input = [];
@@ -1918,7 +2032,8 @@ var ResponsesAdapter = class extends AdapterBase {
 		if (request.temperature !== void 0) body.temperature = request.temperature;
 		if (request.maxOutputTokens !== void 0) body.max_output_tokens = request.maxOutputTokens;
 		if (request.metadata) body.metadata = request.metadata;
-		return body;
+		if (request.reasoningLevel !== void 0) body.reasoning = mapResponsesReasoning(request.reasoningLevel);
+		return applyExtraBody(body, this.extraBody);
 	}
 	async *runStream(providerRequest, factory, request) {
 		const auxiliary = this.createAuxiliaryState(request);
@@ -1926,10 +2041,10 @@ var ResponsesAdapter = class extends AdapterBase {
 		const { reader } = await openProviderJsonStream({
 			fetchFn: this.fetchFn,
 			url: `${this.baseUrl}/responses`,
-			headers: {
+			headers: mergeProviderHeaders({
 				"Content-Type": "application/json",
 				Authorization: `Bearer ${this.apiKey}`
-			},
+			}, this.headers),
 			body: providerRequest,
 			signal: request.signal
 		});
@@ -2240,12 +2355,16 @@ var MessagesAdapter = class extends AdapterBase {
 	apiVersion;
 	baseUrl;
 	fetchFn;
+	headers;
+	extraBody;
 	constructor(options) {
 		super();
 		this.apiKey = options.apiKey;
 		this.apiVersion = options.apiVersion ?? "2023-06-01";
 		this.baseUrl = options.baseUrl ?? "https://api.anthropic.com/v1";
 		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.headers = options.headers;
+		this.extraBody = options.extraBody;
 	}
 	buildRequest(request) {
 		const messages = [];
@@ -2351,7 +2470,8 @@ var MessagesAdapter = class extends AdapterBase {
 			})
 		});
 		if (request.temperature !== void 0) body.temperature = request.temperature;
-		return body;
+		if (request.reasoningLevel !== void 0) body.thinking = mapMessagesThinking(request.reasoningLevel, body.max_tokens);
+		return applyExtraBody(body, this.extraBody);
 	}
 	async *runStream(providerRequest, factory, request) {
 		const auxiliary = this.createAuxiliaryState(request);
@@ -2360,11 +2480,11 @@ var MessagesAdapter = class extends AdapterBase {
 		const { reader, headers } = await openProviderJsonStream({
 			fetchFn: this.fetchFn,
 			url: `${this.baseUrl}/messages`,
-			headers: {
+			headers: mergeProviderHeaders({
 				"Content-Type": "application/json",
 				"x-api-key": this.apiKey,
 				"anthropic-version": this.apiVersion
-			},
+			}, this.headers),
 			body: providerRequest,
 			signal: request.signal
 		});
@@ -2639,11 +2759,15 @@ var ChatCompletionsAdapter = class extends AdapterBase {
 	apiKey;
 	baseUrl;
 	fetchFn;
+	headers;
+	extraBody;
 	constructor(options) {
 		super();
 		this.apiKey = options.apiKey;
 		this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
 		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.headers = options.headers;
+		this.extraBody = options.extraBody;
 	}
 	buildRequest(request) {
 		const messages = [];
@@ -2737,7 +2861,8 @@ var ChatCompletionsAdapter = class extends AdapterBase {
 		if (request.temperature !== void 0) body.temperature = request.temperature;
 		if (request.maxOutputTokens !== void 0) body.max_tokens = request.maxOutputTokens;
 		if (request.metadata) body.metadata = request.metadata;
-		return body;
+		if (request.reasoningLevel !== void 0) body.reasoning_effort = mapChatCompletionsReasoningEffort(request.reasoningLevel);
+		return applyExtraBody(body, this.extraBody);
 	}
 	async *runStream(providerRequest, factory, request) {
 		const auxiliary = this.createAuxiliaryState(request);
@@ -2745,10 +2870,10 @@ var ChatCompletionsAdapter = class extends AdapterBase {
 		const { reader } = await openProviderJsonStream({
 			fetchFn: this.fetchFn,
 			url: `${this.baseUrl}/chat/completions`,
-			headers: {
+			headers: mergeProviderHeaders({
 				"Content-Type": "application/json",
 				Authorization: `Bearer ${this.apiKey}`
-			},
+			}, this.headers),
 			body: providerRequest,
 			signal: request.signal
 		});
@@ -2974,11 +3099,15 @@ var OllamaAdapter = class extends AdapterBase {
 	baseUrl;
 	apiKey;
 	fetchFn;
+	headers;
+	extraBody;
 	constructor(options = {}) {
 		super();
 		this.baseUrl = options.baseUrl ?? "http://localhost:11434";
 		this.apiKey = options.apiKey;
 		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.headers = options.headers;
+		this.extraBody = options.extraBody;
 	}
 	buildRequest(request) {
 		const messages = [];
@@ -3076,7 +3205,8 @@ var OllamaAdapter = class extends AdapterBase {
 			if (request.temperature !== void 0) body.options.temperature = request.temperature;
 			if (request.maxOutputTokens !== void 0) body.options.num_predict = request.maxOutputTokens;
 		}
-		return body;
+		if (request.reasoningLevel !== void 0) body.think = mapOllamaThink(request.reasoningLevel);
+		return applyExtraBody(body, this.extraBody);
 	}
 	async *runStream(providerRequest, factory, request) {
 		const auxiliary = this.createAuxiliaryState(request);
@@ -3088,7 +3218,7 @@ var OllamaAdapter = class extends AdapterBase {
 		const { reader } = await openProviderJsonStream({
 			fetchFn: this.fetchFn,
 			url: `${this.baseUrl}/api/chat`,
-			headers,
+			headers: mergeProviderHeaders(headers, this.headers),
 			body: providerRequest,
 			signal: request.signal
 		});
@@ -3257,7 +3387,7 @@ var MockAdapter = class extends AdapterBase {
 	}
 	async buildRequest(request) {
 		const turnIndex = this.cursor;
-		const context = this.buildHandlerContext(turnIndex, request.signal);
+		const context = this.buildHandlerContext(turnIndex, request);
 		const remainingPendingToolCalls = consumePendingToolCalls(this.pendingToolCalls, request.input);
 		const handlerResult = this.handler(request, context);
 		this.cursor += 1;
@@ -3396,7 +3526,7 @@ var MockAdapter = class extends AdapterBase {
 			rawResponseId: completion.rawResponseId
 		}, factory);
 	}
-	buildHandlerContext(turnIndex, signal) {
+	buildHandlerContext(turnIndex, request) {
 		return {
 			turnIndex,
 			previousReplay: this.previousReplay.map(cloneItem),
@@ -3406,7 +3536,8 @@ var MockAdapter = class extends AdapterBase {
 				replay: record.replay.map(cloneItem),
 				toolCalls: record.toolCalls.map(cloneItem)
 			})),
-			signal
+			signal: request.signal,
+			reasoningLevel: request.reasoningLevel
 		};
 	}
 };
@@ -3632,6 +3763,6 @@ function cloneItem(item) {
 	return structuredClone(item);
 }
 //#endregion
-export { AIError, AIMappingError, AIProviderError, AIRequestError, AIStreamError, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, ChatCompletionsAdapter, IncrementalStreamParser, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, MessagesAdapter, MockAdapter, NormalizedRequestMapper, OllamaAdapter, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, ResponsesAdapter, 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 };
+export { AIError, AIMappingError, AIProviderError, AIRequestError, AIStreamError, AdapterAuxiliaryState, AdapterBase, AuxiliaryCollector, ChatCompletionsAdapter, IncrementalStreamParser, MAX_OPAQUE_JSON_DEPTH, MAX_OPAQUE_PAYLOAD_BYTES, MessagesAdapter, MockAdapter, NormalizedRequestMapper, OllamaAdapter, PROVIDER_ERROR_MESSAGE_MAX_LEN, PROVIDER_ERROR_RAW_BODY_THRESHOLD, REASONING_LEVELS, REASONING_LEVEL_SET, ResponsesAdapter, WarningCode, aggregateEvents, applyExtraBody, assertMockRequest, assertOpaqueReplayEnvelope, assertSupportedReasoningLevel, assertValidRequest, blockToText, collectStream, contentBlocksToText, createAIClient, createChatCompletionsSseParser, createCompletionGate, createEventFactory, createNdjsonLineParser, createSseJsonParser, emitMalformedStreamWarning, extractProviderErrorMessage, extractText, imageBlock, iterateProviderStreamBatches, jsonBlock, mapChatCompletionsReasoningEffort, mapMessagesThinking, mapMessagesThinkingBudget, mapOllamaThink, mapReasoningVisibility, mapResponsesReasoning, mapStopReason, measureJsonDepth, mergeProviderHeaders, 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.mjs.map