@gajae-code/ai 0.1.1

package/src/utils/sse-debug.ts

@@ -0,0 +1,289 @@
+import type { ServerSentEvent } from "@gajae-code/utils";
+import type { RawSseEvent } from "../types";
+
+type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type FetchWithPreconnect = FetchFunction & { preconnect?: typeof fetch.preconnect };
+
+type RawSseObserver = (event: RawSseEvent) => void;
+
+export function notifyRawSseEvent(observer: RawSseObserver | undefined, event: ServerSentEvent | RawSseEvent): void {
+	if (!observer) return;
+	try {
+		// Pass the event through without cloning `raw`. The only wired observer
+		// (`RawSseDebugBuffer.recordEvent`) treats `raw` as owned and never
+		// mutates it; new observers must adhere to the same contract.
+		// `ServerSentEvent` and `RawSseEvent` are structurally identical
+		// (`event: string | null`, `data: string`, `raw: string[]`).
+		observer(event as RawSseEvent);
+	} catch {
+		// Raw stream observers are diagnostic only and must not affect generation.
+	}
+}
+
+function isSseResponse(response: Response): boolean {
+	// `response.body` is non-null for any fetch Response with a body, but we
+	// still guard because user-supplied `fetch` mocks may return `{ body: null }`
+	// for empty responses and we don't want to wrap those.
+	if (!response.ok || !response.body) return false;
+	const contentType = response.headers.get("content-type");
+	// All providers in this repo emit lowercase `text/event-stream` (verified
+	// against anthropic, openai-completions, openai-responses, azure-openai-responses,
+	// google-shared, google-gemini-cli, OpenAI code provider-responses, pi-native-client,
+	// and the auth-gateway server). A canonical `includes` check is sufficient;
+	// if a future provider sends mixed case it will fall back to the unwrapped
+	// fetch — observably safe, just no debug tee for that response.
+	return contentType?.includes("text/event-stream") ?? false;
+}
+
+// Reused for every UTF-8 line decode. Safe because lines are split on LF
+// (0x0a), which is single-byte ASCII and never appears inside a UTF-8
+// multi-byte sequence — each line is a complete UTF-8 run, so the decoder
+// carries no state across calls.
+const SSE_LINE_DECODER = new TextDecoder("utf-8");
+
+// Decode bytes [start, end) of an SSE line.
+//
+// A previous revision added an ASCII fast-path using `String.fromCharCode.apply`
+// over chunked subarrays, on the theory that skipping `TextDecoder` would save
+// the ~9.7% `decode` self-time the profile reported. In practice the swap
+// *regressed* total wall time: `fromCharCode` became a new 7.8% hotspot,
+// `Uint8Array` allocations grew 5.3%, and `subarray` rose from 11.5% to 18.3%
+// — net loss of ~10pp. Bun's `TextDecoder.decode` has a fast C++ ASCII path
+// that beats chunked `fromCharCode.apply` for the typical sub-1KB SSE line,
+// so we keep the decoder. The line is bounded by LF (0x0a, single-byte
+// ASCII), so each [start, end) slice is a complete UTF-8 run and the shared
+// stateless decoder is safe to reuse.
+function decodeSseLine(buf: Uint8Array, start: number, end: number): string {
+	if (start === 0 && end === buf.length) return SSE_LINE_DECODER.decode(buf);
+	return SSE_LINE_DECODER.decode(buf.subarray(start, end));
+}
+
+/**
+ * Inline SSE event splitter. Walks the byte stream as it flows through a
+ * `TransformStream`, dispatching parsed events to the debug observer while
+ * the bytes are forwarded unchanged to the response consumer. Replaces the
+ * previous `body.tee()` + `readSseEvents` re-parse pipeline so the byte
+ * stream is parsed exactly once when a debug observer is attached.
+ *
+ * Field parsing intentionally mirrors `readSseEvents` in `@gajae-code/utils`
+ * (only `event` and `data` are observed; `id`/`retry` ignored; CR stripped
+ * before LF dispatch; leading space after `:` trimmed; `data:` lines join
+ * with `\n`). Reusing `readSseEvents` directly would require a second stream
+ * pipeline, which is exactly what this class avoids.
+ */
+class SseTeeParser {
+	#observer: RawSseObserver;
+	// Trailing bytes from the previous chunk that did not end with LF.
+	#partial: Uint8Array | null = null;
+	#event: string | null = null;
+	#data: string | null = null;
+	#raw: string[] = [];
+
+	constructor(observer: RawSseObserver) {
+		this.#observer = observer;
+	}
+
+	push(chunk: Uint8Array): void {
+		// Carry-forward path: concat the partial line with the new chunk so the
+		// LF scan walks a single contiguous buffer. The common case (partial is
+		// null) skips the allocation entirely.
+		let buf: Uint8Array;
+		if (this.#partial) {
+			buf = new Uint8Array(this.#partial.length + chunk.length);
+			buf.set(this.#partial, 0);
+			buf.set(chunk, this.#partial.length);
+			this.#partial = null;
+		} else {
+			buf = chunk;
+		}
+
+		const len = buf.length;
+		let i = 0;
+		while (i < len) {
+			const lf = buf.indexOf(0x0a, i);
+			if (lf === -1) {
+				// Retain the tail as a partial line for the next chunk. Copy
+				// because the source `chunk` buffer may be reused upstream.
+				this.#partial = buf.subarray(i).slice();
+				return;
+			}
+			let end = lf;
+			if (end > i && buf[end - 1] === 0x0d) end--;
+			this.#consumeLine(buf, i, end);
+			i = lf + 1;
+		}
+	}
+
+	flush(): void {
+		// Treat any trailing partial line (no terminating LF) as a complete line.
+		if (this.#partial) {
+			const tail = this.#partial;
+			this.#partial = null;
+			let end = tail.length;
+			if (end > 0 && tail[end - 1] === 0x0d) end--;
+			if (end > 0) this.#consumeLine(tail, 0, end);
+		}
+		// Real services don't always close on a blank line — flush any pending event.
+		this.#dispatch();
+	}
+
+	#consumeLine(buf: Uint8Array, start: number, end: number): void {
+		if (end === start) {
+			this.#dispatch();
+			return;
+		}
+		// Comment line: keep verbatim in `raw` for diagnostic context, skip parsing.
+		// SSE spec § 9.2.6: lines beginning with ':' are heartbeats/comments and
+		// MUST NOT contribute to the event dispatch state. Heartbeats are the
+		// single most common line type on long-poll provider streams, so the
+		// early-return here directly avoids ~half the field-parse work.
+		if (buf[start] === 0x3a /* ':' */) {
+			this.#raw.push(decodeSseLine(buf, start, end));
+			return;
+		}
+		// Byte-level field parse. We avoid `text.indexOf(':')` + two `String.slice`
+		// calls (~6% of CPU pre-optimization) by scanning bytes for the field
+		// delimiter and matching the field name byte-for-byte. Field-name bytes
+		// are ASCII per SSE spec, so byte offsets equal char offsets in the
+		// decoded string and we can `slice` the value directly off `text` without
+		// re-decoding.
+		//
+		// ASCII signatures (verified against SSE spec):
+		//   "event" = 0x65 0x76 0x65 0x6e 0x74  (5 bytes)
+		//   "data"  = 0x64 0x61 0x74 0x61       (4 bytes)
+		let colon = -1;
+		for (let k = start; k < end; k++) {
+			if (buf[k] === 0x3a) {
+				colon = k;
+				break;
+			}
+		}
+		const fieldEnd = colon === -1 ? end : colon;
+		let valueStart = colon === -1 ? end : colon + 1;
+		// Per SSE spec, a single leading SP after the colon is stripped.
+		if (valueStart < end && buf[valueStart] === 0x20 /* ' ' */) valueStart++;
+		const fieldLen = fieldEnd - start;
+		const isEvent =
+			fieldLen === 5 &&
+			buf[start] === 0x65 &&
+			buf[start + 1] === 0x76 &&
+			buf[start + 2] === 0x65 &&
+			buf[start + 3] === 0x6e &&
+			buf[start + 4] === 0x74;
+		const isData =
+			!isEvent &&
+			fieldLen === 4 &&
+			buf[start] === 0x64 &&
+			buf[start + 1] === 0x61 &&
+			buf[start + 2] === 0x74 &&
+			buf[start + 3] === 0x61;
+		// Decode the line exactly once. Raw observers (debug buffer) want it
+		// regardless of field kind; `id`/`retry`/unknown lines pay only the
+		// decode cost, not any extra slicing.
+		const text = decodeSseLine(buf, start, end);
+		this.#raw.push(text);
+		if (isEvent) {
+			// `valueStart - start` is a byte offset into the line; since the
+			// "event:" prefix (and the optional SP) are pure ASCII, that byte
+			// offset equals the char offset in the decoded `text`.
+			this.#event = valueStart === end ? "" : text.slice(valueStart - start);
+		} else if (isData) {
+			const value = valueStart === end ? "" : text.slice(valueStart - start);
+			if (this.#data === null) this.#data = value;
+			else this.#data = `${this.#data}\n${value}`;
+		}
+		// `id` and `retry` are intentionally ignored — providers don't use them
+		// and reconnects are handled by the underlying transport.
+	}
+
+	// Hands ownership of the accumulated `raw` array to the observer. The
+	// observer (currently only `RawSseDebugBuffer.recordEvent`) MAY retain the
+	// array; we install a fresh `#raw = []` for the next event before invoking
+	// the observer so there is no aliasing across dispatches. This contract is
+	// mirrored in `notifyRawSseEvent` (no defensive clone) — see its comment.
+	//
+	// TODO(BufferOpt): once the buffer-side audit confirms it never mutates
+	// `event.raw`, the defensive `[...event.raw]` clone in older call paths
+	// (search for `notifyRawSseEvent`) can be dropped repository-wide.
+	#dispatch(): void {
+		if (this.#event === null && this.#data === null) return;
+		const event: RawSseEvent = {
+			event: this.#event,
+			data: this.#data ?? "",
+			raw: this.#raw,
+		};
+		this.#event = null;
+		this.#data = null;
+		this.#raw = [];
+		try {
+			this.#observer(event);
+		} catch {
+			// Raw stream observers are diagnostic only and must not affect generation.
+		}
+	}
+}
+
+export function wrapFetchForSseDebug(
+	fetchImpl: FetchWithPreconnect,
+	observer: RawSseObserver | undefined,
+): FetchWithPreconnect {
+	if (!observer) return fetchImpl;
+
+	const wrapped = Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			const response = await fetchImpl(input, init);
+			if (!isSseResponse(response)) {
+				return response;
+			}
+
+			const body = response.body;
+			if (!body) return response;
+
+			// Single-pass interception. Previously implemented as
+			// `body.pipeThrough(new TransformStream({...}))`, but the WHATWG
+			// TransformStream machinery imposes a per-chunk Promise boundary
+			// (`#handleNumberResult` showed at 8.8% self-time in CPU profile).
+			// A manual ReadableStream pulling directly from `body.getReader()`
+			// skips that hop: every `read()` immediately feeds both the parser
+			// and the controller in the same microtask.
+			const parser = new SseTeeParser(observer);
+			const reader = body.getReader();
+			const teed = new ReadableStream<Uint8Array>({
+				async pull(controller) {
+					try {
+						const { done, value } = await reader.read();
+						if (done) {
+							parser.flush();
+							controller.close();
+							return;
+						}
+						// Enqueue first so the consumer sees bytes ASAP; parser
+						// dispatch is best-effort diagnostic and runs after.
+						controller.enqueue(value);
+						parser.push(value);
+					} catch (err) {
+						// Mirror TransformStream semantics: surface upstream
+						// errors to the consumer; do not flush a partial event.
+						controller.error(err);
+					}
+				},
+				cancel(reason) {
+					// Propagate downstream cancellation to the source body so the
+					// underlying connection is released. Matches `pipeThrough`'s
+					// cancel-propagation behavior; `flush()` is intentionally NOT
+					// called (TransformStream skips `flush` on abort too).
+					return reader.cancel(reason);
+				},
+			});
+
+			return new Response(teed, {
+				status: response.status,
+				statusText: response.statusText,
+				headers: response.headers,
+			});
+		},
+		fetchImpl.preconnect ? { preconnect: fetchImpl.preconnect } : {},
+	);
+
+	return wrapped;
+}

package/src/utils/tool-call-healing.ts

@@ -0,0 +1,271 @@
+/**
+ * Streaming-safe filter for the Kimi K2 chat-template "tool-call section"
+ * grammar.
+ *
+ * Some providers hosting Kimi K2 (the native `kimi-code` API, OpenRouter,
+ * Fireworks, and others) leak the raw chat-template special tokens into
+ * `delta.content` instead of emitting structured `tool_calls`. Visually
+ * that looks like:
+ *
+ *     <|tool_calls_section_begin|>
+ *       <|tool_call_begin|>functions.read:0<|tool_call_argument_begin|>{"path":"foo"}<|tool_call_end|>
+ *     <|tool_calls_section_end|>
+ *
+ * Without healing, the user sees the raw markers and the agent loop never
+ * sees a tool call. This module reconstructs the embedded calls and strips
+ * the markers from visible text. It is stream-aware: any partial token at
+ * the end of a chunk is held back until the next chunk arrives.
+ */
+
+import { parseJsonWithRepair } from "./json-parse";
+
+const TOK_SECTION_BEGIN = "<|tool_calls_section_begin|>";
+const TOK_SECTION_END = "<|tool_calls_section_end|>";
+const TOK_CALL_BEGIN = "<|tool_call_begin|>";
+const TOK_CALL_END = "<|tool_call_end|>";
+const TOK_ARG_BEGIN = "<|tool_call_argument_begin|>";
+
+const TOKENS = [TOK_SECTION_BEGIN, TOK_SECTION_END, TOK_CALL_BEGIN, TOK_CALL_END, TOK_ARG_BEGIN] as const;
+
+/** Maximum buffered partial-token length before we give up holding back. */
+const MAX_PARTIAL_HOLD = 64;
+
+export interface HealedToolCall {
+	readonly id: string;
+	readonly name: string;
+	readonly arguments: string;
+}
+
+/**
+ * State machine that consumes streamed text, emits visible text with all
+ * Kimi tool-call markers stripped, and accumulates the embedded tool calls
+ * for the caller to drain after each `feed()`.
+ *
+ * One instance per stream. Feed only the channel that may carry leaked
+ * markers (typically `delta.content`); mixing reasoning + content into the
+ * same accumulator corrupts the holdback buffer if both channels race in
+ * the same chunk.
+ */
+export class ToolCallHealer {
+	#buffer = "";
+	#offset = 0;
+	#inSection = false;
+	#inCall = false;
+	#inArgs = false;
+	#pendingId = "";
+	#pendingArgs = "";
+	#sectionTerminated = false;
+	readonly #completed: HealedToolCall[] = [];
+
+	/**
+	 * Feed a chunk of streamed text. Returns the portion safe to emit
+	 * downstream (with all tokens stripped). Any partial token suffix is
+	 * held back until the next chunk arrives or {@link flushPending} is
+	 * called.
+	 */
+	feed(text: string): string {
+		if (text.length === 0) return "";
+		this.#compact();
+		this.#buffer += text;
+		return this.#consume();
+	}
+
+	/**
+	 * Like {@link feed}, but discards any tool calls that the chunk completes.
+	 * Used when the upstream provider also emits structured `delta.tool_calls`
+	 * for the same chunk: the healer still strips leaked marker text from the
+	 * visible output, but the structured payload remains the single source of
+	 * truth for the call list.
+	 */
+	consumeWithoutCalls(text: string): string {
+		const clean = this.feed(text);
+		if (this.#completed.length > 0) this.#completed.length = 0;
+		return clean;
+	}
+
+	/**
+	 * Drain accumulated tool calls. The internal list is cleared so a
+	 * subsequent section in the same stream (rare) yields fresh calls.
+	 */
+	drainCompleted(): HealedToolCall[] {
+		if (this.#completed.length === 0) return [];
+		return this.#completed.splice(0, this.#completed.length);
+	}
+
+	/**
+	 * Flush any held-back fragment when the stream ends. If we were mid-call
+	 * the partial is dropped (emitting raw token bytes would surface markers
+	 * to the user); otherwise the fragment is returned verbatim so a literal
+	 * `<|` in prose is not silently lost.
+	 */
+	flushPending(): string {
+		const tail = this.#remaining();
+		this.#buffer = "";
+		this.#offset = 0;
+		if (this.#inCall || this.#inSection) return "";
+		return tail;
+	}
+
+	/** True once any tool-call section in this stream has fully closed. */
+	get sectionClosed(): boolean {
+		return this.#sectionTerminated;
+	}
+
+	#remaining(): string {
+		return this.#offset === 0 ? this.#buffer : this.#buffer.slice(this.#offset);
+	}
+
+	#compact(): void {
+		if (this.#offset === 0) return;
+		this.#buffer = this.#buffer.slice(this.#offset);
+		this.#offset = 0;
+	}
+
+	#consume(): string {
+		let clean = "";
+
+		while (this.#offset < this.#buffer.length) {
+			if (this.#startsWithPartialToken()) break;
+
+			if (this.#matches(TOK_SECTION_BEGIN)) {
+				this.#inSection = true;
+				this.#offset += TOK_SECTION_BEGIN.length;
+				continue;
+			}
+			if (this.#matches(TOK_SECTION_END)) {
+				this.#inSection = false;
+				this.#sectionTerminated = true;
+				this.#offset += TOK_SECTION_END.length;
+				continue;
+			}
+			if (this.#matches(TOK_CALL_BEGIN)) {
+				if (!this.#inSection) {
+					// Literal mention outside a section — pass through as text so
+					// docs/examples explaining tool tokens are not silently eaten.
+					clean += TOK_CALL_BEGIN;
+					this.#offset += TOK_CALL_BEGIN.length;
+					continue;
+				}
+				this.#inCall = true;
+				this.#inArgs = false;
+				this.#pendingId = "";
+				this.#pendingArgs = "";
+				this.#offset += TOK_CALL_BEGIN.length;
+				continue;
+			}
+			if (this.#matches(TOK_ARG_BEGIN)) {
+				if (!this.#inSection) {
+					clean += TOK_ARG_BEGIN;
+					this.#offset += TOK_ARG_BEGIN.length;
+					continue;
+				}
+				this.#inArgs = true;
+				this.#offset += TOK_ARG_BEGIN.length;
+				continue;
+			}
+			if (this.#matches(TOK_CALL_END)) {
+				if (!this.#inSection || !this.#inCall) {
+					// Token appeared outside an active call (e.g. an assistant
+					// turn explaining the Kimi format). Emit it verbatim instead
+					// of synthesizing a bogus empty tool call.
+					clean += TOK_CALL_END;
+					this.#offset += TOK_CALL_END.length;
+					continue;
+				}
+				this.#finalizeCall();
+				this.#offset += TOK_CALL_END.length;
+				continue;
+			}
+
+			const ch = this.#buffer[this.#offset]!;
+			this.#offset += 1;
+
+			if (this.#inCall) {
+				if (this.#inArgs) {
+					this.#pendingArgs += ch;
+				} else {
+					this.#pendingId += ch;
+				}
+				continue;
+			}
+
+			// Inside the section but outside an individual call: swallow
+			// inter-call whitespace/newlines. Outside the section: pass through.
+			if (!this.#inSection) clean += ch;
+		}
+
+		return clean;
+	}
+
+	#matches(token: string): boolean {
+		return this.#buffer.startsWith(token, this.#offset);
+	}
+
+	/**
+	 * True if the remaining buffer is a strict prefix of any known token —
+	 * we need more bytes before deciding whether it's a token or prose.
+	 * Capped so a stray `<|` in normal text can't grow the holdback
+	 * unboundedly.
+	 */
+	#startsWithPartialToken(): boolean {
+		const remainingLength = this.#buffer.length - this.#offset;
+		if (remainingLength === 0 || remainingLength > MAX_PARTIAL_HOLD) return false;
+		for (const token of TOKENS) {
+			if (token.length <= remainingLength) continue;
+			if (this.#bufferIsPrefixOf(token, remainingLength)) return true;
+		}
+		return false;
+	}
+
+	#bufferIsPrefixOf(token: string, remainingLength: number): boolean {
+		for (let i = 0; i < remainingLength; i++) {
+			if (this.#buffer[this.#offset + i] !== token[i]) return false;
+		}
+		return true;
+	}
+
+	#finalizeCall(): void {
+		const rawId = this.#pendingId.trim();
+		const rawArgs = this.#pendingArgs.trim();
+		const name = normalizeFunctionName(rawId);
+		const id = generateHealedToolCallId();
+
+		let argsJson = rawArgs;
+		if (rawArgs.length > 0) {
+			try {
+				// Round-trip to normalize whitespace and repair near-valid JSON.
+				argsJson = JSON.stringify(parseJsonWithRepair<unknown>(rawArgs));
+			} catch {
+				// Leave raw; downstream parseStreamingJson absorbs the failure.
+			}
+		} else {
+			argsJson = "{}";
+		}
+
+		this.#completed.push({ id, name, arguments: argsJson });
+		this.#inCall = false;
+		this.#inArgs = false;
+		this.#pendingId = "";
+		this.#pendingArgs = "";
+	}
+}
+
+/**
+ * Cheap test for whether a given model is known to leak Kimi-K2 chat-template
+ * tool-call tokens into visible text. Used to gate the per-stream healer so
+ * non-Kimi providers do not pay for the scan.
+ */
+export function modelMayLeakKimiToolCalls(provider: string, modelId: string): boolean {
+	if (provider === "kimi-code" || provider === "moonshot") return true;
+	return /kimi[-/_.]?k2/i.test(modelId);
+}
+
+function normalizeFunctionName(rawId: string): string {
+	const stripped = rawId.startsWith("functions.") ? rawId.slice("functions.".length) : rawId;
+	const colon = stripped.indexOf(":");
+	return colon >= 0 ? stripped.slice(0, colon) : stripped;
+}
+
+function generateHealedToolCallId(): string {
+	return `call_${crypto.randomUUID().replace(/-/g, "").slice(0, 24)}`;
+}

package/src/utils/tool-choice.ts

@@ -0,0 +1,99 @@
+/**
+ * Utility functions for mapping unified ToolChoice to provider-specific formats.
+ */
+import type { ToolChoice } from "../types";
+
+/** OpenAI Completions API tool choice format */
+export type OpenAICompletionsToolChoice =
+	| "auto"
+	| "none"
+	| "required"
+	| { type: "function"; function: { name: string } }
+	| undefined;
+
+/** OpenAI Responses API tool choice format (flat structure) */
+export type OpenAIResponsesToolChoice =
+	| "auto"
+	| "none"
+	| "required"
+	| { type: "function"; name: string }
+	| { type: "custom"; name: string }
+	| undefined;
+
+/** Anthropic-compatible tool choice format */
+export type AnthropicToolChoice = "auto" | "none" | "any" | { type: "tool"; name: string } | undefined;
+
+/**
+ * Extract function name from unified ToolChoice.
+ */
+function extractFunctionName(choice: ToolChoice): string | undefined {
+	if (typeof choice === "string") return undefined;
+	if (choice.type === "tool" && "name" in choice) return choice.name;
+	if (choice.type === "function") {
+		if ("function" in choice && choice.function && typeof choice.function === "object") {
+			return (choice.function as { name?: string }).name;
+		}
+		if ("name" in choice) return choice.name;
+	}
+	return undefined;
+}
+
+/**
+ * Map unified ToolChoice to OpenAI Completions API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", function: { name } }
+ */
+export function mapToOpenAICompletionsToolChoice(choice?: ToolChoice): OpenAICompletionsToolChoice {
+	if (!choice) return undefined;
+	if (typeof choice === "string") {
+		if (choice === "any") return "required";
+		if (choice === "auto" || choice === "none" || choice === "required") return choice;
+		return undefined;
+	}
+	const name = extractFunctionName(choice);
+	return name ? { type: "function", function: { name } } : undefined;
+}
+
+/**
+ * Returns true when an OpenAI-completions `tool_choice` value forces a tool
+ * call (`"required"` or a function-name pin), as opposed to leaving it open
+ * (`"auto"`, `"none"`, or unset). Accepts `unknown` because the param shape
+ * pulled from the OpenAI SDK (`ChatCompletionToolChoiceOption`) widens with
+ * each release; this check only needs the open/forced bit.
+ */
+export function isForcedToolChoice(choice: unknown): boolean {
+	if (choice === undefined || choice === "auto" || choice === "none") return false;
+	return true;
+}
+
+/**
+ * Map unified ToolChoice to OpenAI Responses API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", name } (flat structure)
+ */
+export function mapToOpenAIResponsesToolChoice(choice?: ToolChoice): OpenAIResponsesToolChoice {
+	if (!choice) return undefined;
+	if (typeof choice === "string") {
+		if (choice === "any") return "required";
+		if (choice === "auto" || choice === "none" || choice === "required") return choice;
+		return undefined;
+	}
+	const name = extractFunctionName(choice);
+	return name ? { type: "function", name } : undefined;
+}
+
+/**
+ * Map unified ToolChoice to Anthropic-compatible format.
+ * - "required" → "any"
+ * - { type: "function", ... } → { type: "tool", name }
+ */
+export function mapToAnthropicToolChoice(choice?: ToolChoice): AnthropicToolChoice {
+	if (!choice) return undefined;
+	if (typeof choice === "string") {
+		if (choice === "required") return "any";
+		if (choice === "auto" || choice === "none" || choice === "any") return choice;
+		return undefined;
+	}
+	const name = extractFunctionName(choice);
+	return name ? { type: "tool", name } : undefined;
+}