@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/llm/openai_chat_completions/adapter.cjs

@@ -0,0 +1,916 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-KmRHZBOW.js");
+const require_tool_registry = require("../../../tool_registry-Dkfprsck.js");
+const require_thought = require("../../../thought-DuN2PgdO.js");
+require("../../../common-Od8edUXU.js");
+const require_tool_call = require("../../../tool_call-DFgzcVcU.js");
+const require_spooled_artifact = require("../../../spooled_artifact-Cm9Te22K.js");
+require("../../../guards.cjs");
+const require_batteries_llm_openai_chat_completions_exceptions = require("./exceptions.cjs");
+const require_batteries_llm_openai_chat_completions_validation = require("./validation.cjs");
+const require_batteries_storage_in_memory = require("../../storage/in_memory.cjs");
+const require_batteries_llm_openai_chat_completions_helpers = require("./helpers.cjs");
+let uuid = require("uuid");
+let luxon = require("luxon");
+let js_sha256 = require("js-sha256");
+//#region src/batteries/llm/openai_chat_completions/adapter.ts
+/**
+* Cross-environment executor adapter for OpenAI Chat Completions compatible endpoints.
+*
+* @module @nhtio/adk/batteries/llm/openai_chat_completions/adapter
+*
+* @remarks
+* Cross-environment LLM adapter for the OpenAI Chat Completions wire shape. Chat Completions was
+* chosen as the ADK's reference adapter because it is the de-facto interchange format for the
+* majority of OpenAI-compatible gateways (vLLM, Together, Groq, Fireworks, Ollama, Azure OpenAI,
+* OpenRouter, DeepSeek, Mistral La Plateforme, and most self-hosted deployments). Its tool-call
+* synthetic-history shape (`role: 'assistant', tool_calls: [...]` followed by `role: 'tool'` with
+* `tool_call_id`) is the lowest-common-denominator that every conformant gateway accepts.
+*
+* The adapter is built around three pluggable layers:
+*
+* 1. **Translation helpers** — the thirteen swappable functions exported from `./helpers` turn
+*    ADK primitives ({@link @nhtio/adk!Tokenizable}, {@link @nhtio/adk!Memory}, {@link @nhtio/adk!Message}, {@link @nhtio/adk!Thought},
+*    {@link @nhtio/adk!ToolCall}, {@link @nhtio/adk!Tool}, {@link @nhtio/adk!ArtifactTool}, {@link @nhtio/adk!SpooledArtifact}) into Chat
+*    Completions wire shapes. Consumers override individual helpers via `options.helpers.*` to
+*    customise envelope formats, bucket ordering, thought surfacing, or JSON Schema generation
+*    without forking the adapter.
+* 2. **Three-layer options merging** — constructor baseline, per-`executor()` overrides, and
+*    per-iteration `ctx.stash.openaiChatCompletions` overrides combine with key-by-key
+*    precedence for `headers`/`helpers`/`retry` and wholesale replacement for everything else.
+*    The merged shape is re-validated on every iteration so a malformed stash override
+*    fails loud, not silently.
+* 3. **Cross-env transport** — uses `globalThis.fetch`, `TextDecoder`, `AbortController`, and
+*    `AbortSignal.any` only. No Node-specific primitives; works unchanged in browser, edge, and
+*    server runtimes. SSE framing is hand-parsed against `\n\n` separators so the streaming path
+*    has no dependency on a particular SSE library.
+*
+* Per-iteration flow (steps 1–9 of the plan):
+* 1. Merge constructor / executor / stash options and re-validate.
+* 2. Resolve helpers, falling back to bundled `default*` for each unset field.
+* 3. Forge artifact-query tools by walking `ctx.turnToolCalls`, collecting unique
+*    `SpooledArtifact` constructors, calling `<Ctor>.forgeTools(ctx)` on each, and merging the
+*    results with `ctx.tools`.
+* 4. Pre-render every persisted tool-call result into the prompt-ready string the timeline will
+*    use, cached by `tc.id`.
+* 5. When `tokenEncoding !== null`, sum the token weight of every persisted bucket and throw
+*    {@link @nhtio/adk/batteries!E_OPENAI_CHAT_COMPLETIONS_CONTEXT_OVERFLOW} when the total exceeds `contextWindow`.
+* 6. Build the request body via `buildChatCompletionsHistory`; carry vendor-opaque reasoning
+*    blocks through the `_adk_reasoning_payloads` side-channel.
+* 7. POST with a linked `AbortSignal`, retry loop respecting `retry.*`, and a request-timeout
+*    watchdog that arms before fetch and clears once response headers arrive.
+* 8. Streaming path: SSE parse via `response.body.getReader()` + `TextDecoder`; surface deltas
+*    through `helpers.reportMessage` / `reportThought` / `reportToolCall`; assemble tool-call
+*    deltas via the accumulator; persist `Message` / `Thought` / `ToolCall` records on `[DONE]`.
+* 9. Non-streaming path: single `response.json()`; same persistence + tool-execution loop.
+*/
+var ADK_CONTROL_KEYS = new Set([
+	"apiKey",
+	"baseURL",
+	"headers",
+	"fetch",
+	"stream",
+	"bucketOrder",
+	"contextWindow",
+	"selfIdentity",
+	"thoughtSurfacing",
+	"tokenEncoding",
+	"replayCompatibility",
+	"helpers",
+	"streamIdleTimeoutMs",
+	"requestTimeoutMs",
+	"retry",
+	"strictToolChoice",
+	"autoAck",
+	"unsupportedMediaPolicy"
+]);
+var mergeRetry = (layers) => {
+	let merged;
+	for (const layer of layers) {
+		if (!layer) continue;
+		merged = {
+			...merged ?? {},
+			...layer
+		};
+	}
+	return merged;
+};
+var mergeHeaders = (layers) => {
+	let merged;
+	for (const layer of layers) {
+		if (!layer) continue;
+		merged = {
+			...merged ?? {},
+			...layer
+		};
+	}
+	return merged;
+};
+var mergeHelpers = (layers) => {
+	let merged;
+	for (const layer of layers) {
+		if (!layer) continue;
+		merged = {
+			...merged ?? {},
+			...layer
+		};
+	}
+	return merged;
+};
+var mergeOptions = (baseline, exec, stash) => {
+	const layers = [
+		baseline,
+		exec ?? {},
+		stash ?? {}
+	];
+	const out = {};
+	for (const layer of layers) for (const [k, v] of Object.entries(layer)) {
+		if (v === void 0) continue;
+		if (k === "headers" || k === "helpers" || k === "retry") continue;
+		out[k] = v;
+	}
+	const headers = mergeHeaders(layers.map((l) => l.headers));
+	if (headers !== void 0) out.headers = headers;
+	const helpers = mergeHelpers(layers.map((l) => l.helpers));
+	if (helpers !== void 0) out.helpers = helpers;
+	const retry = mergeRetry(layers.map((l) => l.retry));
+	if (retry !== void 0) out.retry = retry;
+	return out;
+};
+var resolveHelpers = (overrides) => {
+	const src = overrides ?? {};
+	return {
+		descriptionToChatCompletionsJsonSchema: src.descriptionToChatCompletionsJsonSchema ?? require_batteries_llm_openai_chat_completions_helpers.defaultDescriptionToChatCompletionsJsonSchema,
+		renderUntrustedContent: src.renderUntrustedContent ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderUntrustedContent,
+		renderTrustedContent: src.renderTrustedContent ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderTrustedContent,
+		renderStandingInstructions: src.renderStandingInstructions ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderStandingInstructions,
+		renderMemories: src.renderMemories ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderMemories,
+		renderRetrievables: src.renderRetrievables ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderRetrievables,
+		renderRetrievableSafetyDirective: src.renderRetrievableSafetyDirective ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderRetrievableSafetyDirective,
+		renderFirstPartyRetrievables: src.renderFirstPartyRetrievables ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderFirstPartyRetrievables,
+		renderThirdPartyPublicRetrievables: src.renderThirdPartyPublicRetrievables ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderThirdPartyPublicRetrievables,
+		renderThirdPartyPrivateRetrievables: src.renderThirdPartyPrivateRetrievables ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderThirdPartyPrivateRetrievables,
+		renderTimelineMessage: src.renderTimelineMessage ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderTimelineMessage,
+		renderThought: src.renderThought ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderThought,
+		filterThoughts: src.filterThoughts ?? require_batteries_llm_openai_chat_completions_helpers.defaultFilterThoughts,
+		toolsToChatCompletionsTools: src.toolsToChatCompletionsTools ?? require_batteries_llm_openai_chat_completions_helpers.defaultToolsToChatCompletionsTools,
+		renderChatCompletionsSystemPrompt: src.renderChatCompletionsSystemPrompt ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderChatCompletionsSystemPrompt,
+		renderChatCompletionsToolCallResult: src.renderChatCompletionsToolCallResult ?? require_batteries_llm_openai_chat_completions_helpers.defaultRenderChatCompletionsToolCallResult,
+		buildChatCompletionsHistory: src.buildChatCompletionsHistory ?? require_batteries_llm_openai_chat_completions_helpers.defaultBuildChatCompletionsHistory,
+		createChatCompletionsToolCallDeltaAccumulator: src.createChatCompletionsToolCallDeltaAccumulator ?? require_batteries_llm_openai_chat_completions_helpers.defaultCreateChatCompletionsToolCallDeltaAccumulator
+	};
+};
+var computeBackoff = (attempt, cfg) => {
+	const base = cfg.baseDelayMs ?? 500;
+	const max = cfg.maxDelayMs ?? 3e4;
+	return Math.min(base * Math.pow(2, attempt - 1), max);
+};
+var sleepWithJitter = (ms, signal) => {
+	const jittered = ms * (.9 + Math.random() * .2);
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve();
+			return;
+		}
+		let onAbort;
+		const timer = setTimeout(() => {
+			if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, jittered);
+		if (signal) {
+			onAbort = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+};
+var parseRetryAfter = (raw) => {
+	const asNum = Number(raw);
+	if (Number.isFinite(asNum)) return asNum * 1e3;
+	const asDate = Date.parse(raw);
+	if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now());
+	return 0;
+};
+var linkAbortSignals = (signals) => {
+	const anyFn = AbortSignal.any;
+	if (typeof anyFn === "function") return {
+		signal: anyFn(signals),
+		dispose: () => {}
+	};
+	const ctrl = new AbortController();
+	const links = [];
+	for (const sig of signals) {
+		if (sig.aborted) {
+			ctrl.abort();
+			break;
+		}
+		const handler = () => ctrl.abort();
+		sig.addEventListener("abort", handler, { once: true });
+		links.push({
+			sig,
+			handler
+		});
+	}
+	return {
+		signal: ctrl.signal,
+		dispose: () => {
+			for (const { sig, handler } of links) sig.removeEventListener("abort", handler);
+			links.length = 0;
+		}
+	};
+};
+var computeChecksum = (tool, args) => (0, js_sha256.sha256)(require_tool_registry.canonicalStringify({
+	tool,
+	args
+}));
+var nowIso = () => luxon.DateTime.now().toISO() ?? (/* @__PURE__ */ new Date()).toISOString();
+var estimateTokensOf = async (value, encoding) => {
+	return Promise.resolve(value.estimateTokens(encoding));
+};
+/**
+* Opinionated cross-environment LLM adapter for the OpenAI Chat Completions wire shape.
+*
+* @remarks
+* Construction validates options eagerly via {@link @nhtio/adk/batteries!validateOptions} and throws
+* {@link @nhtio/adk/batteries!E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS} on failure — config bugs fail loud, not at
+* dispatch time. The returned instance is reusable: call {@link OpenAIChatCompletionsAdapter.executor}
+* once per `DispatchRunner` configuration to obtain an {@link @nhtio/adk!DispatchExecutorFn} bound to the
+* baseline plus optional executor-scope overrides.
+*
+* Per-iteration overrides live on the active {@link @nhtio/adk!DispatchContext}'s
+* `stash.openaiChatCompletions` slot and take highest precedence — they merge into the
+* executor-scope shape on every iteration. `headers`, `helpers`, and `retry` merge key-by-key
+* across all three layers; every other field is replaced wholesale at the highest layer that
+* sets it.
+*/
+var OpenAIChatCompletionsAdapter = class OpenAIChatCompletionsAdapter {
+	/**
+	* Customary key for per-iteration overrides on `ctx.stash`. The adapter reads
+	* `ctx.stash.get(OpenAIChatCompletionsAdapter.STASH_KEY, {})` at the start of every
+	* iteration and merges the value into the resolved options shape.
+	*/
+	static STASH_KEY = "openaiChatCompletions";
+	#baseline;
+	/**
+	* @param options - Constructor-baseline options. Re-validated on every iteration after
+	*   per-dispatch and per-iteration overrides are layered in.
+	* @throws {@link @nhtio/adk/batteries!E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries!openAIChatCompletionsOptionsSchema}.
+	*/
+	constructor(options) {
+		this.#baseline = require_batteries_llm_openai_chat_completions_validation.validateOptions(options);
+	}
+	/**
+	* Returns an {@link @nhtio/adk!DispatchExecutorFn} bound to this adapter's baseline plus optional
+	* executor-scope overrides. The returned function is reusable across iterations — every
+	* iteration re-merges with `ctx.stash[STASH_KEY]` and re-validates the result.
+	*
+	* @param overrides - Optional executor-scope overrides. Higher precedence than the baseline,
+	*   lower precedence than `ctx.stash[STASH_KEY]`.
+	* @returns An {@link @nhtio/adk!DispatchExecutorFn} suitable for `DispatchRunner`.
+	*/
+	executor(overrides) {
+		const baseline = this.#baseline;
+		const adapterClass = OpenAIChatCompletionsAdapter;
+		return async (ctx, helpers) => {
+			const localWarn = (msg) => {
+				helpers.log.warn({
+					kind: "helper-warning",
+					message: msg
+				});
+			};
+			const stashRaw = ctx.stash.get(adapterClass.STASH_KEY, {});
+			const merged = require_batteries_llm_openai_chat_completions_validation.validateOptions(mergeOptions(baseline, overrides, stashRaw && typeof stashRaw === "object" ? stashRaw : {}));
+			if (merged.tokenEncoding !== null && merged.contextWindow === void 0) throw new require_batteries_llm_openai_chat_completions_exceptions.E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS(["tokenEncoding is non-null but contextWindow is undefined"]);
+			const resolvedHelpers = resolveHelpers(merged.helpers);
+			const uniqueCtors = /* @__PURE__ */ new Set();
+			for (const tc of ctx.turnToolCalls) {
+				const ctor = tc.results?.constructor;
+				if (ctor && require_spooled_artifact.SpooledArtifact.isSpooledArtifactConstructor(ctor)) uniqueCtors.add(ctor);
+			}
+			const forgedRegistries = [];
+			for (const ctor of uniqueCtors) {
+				const forgeFn = ctor.forgeTools;
+				if (typeof forgeFn === "function") forgedRegistries.push(forgeFn.call(ctor, ctx));
+			}
+			const mergedRegistry = require_tool_registry.ToolRegistry.merge([ctx.tools, ...forgedRegistries], { onCollision: "replace" });
+			mergedRegistry.bindContext(ctx);
+			const renderedToolCallResults = /* @__PURE__ */ new Map();
+			for (const tc of ctx.turnToolCalls) {
+				const rendered = await resolvedHelpers.renderChatCompletionsToolCallResult({
+					toolCall: tc,
+					results: tc.results,
+					tool: mergedRegistry.get(tc.tool),
+					renderUntrustedContent: resolvedHelpers.renderUntrustedContent,
+					renderTrustedContent: resolvedHelpers.renderTrustedContent,
+					unsupportedMediaPolicy: merged.unsupportedMediaPolicy ?? "throw",
+					warn: localWarn
+				});
+				renderedToolCallResults.set(tc.id, rendered);
+			}
+			if (merged.tokenEncoding !== null && merged.contextWindow !== void 0) {
+				const encoding = merged.tokenEncoding;
+				let spTokens = await estimateTokensOf(ctx.systemPrompt, encoding);
+				let siTokens = 0;
+				for (const si of ctx.standingInstructions) siTokens += await estimateTokensOf(si, encoding);
+				let memTokens = 0;
+				for (const mem of ctx.turnMemories) memTokens += await estimateTokensOf(mem.content, encoding);
+				let retTokens = 0;
+				for (const r of ctx.turnRetrievables) retTokens += await estimateTokensOf(r.content, encoding);
+				let tlTokens = 0;
+				for (const msg of ctx.turnMessages) if (msg.content !== void 0) tlTokens += await estimateTokensOf(msg.content, encoding);
+				for (const th of ctx.turnThoughts) tlTokens += await estimateTokensOf(th.content, encoding);
+				for (const rendered of renderedToolCallResults.values()) {
+					const tk = new require_tool_registry.Tokenizable(typeof rendered === "string" ? rendered : rendered.filter((b) => b.type === "text").map((b) => b.text).join("\n"));
+					tlTokens += await estimateTokensOf(tk, encoding);
+				}
+				const total = spTokens + siTokens + memTokens + retTokens + tlTokens;
+				const perBucketObj = {
+					systemPrompt: spTokens,
+					standingInstructions: siTokens,
+					memories: memTokens,
+					retrievables: retTokens,
+					timeline: tlTokens
+				};
+				helpers.log.debug({
+					kind: "context-window-usage",
+					message: `Context window usage: ${total}/${merged.contextWindow} tokens`,
+					payload: {
+						total,
+						limit: merged.contextWindow,
+						encoding,
+						perBucket: perBucketObj
+					}
+				});
+				if (total > merged.contextWindow) {
+					const perBucket = JSON.stringify(perBucketObj);
+					throw new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_CONTEXT_OVERFLOW([
+						total,
+						merged.contextWindow,
+						encoding,
+						perBucket
+					]);
+				}
+			}
+			const forcedToolNames = [];
+			const toolChoice = merged.tool_choice;
+			let toolChoiceVariant = "function";
+			if (toolChoice && typeof toolChoice === "object") {
+				if ("function" in toolChoice && toolChoice.type === "function") forcedToolNames.push(toolChoice.function.name);
+				else if ("custom" in toolChoice && toolChoice.type === "custom") forcedToolNames.push(toolChoice.custom.name);
+				else if (toolChoice.type === "allowed_tools") {
+					toolChoiceVariant = "allowed_tools";
+					for (const entry of toolChoice.allowed_tools.tools) if ("function" in entry) forcedToolNames.push(entry.function.name);
+					else if ("custom" in entry) forcedToolNames.push(entry.custom.name);
+				}
+			}
+			const forcedForgedHits = [];
+			for (const name of forcedToolNames) if (mergedRegistry.get(name)?.ephemeral === true) forcedForgedHits.push({ toolName: name });
+			if (forcedForgedHits.length > 0) {
+				if (merged.strictToolChoice === true) throw new require_batteries_llm_openai_chat_completions_exceptions.E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS([`tool_choice forces forged ephemeral artifact-query tool(s): ${forcedForgedHits.map((h) => h.toolName).join(", ")} — these may not exist on the next iteration. Remove the override or unset strictToolChoice.`]);
+				helpers.log.warn({
+					kind: "tool-choice-forged-artifact",
+					message: `tool_choice forces ${forcedForgedHits.length} forged ephemeral artifact-query tool(s); this is almost always a misconfiguration`,
+					payload: {
+						toolNames: forcedForgedHits.map((h) => h.toolName),
+						variant: toolChoiceVariant
+					}
+				});
+			}
+			const { messages: wireMessages, reasoningPayloads } = await resolvedHelpers.buildChatCompletionsHistory({
+				systemPrompt: ctx.systemPrompt,
+				standingInstructions: ctx.standingInstructions,
+				memories: ctx.turnMemories,
+				retrievables: ctx.turnRetrievables,
+				messages: ctx.turnMessages,
+				thoughts: ctx.turnThoughts,
+				toolCalls: ctx.turnToolCalls,
+				tools: mergedRegistry,
+				renderedToolCallResults,
+				bucketOrder: merged.bucketOrder ?? [
+					"standingInstructions",
+					"memories",
+					"retrievables",
+					"timeline"
+				],
+				selfIdentity: merged.selfIdentity ?? "assistant",
+				thoughtSurfacing: merged.thoughtSurfacing ?? "all-self",
+				replayCompatibility: merged.replayCompatibility ?? [],
+				renderChatCompletionsToolCallResult: resolvedHelpers.renderChatCompletionsToolCallResult,
+				renderChatCompletionsSystemPrompt: resolvedHelpers.renderChatCompletionsSystemPrompt,
+				renderStandingInstructions: resolvedHelpers.renderStandingInstructions,
+				renderMemories: resolvedHelpers.renderMemories,
+				renderRetrievables: resolvedHelpers.renderRetrievables,
+				renderRetrievableSafetyDirective: resolvedHelpers.renderRetrievableSafetyDirective,
+				renderFirstPartyRetrievables: resolvedHelpers.renderFirstPartyRetrievables,
+				renderThirdPartyPublicRetrievables: resolvedHelpers.renderThirdPartyPublicRetrievables,
+				renderThirdPartyPrivateRetrievables: resolvedHelpers.renderThirdPartyPrivateRetrievables,
+				renderTimelineMessage: resolvedHelpers.renderTimelineMessage,
+				renderThought: resolvedHelpers.renderThought,
+				filterThoughts: resolvedHelpers.filterThoughts,
+				renderUntrustedContent: resolvedHelpers.renderUntrustedContent,
+				renderTrustedContent: resolvedHelpers.renderTrustedContent,
+				unsupportedMediaPolicy: merged.unsupportedMediaPolicy ?? "throw",
+				warn: localWarn
+			});
+			const stream = merged.stream ?? true;
+			const body = {
+				model: merged.model,
+				messages: wireMessages,
+				stream
+			};
+			for (const [k, v] of Object.entries(merged)) {
+				if (ADK_CONTROL_KEYS.has(k)) continue;
+				if (k === "model" || k === "messages" || k === "stream") continue;
+				if (v === void 0) continue;
+				body[k] = v;
+			}
+			const toolsArr = mergedRegistry.all();
+			if (toolsArr.length > 0) body.tools = resolvedHelpers.toolsToChatCompletionsTools(toolsArr, { descriptionToChatCompletionsJsonSchema: resolvedHelpers.descriptionToChatCompletionsJsonSchema });
+			if (reasoningPayloads.length > 0) body._adk_reasoning_payloads = reasoningPayloads;
+			const rawBase = merged.baseURL ?? "https://api.openai.com/v1";
+			const url = `${rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase}/chat/completions`;
+			const headers = { "Content-Type": "application/json" };
+			if (stream) headers["Accept"] = "text/event-stream";
+			if (merged.apiKey) headers["Authorization"] = `Bearer ${merged.apiKey}`;
+			if (merged.headers) Object.assign(headers, merged.headers);
+			const retryCfg = {
+				maxAttempts: merged.retry?.maxAttempts ?? 1,
+				baseDelayMs: merged.retry?.baseDelayMs ?? 500,
+				maxDelayMs: merged.retry?.maxDelayMs ?? 3e4,
+				retriableStatuses: merged.retry?.retriableStatuses ?? [
+					429,
+					502,
+					503,
+					504
+				],
+				honorRetryAfter: merged.retry?.honorRetryAfter ?? true
+			};
+			const fetchFn = merged.fetch ?? globalThis.fetch;
+			const maxAttempts = retryCfg.maxAttempts ?? 1;
+			let response;
+			let attempt = 1;
+			let disposeLink = () => {};
+			while (attempt <= maxAttempts) {
+				if (ctx.abortSignal.aborted) return;
+				const internalController = new AbortController();
+				let timeoutHandle;
+				const requestTimeoutMs = merged.requestTimeoutMs ?? 0;
+				if (requestTimeoutMs > 0) timeoutHandle = setTimeout(() => internalController.abort(), requestTimeoutMs);
+				disposeLink();
+				const { signal: linkedSignal, dispose: disposeCurrentLink } = linkAbortSignals([ctx.abortSignal, internalController.signal]);
+				disposeLink = disposeCurrentLink;
+				try {
+					response = await fetchFn(url, {
+						method: "POST",
+						headers,
+						body: JSON.stringify(body),
+						signal: linkedSignal
+					});
+				} catch (err) {
+					if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+					if (ctx.abortSignal.aborted) return;
+					if (internalController.signal.aborted) {
+						helpers.log.warn({
+							kind: "request-timeout",
+							message: `Request timed out after ${requestTimeoutMs}ms on attempt ${attempt}/${maxAttempts}`,
+							payload: {
+								requestTimeoutMs,
+								attempt,
+								maxAttempts
+							}
+						});
+						if (attempt < maxAttempts) {
+							const delay = computeBackoff(attempt, retryCfg);
+							helpers.log.debug({
+								kind: "retry-attempt",
+								message: `Retrying after request timeout in ~${delay}ms (attempt ${attempt + 1}/${maxAttempts})`,
+								payload: {
+									reason: "request-timeout",
+									delayMs: delay,
+									attempt: attempt + 1,
+									maxAttempts
+								}
+							});
+							await sleepWithJitter(delay, ctx.abortSignal);
+							attempt += 1;
+							continue;
+						}
+						ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_REQUEST_TIMEOUT([requestTimeoutMs]));
+						return;
+					}
+					helpers.log.error({
+						kind: "transport-error",
+						message: `Transport failure on attempt ${attempt}/${maxAttempts}: ${require_tool_registry.isError(err) ? err.message : String(err)}`,
+						payload: {
+							attempt,
+							maxAttempts,
+							detail: require_tool_registry.isError(err) ? err.message : String(err)
+						}
+					});
+					ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_HTTP_ERROR([0, require_tool_registry.isError(err) ? err.message : String(err)]));
+					return;
+				}
+				if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+				if (!response.ok) {
+					const status = response.status;
+					const retriable = (retryCfg.retriableStatuses ?? [
+						429,
+						502,
+						503,
+						504
+					]).includes(status);
+					if (retriable && attempt < maxAttempts) {
+						let delay = computeBackoff(attempt, retryCfg);
+						let retryAfterMs;
+						if (retryCfg.honorRetryAfter !== false) {
+							const ra = response.headers.get("Retry-After");
+							if (ra) {
+								const raMs = parseRetryAfter(ra);
+								if (raMs > 0) {
+									retryAfterMs = raMs;
+									delay = Math.min(Math.max(delay, raMs), retryCfg.maxDelayMs ?? 3e4);
+								}
+							}
+						}
+						helpers.log.warn({
+							kind: "retry-attempt",
+							message: `HTTP ${status} on attempt ${attempt}/${maxAttempts}; retrying in ~${delay}ms`,
+							payload: {
+								reason: "http-status",
+								status,
+								delayMs: delay,
+								...retryAfterMs !== void 0 ? { retryAfterMs } : {},
+								attempt: attempt + 1,
+								maxAttempts
+							}
+						});
+						await sleepWithJitter(delay, ctx.abortSignal);
+						attempt += 1;
+						continue;
+					}
+					const errBody = await response.text().catch(() => "");
+					helpers.log.error({
+						kind: "http-error",
+						message: `HTTP ${status} (terminal): ${errBody.slice(0, 256)}`,
+						payload: {
+							status,
+							body: errBody,
+							attempt,
+							maxAttempts,
+							retriable
+						}
+					});
+					ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_HTTP_ERROR([status, errBody]));
+					return;
+				}
+				break;
+			}
+			if (!response) return;
+			const spoolStore = new require_batteries_storage_in_memory.InMemorySpoolStore();
+			const executeAndPersistToolCall = async (call) => {
+				const tool = mergedRegistry.get(call.name);
+				let args = {};
+				let parseError;
+				if (call.args && call.args.length > 0) try {
+					const parsed = JSON.parse(call.args);
+					if (require_tool_registry.isObject(parsed)) args = parsed;
+					else parseError = new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_INVALID_TOOL_CALL_ARGS([`must be a JSON object; received ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}`, call.args]);
+				} catch {
+					parseError = new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_INVALID_TOOL_CALL_ARGS(["are not valid JSON", call.args]);
+				}
+				const completedAt = nowIso();
+				if (parseError !== void 0) {
+					const results = new require_tool_registry.Tokenizable(parseError.message);
+					helpers.reportToolCall(call.id, {
+						tool: call.name,
+						args
+					});
+					helpers.reportToolCall(call.id, {
+						results,
+						isError: true,
+						isComplete: true
+					});
+					const checksum = computeChecksum(call.name, args);
+					await ctx.storeToolCall(new require_tool_call.ToolCall({
+						id: call.id,
+						tool: call.name,
+						args,
+						checksum,
+						isComplete: true,
+						isError: true,
+						results,
+						createdAt: completedAt,
+						updatedAt: completedAt,
+						completedAt
+					}));
+					return;
+				}
+				if (!tool) {
+					const results = new require_tool_registry.Tokenizable(`Tool not found: ${call.name}`);
+					helpers.reportToolCall(call.id, {
+						tool: call.name,
+						args
+					});
+					helpers.reportToolCall(call.id, {
+						results,
+						isError: true,
+						isComplete: true
+					});
+					const checksum = computeChecksum(call.name, args);
+					await ctx.storeToolCall(new require_tool_call.ToolCall({
+						id: call.id,
+						tool: call.name,
+						args,
+						checksum,
+						isComplete: true,
+						isError: true,
+						results,
+						createdAt: completedAt,
+						updatedAt: completedAt,
+						completedAt
+					}));
+					return;
+				}
+				helpers.reportToolCall(call.id, {
+					tool: tool.name,
+					args
+				});
+				const isArtifactTool = require_spooled_artifact.ArtifactTool.isArtifactTool(tool);
+				let results = new require_tool_registry.Tokenizable("");
+				let toolHadError = false;
+				try {
+					const raw = await tool.executor(ctx)(args);
+					if (isArtifactTool) if (require_tool_registry.Tokenizable.isTokenizable(raw)) results = raw;
+					else if (typeof raw === "string") results = new require_tool_registry.Tokenizable(raw);
+					else throw new Error(`ArtifactTool "${tool.name}" returned a non-string/non-Tokenizable value`);
+					else if (require_tool_call.Media.isMedia(raw)) results = raw;
+					else if (Array.isArray(raw) && raw.length > 0 && raw.every((m) => require_tool_call.Media.isMedia(m))) results = raw;
+					else if (typeof raw === "string" || require_tool_registry.isInstanceOf(raw, "Uint8Array", Uint8Array)) {
+						const reader = spoolStore.write(call.id, raw);
+						results = new ((tool.artifactConstructor?.()) ?? require_spooled_artifact.SpooledArtifact)(reader);
+					} else {
+						const reader = spoolStore.write(call.id, String(raw));
+						results = new ((tool.artifactConstructor?.()) ?? require_spooled_artifact.SpooledArtifact)(reader);
+					}
+				} catch (err) {
+					toolHadError = true;
+					let detailMsg = require_tool_registry.isError(err) ? err.message : String(err);
+					if (require_tool_registry.isError(err) && require_tool_registry.isError(err.cause) && err.cause.message && err.cause.message !== err.message) detailMsg = `${detailMsg} ${err.cause.message}`;
+					results = new require_tool_registry.Tokenizable(detailMsg);
+				}
+				helpers.reportToolCall(call.id, {
+					results,
+					isError: toolHadError,
+					isComplete: true
+				});
+				const checksum = computeChecksum(tool.name, args);
+				const completedAt2 = nowIso();
+				await ctx.storeToolCall(new require_tool_call.ToolCall({
+					id: call.id,
+					tool: tool.name,
+					args,
+					checksum,
+					isComplete: true,
+					isError: toolHadError,
+					results,
+					fromArtifactTool: isArtifactTool,
+					createdAt: completedAt2,
+					updatedAt: completedAt2,
+					completedAt: completedAt2
+				}));
+			};
+			const selfIdentity = merged.selfIdentity ?? "assistant";
+			if (stream) {
+				if (!response.body) {
+					ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_STREAM_ERROR(["response has no body"]));
+					return;
+				}
+				const reader = response.body.getReader();
+				const decoder = new TextDecoder();
+				const accumulator = resolvedHelpers.createChatCompletionsToolCallDeltaAccumulator();
+				const streamId = (0, uuid.v6)();
+				let buffer = "";
+				let idleTimer;
+				let stalled = false;
+				let partialMessageContent = "";
+				let partialThoughtContent = "";
+				let sawMessageDelta = false;
+				let sawThoughtDelta = false;
+				let doneSentinelSeen = false;
+				const idleMs = merged.streamIdleTimeoutMs ?? 0;
+				const armIdleTimer = () => {
+					if (idleMs <= 0) return;
+					if (idleTimer) clearTimeout(idleTimer);
+					idleTimer = setTimeout(() => {
+						stalled = true;
+						helpers.log.warn({
+							kind: "stream-idle-timeout",
+							message: `SSE stream went idle for ${idleMs}ms; cancelling`,
+							payload: { idleMs }
+						});
+						reader.cancel().catch(() => {});
+					}, idleMs);
+				};
+				const clearIdleTimer = () => {
+					if (idleTimer) {
+						clearTimeout(idleTimer);
+						idleTimer = void 0;
+					}
+				};
+				const drainAndPersist = async () => {
+					if (sawMessageDelta) {
+						helpers.reportMessage(streamId, "", { isComplete: true });
+						await ctx.storeMessage(new require_thought.Message({
+							id: streamId,
+							role: "assistant",
+							content: partialMessageContent,
+							identity: selfIdentity,
+							createdAt: nowIso(),
+							updatedAt: nowIso()
+						}));
+					}
+					if (sawThoughtDelta) {
+						helpers.reportThought(streamId, "", { isComplete: true });
+						await ctx.storeThought(new require_thought.Thought({
+							id: streamId,
+							content: partialThoughtContent,
+							identity: selfIdentity,
+							createdAt: nowIso(),
+							updatedAt: nowIso()
+						}));
+					}
+					const calls = accumulator.drain();
+					helpers.log.debug({
+						kind: "accumulator-finalised",
+						message: `Stream finalised: ${calls.length} tool call(s), message=${sawMessageDelta}, thought=${sawThoughtDelta}`,
+						payload: {
+							toolCallCount: calls.length,
+							sawMessageDelta,
+							sawThoughtDelta,
+							doneSentinelSeen
+						}
+					});
+					if (calls.length === 0) {
+						if (merged.autoAck) ctx.ack();
+						return;
+					}
+					for (const call of calls) {
+						if (ctx.abortSignal.aborted) return;
+						await executeAndPersistToolCall(call);
+					}
+				};
+				try {
+					armIdleTimer();
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						armIdleTimer();
+						if (ctx.abortSignal.aborted) {
+							clearIdleTimer();
+							return;
+						}
+						buffer += decoder.decode(value, { stream: true });
+						let sepIdx = buffer.indexOf("\n\n");
+						while (sepIdx !== -1) {
+							const frame = buffer.slice(0, sepIdx);
+							buffer = buffer.slice(sepIdx + 2);
+							for (const line of frame.split("\n")) {
+								if (!line.startsWith("data:")) continue;
+								const data = line.slice(5).trim();
+								if (data.length === 0) continue;
+								if (data === "[DONE]") {
+									doneSentinelSeen = true;
+									clearIdleTimer();
+									await drainAndPersist();
+									return;
+								}
+								let chunk;
+								try {
+									chunk = JSON.parse(data);
+								} catch {
+									helpers.log.trace({
+										kind: "sse-parse-failure",
+										message: "Failed to parse SSE chunk as JSON; skipping",
+										payload: { dataPreview: data.slice(0, 256) }
+									});
+									continue;
+								}
+								const delta = chunk.choices?.[0]?.delta;
+								if (!delta) continue;
+								if (typeof delta.content === "string" && delta.content.length > 0) {
+									sawMessageDelta = true;
+									partialMessageContent += delta.content;
+									helpers.reportMessage(streamId, delta.content);
+								}
+								const reasoning = delta.reasoning_content;
+								if (typeof reasoning === "string" && reasoning.length > 0) {
+									sawThoughtDelta = true;
+									partialThoughtContent += reasoning;
+									helpers.reportThought(streamId, reasoning);
+								}
+								if (Array.isArray(delta.tool_calls)) for (const d of delta.tool_calls) accumulator.feed(d);
+							}
+							sepIdx = buffer.indexOf("\n\n");
+						}
+					}
+					clearIdleTimer();
+					if (stalled) {
+						ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_STREAM_STALLED([idleMs]));
+						return;
+					}
+					if (!doneSentinelSeen) {
+						helpers.log.warn({
+							kind: "sse-eof-without-done",
+							message: "SSE stream ended without [DONE] sentinel; draining accumulated state"
+						});
+						await drainAndPersist();
+					}
+				} catch (err) {
+					clearIdleTimer();
+					if (ctx.abortSignal.aborted) return;
+					if (stalled) {
+						ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_STREAM_STALLED([idleMs]));
+						return;
+					}
+					helpers.log.error({
+						kind: "stream-error",
+						message: `SSE stream failed: ${require_tool_registry.isError(err) ? err.message : String(err)}`,
+						payload: { detail: require_tool_registry.isError(err) ? err.message : String(err) }
+					});
+					ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_STREAM_ERROR([require_tool_registry.isError(err) ? err.message : String(err)]));
+					return;
+				}
+				return;
+			}
+			let parsed;
+			try {
+				parsed = await response.json();
+			} catch (err) {
+				ctx.nack(new require_batteries_llm_openai_chat_completions_exceptions.E_OPENAI_CHAT_COMPLETIONS_STREAM_ERROR([require_tool_registry.isError(err) ? err.message : String(err)]));
+				return;
+			}
+			const choice = parsed.choices?.[0];
+			if (!choice) {
+				if (merged.autoAck) ctx.ack();
+				return;
+			}
+			const msg = choice.message;
+			const responseId = parsed.id ?? (0, uuid.v6)();
+			if (msg && typeof msg.content === "string" && msg.content.length > 0) {
+				const messageId = `${responseId}:message`;
+				helpers.reportMessage(messageId, msg.content, { isComplete: true });
+				await ctx.storeMessage(new require_thought.Message({
+					id: messageId,
+					role: "assistant",
+					content: msg.content,
+					identity: selfIdentity,
+					createdAt: nowIso(),
+					updatedAt: nowIso()
+				}));
+			}
+			const reasoning = msg?.reasoning_content;
+			if (typeof reasoning === "string" && reasoning.length > 0) {
+				const thoughtId = `${responseId}:thought`;
+				helpers.reportThought(thoughtId, reasoning, { isComplete: true });
+				await ctx.storeThought(new require_thought.Thought({
+					id: thoughtId,
+					content: reasoning,
+					identity: selfIdentity,
+					createdAt: nowIso(),
+					updatedAt: nowIso()
+				}));
+			}
+			const rawCalls = msg?.tool_calls ?? [];
+			if (rawCalls.length === 0) {
+				if (merged.autoAck) ctx.ack();
+				return;
+			}
+			const calls = rawCalls.map((tc) => ({
+				id: tc.id,
+				type: tc.type ?? "function",
+				name: tc.function?.name ?? "",
+				args: tc.function?.arguments ?? ""
+			}));
+			for (const call of calls) {
+				if (ctx.abortSignal.aborted) return;
+				await executeAndPersistToolCall(call);
+			}
+		};
+	}
+	/**
+	* Returns `true` when `value` is an {@link OpenAIChatCompletionsAdapter} instance.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is an `OpenAIChatCompletionsAdapter` instance.
+	*/
+	static isOpenAIChatCompletionsAdapter(value) {
+		return require_tool_registry.isInstanceOf(value, "OpenAIChatCompletionsAdapter", OpenAIChatCompletionsAdapter);
+	}
+};
+//#endregion
+exports.OpenAIChatCompletionsAdapter = OpenAIChatCompletionsAdapter;
+
+//# sourceMappingURL=adapter.cjs.map