@codehz/ai 0.8.2 → 0.9.1

package/dist/index.mjs

@@ -5,8 +5,10 @@
 * KnownAdapterKind 覆盖内置 adapter；
 * AdapterKind 额外接受任意 string，便于自定义 backend 扩展（无需改库联合类型）。
 */
+/** 内置 adapter kind 列表。 */
 const KNOWN_ADAPTER_KINDS = [
 	"chat-completions",
+	"delta-completions",
 	"messages",
 	"responses",
 	"ollama",
@@ -34,6 +36,7 @@ const REASONING_LEVEL_SET = new Set(REASONING_LEVELS);
 *
 * runtime.errors 与 events 均从此导出，避免手工双表漂移。
 */
+/** 标准 warning 代码常量；事件和响应均可携带这些代码。 */
 const WarningCode = {
 	/** replay fidelity 低于预期 */
 	REPLAY_FIDELITY_LOW: "REPLAY_FIDELITY_LOW",
@@ -87,7 +90,7 @@ function streamWarningKey(warning) {
 }
 //#endregion
 //#region src/types/compress.ts
-/** 探测 adapter 是否实现 compress（不依赖 kind 硬编码）。 */
+/** 探测 adapter 是否实现上下文压缩能力。 */
 function supportsContextCompress(adapter) {
 	return typeof adapter.compress === "function";
 }
@@ -99,11 +102,7 @@ const DEFAULT_INCLUDE = {
 	providerMetadata: "best_effort"
 };
 /**
-* 归一化请求：
-* 1. 合并 defaults
-* 2. 填充 include 默认值
-* 3. 生成 requestId
-* 4. 返回 provider 映射所需的归一化请求
+* 归一化请求：合并 defaults、填充 include 默认值并生成 requestId。
 */
 function normalizeRequest(request, options) {
 	const { model, defaults } = options;
@@ -121,6 +120,7 @@ function normalizeRequest(request, options) {
 }
 //#endregion
 //#region src/runtime/client.ts
+/** 创建统一 AI 客户端；请求级字段覆盖 defaults，signal 可在客户端级设置。 */
 function createAIClient(options) {
 	const { adapter, model, defaults, signal: defaultSignal } = options;
 	return { stream(request) {
@@ -147,6 +147,7 @@ function mergeAbortSignals(...signals) {
 }
 //#endregion
 //#region src/runtime/errors.ts
+/** 所有运行时错误的基类。 */
 var AIError = class extends Error {
 	code;
 	name;
@@ -220,24 +221,28 @@ var AIRecoverableError = class extends AIError {
 };
 //#endregion
 //#region src/canonical/content.ts
+/** 创建文本内容块。 */
 function textBlock(text) {
 	return {
 		type: "text",
 		text
 	};
 }
+/** 创建 JSON 内容块。 */
 function jsonBlock(json) {
 	return {
 		type: "json",
 		json
 	};
 }
+/** 创建图片内容块；imageUrl 可为 URL 或 data URL。 */
 function imageBlock(imageUrl) {
 	return {
 		type: "image",
 		imageUrl
 	};
 }
+/** 创建 provider 专有 opaque 内容块。 */
 function opaqueBlock(payload) {
 	return {
 		type: "opaque",
@@ -283,6 +288,7 @@ function coalesceContentBlocks(blocks) {
 * 简单场景下 replay 与 output 一致。
 * 复杂场景（需要 opaque continuation）由 adapter 自行扩展。
 */
+/** 从 output items 构建 replay；opaque continuation 可由 adapter 额外扩展。 */
 function replayFromOutput(output) {
 	return output.map((item) => {
 		switch (item.type) {
@@ -299,6 +305,7 @@ function replayFromOutput(output) {
 /**
 * 从 OutputItem 数组中提取所有 message 类型 item 的文本内容。
 */
+/** 从 output 中提取所有消息 item 的文本内容。 */
 function extractText(output) {
 	return output.filter((item) => item.type === "message").flatMap((m) => m.content).filter((b) => b.type === "text").map((b) => b.text).join("");
 }
@@ -637,6 +644,7 @@ function streamProtocolError(message) {
 }
 //#endregion
 //#region src/stream/collect-stream.ts
+/** 消费完整个事件流并聚合为 AIResponse；适用于不需要逐事件处理的调用方。 */
 async function collectStream(stream) {
 	const state = createAggregatorState();
 	for await (const event of stream) aggregateEvent(state, event);
@@ -669,9 +677,11 @@ const STOP_REASON_MAP = {
 	MISSING_THOUGHT_SIGNATURE: "error",
 	error: "error"
 };
+/** 将 provider stop/finish reason 映射为规范化 StopReason。 */
 function mapStopReason(providerReason) {
 	return STOP_REASON_MAP[providerReason] ?? "unknown";
 }
+/** 根据 thinking 和 redacted 标记推断 reasoning 可见性。 */
 function mapReasoningVisibility(hasThinking, hasRedacted) {
 	if (hasRedacted) return "redacted";
 	if (hasThinking) return "full";
@@ -679,6 +689,7 @@ function mapReasoningVisibility(hasThinking, hasRedacted) {
 }
 //#endregion
 //#region src/canonical/items.ts
+/** 创建消息 item；可用 overrides 补充 id、role 和 citations。 */
 function messageItem(content, overrides) {
 	return {
 		type: "message",
@@ -687,6 +698,7 @@ function messageItem(content, overrides) {
 		content
 	};
 }
+/** 创建 reasoning item。 */
 function reasoningItem(content, visibility = "full", id) {
 	return {
 		type: "reasoning",
@@ -695,6 +707,7 @@ function reasoningItem(content, visibility = "full", id) {
 		content
 	};
 }
+/** 创建客户端工具调用 item。 */
 function toolCallItem(id, name, argumentsText) {
 	return {
 		type: "tool_call",
@@ -703,6 +716,7 @@ function toolCallItem(id, name, argumentsText) {
 		argumentsText
 	};
 }
+/** 创建客户端工具结果 item。 */
 function toolResultItem(callId, toolName, outcome, content) {
 	return {
 		type: "tool_result",
@@ -712,6 +726,7 @@ function toolResultItem(callId, toolName, outcome, content) {
 		content
 	};
 }
+/** 创建 opaque item，通常用于 provider replay。 */
 function opaqueItem(source, purpose, payload, id) {
 	return {
 		type: "opaque",
@@ -721,6 +736,7 @@ function opaqueItem(source, purpose, payload, id) {
 		payload
 	};
 }
+/** 创建 provider 托管工具调用 item。 */
 function serverToolCallItem(id, tool, overrides) {
 	return {
 		type: "server_tool_call",
@@ -729,6 +745,7 @@ function serverToolCallItem(id, tool, overrides) {
 		...overrides
 	};
 }
+/** 创建 provider 托管工具结果 item。 */
 function serverToolResultItem(callId, tool, outcome, content, overrides) {
 	return {
 		type: "server_tool_result",
@@ -739,6 +756,7 @@ function serverToolResultItem(callId, tool, outcome, content, overrides) {
 		...overrides
 	};
 }
+/** 创建 MCP 等 provider 托管工具发现 item。 */
 function serverToolDiscoveryItem(id, serverLabel, tools, overrides) {
 	return {
 		type: "server_tool_discovery",
@@ -1091,11 +1109,11 @@ var AdapterAuxiliaryState = class {
 			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 (this.request.include?.usage === "required" && !built.usage) events.push(factory.responseWarning("Usage information was not provided by the provider", WarningCode.USAGE_MISSING));
+		if (this.request.include?.billing === "required") {
 			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));
-		}
+		} else if (built.billing?.isEstimated) events.push(factory.responseWarning("Billing amount is an estimate", WarningCode.BILLING_ESTIMATED));
 		return {
 			events,
 			usage: built.usage,
@@ -1585,7 +1603,7 @@ function createProviderJsonStreamSession(host) {
 /**
 * HTTP adapter 共享基类与构造选项
 *
-* 收敛五家真实后端 adapter 的：
+* 收敛真实 HTTP adapter 的：
 * - apiKey / baseUrl / fetch / headers / extraBody 字段赋值
 * - 默认 baseUrl 解析
 * - beginJsonStream：open → batches → complete session
@@ -1923,6 +1941,7 @@ async function* finalizeStreamTurn(session, items, options = {}) {
 */
 const OPAQUE_SOURCE = {
 	CHAT_COMPLETIONS: "chat.completions",
+	DELTA_COMPLETIONS: "delta.completions",
 	MESSAGES: "messages",
 	OLLAMA: "ollama",
 	GEMINI: "gemini",
@@ -2169,7 +2188,7 @@ function mapServerTools(serverTools) {
 *
 * 同时服务 stream（/responses）与 compress（/responses/compact）。
 */
-const mapper$7 = new NormalizedRequestMapper("responses");
+const mapper$8 = new NormalizedRequestMapper("responses");
 /** compact replay opaque：整份 wire output window 保真回传 */
 const RESPONSES_COMPACTED_WINDOW_KIND = "compacted_window";
 function isReplayCanonicalInput(item) {
@@ -2189,13 +2208,13 @@ function readNonEmptyString(value, maxLen = 256) {
 * - user 纯 text/json：仍发 string，避免无谓 shape churn
 */
 function mapResponsesMessageContent(role, blocks, field) {
-	if (role !== "user") return mapper$7.textFromBlocks(blocks, field);
-	mapper$7.ensureBlocks(blocks, field, [
+	if (role !== "user") return mapper$8.textFromBlocks(blocks, field);
+	mapper$8.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
 	], "only text/json/image blocks are supported");
-	if (!blocks.some((block) => block.type === "image")) return mapper$7.textFromBlocks(blocks, field);
+	if (!blocks.some((block) => block.type === "image")) return mapper$8.textFromBlocks(blocks, field);
 	return blocks.map((block) => {
 		if (block.type === "text") return {
 			type: "input_text",
@@ -2209,16 +2228,16 @@ function mapResponsesMessageContent(role, blocks, field) {
 			type: "input_image",
 			image_url: block.imageUrl
 		};
-		throw new AIRequestError(`${mapper$7.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+		throw new AIRequestError(`${mapper$8.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
 function mapResponsesToolResultOutput(blocks, field) {
-	mapper$7.ensureBlocks(blocks, field, [
+	mapper$8.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
 	], "only text/json/image blocks are supported");
-	if (!blocks.some((block) => block.type === "image")) return mapper$7.textFromBlocks(blocks, field);
+	if (!blocks.some((block) => block.type === "image")) return mapper$8.textFromBlocks(blocks, field);
 	return blocks.map((block) => {
 		if (block.type === "text") return {
 			type: "input_text",
@@ -2232,11 +2251,11 @@ function mapResponsesToolResultOutput(blocks, field) {
 			type: "input_image",
 			image_url: block.imageUrl
 		};
-		throw new AIRequestError(`${mapper$7.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+		throw new AIRequestError(`${mapper$8.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
 function mapReasoningInput(item, index) {
-	const text = mapper$7.textFromBlocks(mapper$7.ensureReasoningBlocks(item.content, "reasoning content"), "reasoning content");
+	const text = mapper$8.textFromBlocks(mapper$8.ensureReasoningBlocks(item.content, "reasoning content"), "reasoning content");
 	const id = item.id && item.id.length > 0 ? item.id : `reasoning_replay_${index}`;
 	if (item.visibility === "full") return {
 		type: "reasoning",
@@ -2346,7 +2365,7 @@ function mapResponsesCore(request, options) {
 		usedCompactedWindow
 	};
 	if (previousResponseId && !usedCompactedWindow) mapped.previousResponseId = previousResponseId;
-	if (request.instructions) mapped.instructions = mapper$7.mapInstructions(request.instructions);
+	if (request.instructions) mapped.instructions = mapper$8.mapInstructions(request.instructions);
 	return mapped;
 }
 /** 构建 Responses 流式请求体；调用方再 `withExtraBody` 合并构造期扩展字段。 */
@@ -2359,7 +2378,7 @@ function buildResponsesRequest(request, options) {
 	};
 	if (core.previousResponseId) body.previous_response_id = core.previousResponseId;
 	if (core.instructions) body.instructions = core.instructions;
-	const functionTools = mapper$7.mapToolsIfPresent(request.tools, (t) => ({
+	const functionTools = mapper$8.mapToolsIfPresent(request.tools, (t) => ({
 		type: "function",
 		name: t.name,
 		description: t.description,
@@ -2368,7 +2387,7 @@ function buildResponsesRequest(request, options) {
 	const serverTools = mapServerTools(request.serverTools);
 	const tools = [...functionTools, ...serverTools];
 	if (tools.length > 0) body.tools = tools;
-	body.tool_choice = mapper$7.mapToolChoice(request.toolChoice, {
+	body.tool_choice = mapper$8.mapToolChoice(request.toolChoice, {
 		auto: "auto",
 		none: "none",
 		tool: (name) => ({
@@ -3135,6 +3154,7 @@ function createResponsesSseProcessor(factory) {
 * 编排层：buildRequest + runStream（open → SSE 处理 → complete）。
 * 可选能力：compress → POST /responses/compact（ContextCompressCapable）。
 */
+/** OpenAI Responses API 适配器；支持原生流式响应和上下文压缩。 */
 var ResponsesAdapter = class extends HttpAdapterBase {
 	kind = "responses";
 	isSyntheticStream = false;
@@ -3258,7 +3278,7 @@ function parseImageDataUrl(imageUrl) {
 /**
 * MessagesAdapter — request 映射
 */
-const mapper$6 = new NormalizedRequestMapper("messages");
+const mapper$7 = new NormalizedRequestMapper("messages");
 function isMessagesReplayContentBlock(value) {
 	if (!value || typeof value !== "object" || !("type" in value)) return false;
 	const block = value;
@@ -3320,33 +3340,33 @@ function canonicalToMessagesBlock(b, field = "canonical mapping") {
 	throw new AIRequestError(`messages does not support content block type "${b.type}" in ${field}`, "UNSUPPORTED_CONTENT_BLOCK");
 }
 function mapMessagesUserContent(blocks, field) {
-	mapper$6.ensureBlocks(blocks, field, [
+	mapper$7.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
 	], "only text/json/image blocks are supported");
 	if (!blocks.some((block) => block.type === "image")) {
-		const supportedContent = mapper$6.ensureTextBlocks(blocks, field);
+		const supportedContent = mapper$7.ensureTextBlocks(blocks, field);
 		if (supportedContent.length === 1 && supportedContent[0]?.type === "text") return supportedContent[0].text;
 		return supportedContent.map((block) => canonicalToMessagesBlock(block, field));
 	}
 	return blocks.map((block) => canonicalToMessagesBlock(block, field));
 }
 function mapMessagesToolResultContent(blocks, field) {
-	mapper$6.ensureBlocks(blocks, field, [
+	mapper$7.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
 	], "only text/json/image blocks are supported");
-	if (!blocks.some((block) => block.type === "image")) return mapper$6.textFromBlocks(blocks, field);
+	if (!blocks.some((block) => block.type === "image")) return mapper$7.textFromBlocks(blocks, field);
 	return blocks.map((block) => canonicalToMessagesBlock(block, field));
 }
 function buildMessagesRequest(request, options) {
-	mapper$6.assertNoServerTools(request.serverTools);
+	mapper$7.assertNoServerTools(request.serverTools);
 	const messages = [];
 	let systemPrompt;
 	let pendingToolResultMessage;
-	if (request.instructions) systemPrompt = mapper$6.mapInstructions(request.instructions);
+	if (request.instructions) systemPrompt = mapper$7.mapInstructions(request.instructions);
 	for (const item of request.input) {
 		if (item.type !== "tool_result") pendingToolResultMessage = void 0;
 		switch (item.type) {
@@ -3359,7 +3379,7 @@ function buildMessagesRequest(request, options) {
 					});
 					break;
 				}
-				const supportedContent = mapper$6.ensureTextBlocks(item.content, field);
+				const supportedContent = mapper$7.ensureTextBlocks(item.content, field);
 				if (supportedContent.length === 1 && supportedContent[0]?.type === "text") messages.push({
 					role: "assistant",
 					content: supportedContent[0].text
@@ -3376,7 +3396,7 @@ function buildMessagesRequest(request, options) {
 					type: "tool_use",
 					id: item.id,
 					name: item.name,
-					input: mapper$6.parseToolArguments(item)
+					input: mapper$7.parseToolArguments(item)
 				};
 				if (lastMsg && lastMsg.role === "assistant" && typeof lastMsg.content !== "string") lastMsg.content.push(toolBlock);
 				else messages.push({
@@ -3406,7 +3426,7 @@ function buildMessagesRequest(request, options) {
 			case "reasoning": {
 				const block = {
 					type: "thinking",
-					thinking: contentBlocksToText(mapper$6.ensureReasoningBlocks(item.content, "reasoning content"))
+					thinking: contentBlocksToText(mapper$7.ensureReasoningBlocks(item.content, "reasoning content"))
 				};
 				const lastMsg = messages[messages.length - 1];
 				if (lastMsg && lastMsg.role === "assistant" && typeof lastMsg.content !== "string") lastMsg.content.push(block);
@@ -3421,7 +3441,7 @@ function buildMessagesRequest(request, options) {
 				if (!payload) break;
 				if (payload.role === "assistant" && "content" in payload) {
 					assertMessagesReplayContent(payload.content);
-					mapper$6.rollbackTrailingAssistantMessages(messages);
+					mapper$7.rollbackTrailingAssistantMessages(messages);
 					messages.push({
 						role: "assistant",
 						content: payload.content
@@ -3438,12 +3458,12 @@ function buildMessagesRequest(request, options) {
 		stream: true
 	};
 	if (systemPrompt) body.system = systemPrompt;
-	body.tools = mapper$6.mapToolsIfPresent(request.tools, (t) => ({
+	body.tools = mapper$7.mapToolsIfPresent(request.tools, (t) => ({
 		name: t.name,
 		description: t.description,
 		input_schema: t.inputSchema
 	}));
-	body.tool_choice = mapper$6.mapToolChoice(request.toolChoice, {
+	body.tool_choice = mapper$7.mapToolChoice(request.toolChoice, {
 		auto: { type: "auto" },
 		none: { type: "none" },
 		tool: (name) => ({
@@ -3705,6 +3725,7 @@ async function* mapMessagesStream(host, providerRequest, factory, request) {
 *
 * 编排层：buildRequest + runStream（委托 map-request / map-stream）。
 */
+/** Anthropic Messages API 适配器。 */
 var MessagesAdapter = class extends HttpAdapterBase {
 	kind = "messages";
 	isSyntheticStream = false;
@@ -3747,7 +3768,7 @@ const REASONING_FIELDS = ["reasoning_content", "reasoning"];
 /**
 * ChatCompletionsAdapter — request 映射
 */
-const mapper$4 = new NormalizedRequestMapper("chat-completions");
+const mapper$5 = new NormalizedRequestMapper("chat-completions");
 function extractReasoningText(value) {
 	if (typeof value === "string") return value;
 	if (Array.isArray(value)) return value.map(extractReasoningText).join("");
@@ -3838,7 +3859,7 @@ function buildAssistantReplayMessage(params) {
 	return replayMessage;
 }
 function mapChatUserContent(blocks, field) {
-	mapper$4.ensureBlocks(blocks, field, [
+	mapper$5.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
@@ -3857,16 +3878,16 @@ function mapChatUserContent(blocks, field) {
 			type: "image_url",
 			image_url: { url: block.imageUrl }
 		};
-		throw new AIRequestError(`${mapper$4.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+		throw new AIRequestError(`${mapper$5.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
 function mapChatToolResultContent(blocks, field) {
-	mapper$4.ensureBlocks(blocks, field, [
+	mapper$5.ensureBlocks(blocks, field, [
 		"text",
 		"json",
 		"image"
 	], "only text/json/image blocks are supported");
-	if (!blocks.some((block) => block.type === "image")) return mapper$4.textFromBlocks(blocks, field);
+	if (!blocks.some((block) => block.type === "image")) return mapper$5.textFromBlocks(blocks, field);
 	return blocks.map((block) => {
 		if (block.type === "text") return {
 			type: "text",
@@ -3880,19 +3901,19 @@ function mapChatToolResultContent(blocks, field) {
 			type: "image_url",
 			image_url: { url: block.imageUrl }
 		};
-		throw new AIRequestError(`${mapper$4.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
+		throw new AIRequestError(`${mapper$5.kind} does not support ${field} block of type "${block.type}"; only text/json/image blocks are supported`, "UNSUPPORTED_CONTENT_BLOCK");
 	});
 }
 function mapChatMessageContent(role, blocks, field) {
 	if (role === "user") return mapChatUserContent(blocks, field);
-	return mapper$4.textFromBlocks(blocks, field) || null;
+	return mapper$5.textFromBlocks(blocks, field) || null;
 }
 function buildChatCompletionsRequest(request, options) {
-	mapper$4.assertNoServerTools(request.serverTools);
+	mapper$5.assertNoServerTools(request.serverTools);
 	const messages = [];
 	if (request.instructions) messages.push({
 		role: "system",
-		content: mapper$4.mapInstructions(request.instructions)
+		content: mapper$5.mapInstructions(request.instructions)
 	});
 	for (const item of request.input) switch (item.type) {
 		case "message": {
@@ -3932,7 +3953,7 @@ function buildChatCompletionsRequest(request, options) {
 		case "reasoning":
 			messages.push({
 				role: "assistant",
-				content: mapper$4.textFromBlocks(item.content, "reasoning content")
+				content: mapper$5.textFromBlocks(item.content, "reasoning content")
 			});
 			break;
 		case "opaque": {
@@ -3940,7 +3961,7 @@ function buildChatCompletionsRequest(request, options) {
 			if (!payload) break;
 			if ("messages" in payload) {
 				assertChatReplayMessages(payload.messages, "messages");
-				mapper$4.rollbackTrailingAssistantMessages(messages);
+				mapper$5.rollbackTrailingAssistantMessages(messages);
 				for (const m of payload.messages) messages.push(m);
 			}
 			break;
@@ -3952,8 +3973,8 @@ function buildChatCompletionsRequest(request, options) {
 		stream: true,
 		n: 1
 	};
-	body.tools = mapper$4.mapToolsIfPresent(request.tools, mapOpenAiFunctionTool);
-	body.tool_choice = mapper$4.mapToolChoice(request.toolChoice, {
+	body.tools = mapper$5.mapToolsIfPresent(request.tools, mapOpenAiFunctionTool);
+	body.tool_choice = mapper$5.mapToolChoice(request.toolChoice, {
 		auto: "auto",
 		none: "none",
 		tool: (name) => ({
@@ -4188,6 +4209,7 @@ async function* mapChatCompletionsStream(host, providerRequest, factory, request
 *
 * 编排层：buildRequest + runStream（委托 map-request / map-stream）。
 */
+/** OpenAI Chat Completions API 适配器。 */
 var ChatCompletionsAdapter = class extends HttpAdapterBase {
 	kind = "chat-completions";
 	isSyntheticStream = false;
@@ -4208,6 +4230,188 @@ var ChatCompletionsAdapter = class extends HttpAdapterBase {
 	}
 };
 //#endregion
+//#region src/adapters/delta-completions/map-request.ts
+/**
+* DeltaCompletionsAdapter — request 映射
+*/
+const mapper$4 = new NormalizedRequestMapper("delta-completions");
+function isDeltaReplayMessage(value) {
+	if (!value || typeof value !== "object") return false;
+	const msg = value;
+	const role = msg.role;
+	return (role === "system" || role === "user" || role === "assistant") && typeof msg.content === "string";
+}
+function assertDeltaReplayMessages(messages, field) {
+	if (!Array.isArray(messages)) throw new AIRequestError(`Invalid opaque replay payload: ${field} must be an array`, "INVALID_OPAQUE_REPLAY");
+	for (let i = 0; i < messages.length; i++) if (!isDeltaReplayMessage(messages[i])) throw new AIRequestError(`Invalid opaque replay payload: ${field}[${i}] is not a valid delta-completions text message`, "INVALID_OPAQUE_REPLAY");
+}
+function assertTextOnlyRequest(request) {
+	mapper$4.assertNoServerTools(request.serverTools);
+	if (request.tools && request.tools.length > 0) throw new AIRequestError("delta-completions does not support tools; use ChatCompletionsAdapter", "UNSUPPORTED_TOOL");
+	if (request.toolChoice) throw new AIRequestError("delta-completions does not support toolChoice; use ChatCompletionsAdapter", "UNSUPPORTED_TOOL");
+}
+function buildDeltaCompletionsRequest(request, options) {
+	assertTextOnlyRequest(request);
+	const messages = [];
+	if (request.instructions) messages.push({
+		role: "system",
+		content: mapper$4.mapInstructions(request.instructions)
+	});
+	for (const item of request.input) switch (item.type) {
+		case "message":
+			messages.push({
+				role: item.role,
+				content: mapper$4.textFromBlocks(item.content, `input message (${item.role}) content`)
+			});
+			break;
+		case "reasoning":
+			messages.push({
+				role: "assistant",
+				content: mapper$4.textFromBlocks(item.content, "reasoning content")
+			});
+			break;
+		case "opaque": {
+			const payload = acceptOpaqueReplay(item, OPAQUE_SOURCE.DELTA_COMPLETIONS, { maxBytes: options?.maxOpaquePayloadBytes });
+			if (!payload) break;
+			if ("messages" in payload) {
+				assertDeltaReplayMessages(payload.messages, "messages");
+				mapper$4.rollbackTrailingAssistantMessages(messages);
+				for (const m of payload.messages) messages.push({
+					role: m.role,
+					content: m.content
+				});
+			}
+			break;
+		}
+		case "tool_call":
+		case "tool_result":
+		case "server_tool_call":
+		case "server_tool_result":
+		case "server_tool_discovery": throw new AIRequestError(`delta-completions does not support input item type "${item.type}"; use ChatCompletionsAdapter`, "UNSUPPORTED_TOOL");
+	}
+	const body = {
+		model: request.model,
+		messages,
+		stream: true
+	};
+	if (request.temperature !== void 0) body.temperature = request.temperature;
+	if (request.maxOutputTokens !== void 0) body.max_tokens = request.maxOutputTokens;
+	return body;
+}
+//#endregion
+//#region src/adapters/delta-completions/map-stream.ts
+/**
+* DeltaCompletionsAdapter — stream 映射
+*
+* 完成信号是 SSE 结束，不依赖 finish_reason / index / id。
+*/
+async function* mapDeltaCompletionsStream(host, providerRequest, factory, request) {
+	const session = host.beginJsonStream(factory, request);
+	const { gate } = session;
+	const items = createStreamingItemSession(factory);
+	if (request.metadata) yield factory.responseWarning("Request metadata is not supported by the Delta Completions adapter", WarningCode.UNSUPPORTED_METADATA);
+	if (request.reasoningLevel !== void 0) yield factory.responseWarning("Request reasoningLevel is not supported by the Delta Completions adapter", WarningCode.CAPABILITY_DOWNGRADE);
+	const headers = { "Content-Type": "application/json" };
+	if (host.apiKey) headers.Authorization = `Bearer ${host.apiKey}`;
+	await session.open({
+		url: `${host.baseUrl}/chat/completions`,
+		headers: host.mergeHeaders(headers),
+		body: providerRequest
+	});
+	const parser = createDataLineSseParser();
+	let responseId;
+	let accumulatedContent = "";
+	let currentMessageId = "";
+	let hasMessageStarted = false;
+	let lastFinishReason;
+	let warnedExtraChoices = false;
+	let warnedIgnoredDelta = false;
+	const ensureMessageStarted = function* (idSeed) {
+		if (!currentMessageId) currentMessageId = `msg-${idSeed}`;
+		const started = items.ensureMessageStarted(currentMessageId);
+		if (started) {
+			hasMessageStarted = true;
+			yield started;
+		}
+	};
+	for await (const batch of session.batches({
+		parser,
+		providerLabel: "Delta Completions",
+		transportLabel: "SSE event(s)",
+		incompleteMessage: "Stream ended with an incomplete Delta Completions SSE frame"
+	})) {
+		for (const warning of batch.warnings) yield warning;
+		for (const chunk of batch.items) {
+			if (chunk === null || typeof chunk !== "object") continue;
+			if ("id" in chunk && typeof chunk.id === "string" && chunk.id) responseId = chunk.id;
+			if (!("choices" in chunk) || !Array.isArray(chunk.choices) || chunk.choices.length === 0) continue;
+			if (chunk.choices.length > 1 && !warnedExtraChoices) {
+				yield factory.responseWarning("Delta Completions returned multiple choices; only the first array element is read. This adapter ignores choice.index.", WarningCode.MULTIPLE_CHOICES_IGNORED);
+				warnedExtraChoices = true;
+			}
+			const choice = chunk.choices[0];
+			if (choice === null || typeof choice !== "object") continue;
+			if ("finish_reason" in choice && typeof choice.finish_reason === "string" && choice.finish_reason) lastFinishReason = choice.finish_reason;
+			if (!("delta" in choice) || choice.delta === null || typeof choice.delta !== "object") continue;
+			const delta = choice.delta;
+			if (!warnedIgnoredDelta && ("tool_calls" in delta || "function_call" in delta || "reasoning" in delta || "reasoning_content" in delta)) {
+				yield factory.responseWarning("Delta Completions ignored non-content delta fields (tool_calls / function_call / reasoning); use ChatCompletionsAdapter for those", WarningCode.CAPABILITY_DOWNGRADE);
+				warnedIgnoredDelta = true;
+			}
+			if (!("content" in delta) || typeof delta.content !== "string" || !delta.content) continue;
+			yield* ensureMessageStarted(responseId ?? request.requestId);
+			accumulatedContent += delta.content;
+			yield items.deltaMessage(currentMessageId, textBlock(delta.content));
+		}
+	}
+	if (gate.completed) return;
+	if (hasMessageStarted && items.isActive(currentMessageId)) yield items.completeMessage(currentMessageId);
+	const stopReason = lastFinishReason ? mapStopReason(lastFinishReason) : "end_turn";
+	const assistantReplayMessage = accumulatedContent.length > 0 ? {
+		role: "assistant",
+		content: accumulatedContent
+	} : null;
+	yield* finalizeStreamTurn(session, items, {
+		stopReason,
+		rawResponseId: responseId ?? request.requestId,
+		factory,
+		maxOpaquePayloadBytes: host.maxOpaquePayloadBytes,
+		opaque: assistantReplayMessage ? opaqueItem(OPAQUE_SOURCE.DELTA_COMPLETIONS, "replay", {
+			replaceCanonical: true,
+			messages: [assistantReplayMessage]
+		}) : null
+	});
+}
+//#endregion
+//#region src/adapters/delta-completions/adapter.ts
+/**
+* DeltaCompletionsAdapter
+*
+* 残缺 OpenAI 兼容 SSE：只读 choices[0].delta.content，以流结束为完成。
+* 不要用本 adapter 对接完整 chat.completions。
+*/
+/** 残缺 chat/completions SSE 适配器。 */
+var DeltaCompletionsAdapter = class extends HttpAdapterBase {
+	kind = "delta-completions";
+	isSyntheticStream = false;
+	constructor(options) {
+		if (!options.baseUrl) throw new AIRequestError("DeltaCompletionsAdapter requires baseUrl; it does not default to the OpenAI API", "ADAPTER_OPTIONS_INVALID");
+		super(options, { baseUrl: options.baseUrl });
+	}
+	buildRequest(request) {
+		return this.withExtraBody(buildDeltaCompletionsRequest(request, { maxOpaquePayloadBytes: this.maxOpaquePayloadBytes }));
+	}
+	async *runStream(providerRequest, factory, request) {
+		yield* mapDeltaCompletionsStream({
+			beginJsonStream: this.beginJsonStream.bind(this),
+			baseUrl: this.baseUrl,
+			apiKey: this.apiKey,
+			mergeHeaders: this.mergeHeaders.bind(this),
+			maxOpaquePayloadBytes: this.maxOpaquePayloadBytes
+		}, providerRequest, factory, request);
+	}
+};
+//#endregion
 //#region src/adapters/ollama/map-request.ts
 /**
 * OllamaAdapter — request 映射
@@ -4485,6 +4689,7 @@ async function* mapOllamaStream(host, providerRequest, factory, request) {
 *
 * 编排层：buildRequest + runStream（委托 map-request / map-stream）。
 */
+/** Ollama Chat API 适配器。 */
 var OllamaAdapter = class extends HttpAdapterBase {
 	kind = "ollama";
 	isSyntheticStream = false;
@@ -4826,6 +5031,7 @@ async function* mapGeminiStream(host, providerRequest, factory, request) {
 *
 * 编排层：buildRequest + runStream（委托 map-request / map-stream）。
 */
+/** Google Gemini generateContent API 适配器。 */
 var GeminiAdapter = class extends HttpAdapterBase {
 	kind = "gemini";
 	isSyntheticStream = false;
@@ -4850,6 +5056,7 @@ var GeminiAdapter = class extends HttpAdapterBase {
 /**
 * Mock 流式包装与事件发射
 */
+/** 为静态 Mock handler 添加可配置的文本/参数流式切分。 */
 function withMockStreaming(handler, options) {
 	const defaults = resolveMockTextStreamOptions(options, "mock stream wrapper");
 	if (!defaults) throw new AIRequestError("mock stream wrapper requires streaming options", "MOCK_STREAM_CONFIG_INVALID");
@@ -5045,6 +5252,7 @@ async function sleep(ms) {
 *
 * 这不是通用“假模型”，而是测试工具调用编排与错误路径的测试夹具。
 */
+/** 用于测试和本地场景的确定性模拟适配器。 */
 var MockAdapter = class extends AdapterBase {
 	kind = "mock";
 	isSyntheticStream = true;
@@ -5226,6 +5434,7 @@ function cloneItem(item) {
 /**
 * Mock 请求期望校验
 */
+/** 按 MockRequestExpectation 校验规范化请求；失败时抛出断言错误。 */
 function assertMockRequest(request, expectation, context) {
 	const prefix = `MockAdapter turn ${context.turnIndex + 1} expectation failed`;
 	if (expectation.minItems !== void 0 && request.input.length < expectation.minItems) throw new AIRequestError(`${prefix}: expected at least ${expectation.minItems} input item(s)`, "MOCK_EXPECTATION_FAILED");
@@ -5244,6 +5453,7 @@ function assertMockRequest(request, expectation, context) {
 	if (expectation.items && expectation.items.length > 0) if (expectation.ordered) assertOrderedItems(request.input, expectation.items, prefix);
 	else assertUnorderedItems(request.input, expectation.items, prefix);
 }
+/** 断言上一轮 replay 按顺序包含在当前输入中。 */
 function assertReplayIncluded(input, replay, prefix) {
 	const fingerprints = input.map(fingerprintItem);
 	let cursor = 0;
@@ -5254,6 +5464,7 @@ function assertReplayIncluded(input, replay, prefix) {
 		cursor = foundIndex + 1;
 	}
 }
+/** 按顺序匹配输入 item。 */
 function assertOrderedItems(input, expectations, prefix) {
 	let cursor = 0;
 	for (const expected of expectations) {
@@ -5270,9 +5481,11 @@ function assertOrderedItems(input, expectations, prefix) {
 		if (!matched) throw new AIRequestError(`${prefix}: missing ordered input item ${describeExpectation(expected)}`, "MOCK_EXPECTATION_FAILED");
 	}
 }
+/** 无序匹配输入 item。 */
 function assertUnorderedItems(input, expectations, prefix) {
 	for (const expected of expectations) if (!input.some((item) => matchesItemExpectation(item, expected))) throw new AIRequestError(`${prefix}: missing input item ${describeExpectation(expected)}`, "MOCK_EXPECTATION_FAILED");
 }
+/** 判断输入 item 是否满足指定条件。 */
 function matchesItemExpectation(item, expected) {
 	if (item.type !== expected.type) return false;
 	if (expected.id !== void 0 && "id" in item && item.id !== expected.id) return false;
@@ -5287,6 +5500,7 @@ function matchesItemExpectation(item, expected) {
 		case "opaque": return (expected.source === void 0 || item.source === expected.source) && (expected.purpose === void 0 || item.purpose === expected.purpose);
 	}
 }
+/** 判断内容块文本是否包含指定片段。 */
 function matchesText(blocks, textIncludes) {
 	if (textIncludes === void 0) return true;
 	return blocks.some((block) => {
@@ -5295,9 +5509,11 @@ function matchesText(blocks, textIncludes) {
 		return false;
 	});
 }
+/** 为 item 生成稳定的 JSON 指纹。 */
 function fingerprintItem(item) {
 	return JSON.stringify(item);
 }
+/** 将 Mock 断言条件格式化为可读文本。 */
 function describeExpectation(expectation) {
 	const parts = [`type=${expectation.type}`];
 	if (expectation.role) parts.push(`role=${expectation.role}`);
@@ -5308,6 +5524,6 @@ function describeExpectation(expectation) {
 	return `{ ${parts.join(", ")} }`;
 }
 //#endregion
-export { AIError, AIMappingError, AIProviderError, AIRecoverableError, AIRequestError, AIStreamError, ChatCompletionsAdapter, GeminiAdapter, KNOWN_ADAPTER_KINDS, MessagesAdapter, MockAdapter, OllamaAdapter, REASONING_LEVELS, REASONING_LEVEL_SET, ResponsesAdapter, WarningCode, assertMockRequest, blockToText, coalesceContentBlocks, collectStream, contentBlocksToText, createAIClient, extractText, imageBlock, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, opaqueBlock, opaqueItem, reasoningItem, replayFromOutput, serverToolCallItem, serverToolDiscoveryItem, serverToolResultItem, streamWarningKey, supportsContextCompress, textBlock, toolCallItem, toolResultItem, withMockStreaming };
+export { AIError, AIMappingError, AIProviderError, AIRecoverableError, AIRequestError, AIStreamError, ChatCompletionsAdapter, DeltaCompletionsAdapter, GeminiAdapter, KNOWN_ADAPTER_KINDS, MessagesAdapter, MockAdapter, OllamaAdapter, REASONING_LEVELS, REASONING_LEVEL_SET, ResponsesAdapter, WarningCode, assertMockRequest, blockToText, coalesceContentBlocks, collectStream, contentBlocksToText, createAIClient, extractText, imageBlock, jsonBlock, mapReasoningVisibility, mapStopReason, messageItem, opaqueBlock, opaqueItem, reasoningItem, replayFromOutput, serverToolCallItem, serverToolDiscoveryItem, serverToolResultItem, streamWarningKey, supportsContextCompress, textBlock, toolCallItem, toolResultItem, withMockStreaming };
 
 //# sourceMappingURL=index.mjs.map