jeopi-ai 16.2.13

package/src/utils/abort.ts

@@ -0,0 +1,67 @@
+import * as AIError from "../error";
+
+export interface AbortSourceTracker {
+	requestAbortController: AbortController;
+	requestSignal: AbortSignal;
+	abortLocally(reason: Error): Error;
+	getLocalAbortReason(): Error | undefined;
+	wasCallerAbort(): boolean;
+}
+
+/**
+ * Tracks whether a merged request signal was aborted by the caller or by provider-local logic.
+ *
+ * Caller aborts always take priority. When both the caller and a local watchdog fire near
+ * each other, the merged `requestSignal.reason` reflects whichever AbortController called
+ * `.abort()` first — but ordering is racy and not meaningful for upstream consumers. What
+ * matters is intent: if the caller's signal aborted, the request was cancelled by the
+ * caller, and any local watchdog reason is incidental and **MUST NOT** be surfaced as a
+ * retryable transient error (which would cause auto-retry to re-enter streaming and leave
+ * the UI showing a spinner the user already tried to cancel).
+ */
+export function createAbortSourceTracker(callerSignal?: AbortSignal): AbortSourceTracker {
+	const requestAbortController = new AbortController();
+	const requestSignal = callerSignal
+		? AbortSignal.any([callerSignal, requestAbortController.signal])
+		: requestAbortController.signal;
+	let localAbortReason: Error | undefined;
+
+	return {
+		requestAbortController,
+		requestSignal,
+		abortLocally(reason) {
+			localAbortReason = reason;
+			requestAbortController.abort(reason);
+			return reason;
+		},
+		getLocalAbortReason() {
+			// Caller intent dominates. Surface a local reason only when the caller did not
+			// abort, so timeout/idle-watchdog errors don't masquerade as the user's cancel.
+			if (!localAbortReason || callerSignal?.aborted) return undefined;
+			return requestSignal.reason === localAbortReason ? localAbortReason : undefined;
+		},
+		wasCallerAbort() {
+			// If the caller signal aborted, treat it as a caller abort regardless of which
+			// AbortController won the race to set `requestSignal.reason`. The previous
+			// `requestSignal.reason !== localAbortReason` heuristic flipped the result to
+			// `false` when a local watchdog fired microseconds before the user's ESC, which
+			// then routed user-initiated cancels through the auto-retry transient-error
+			// path.
+			return callerSignal?.aborted === true;
+		},
+	};
+}
+
+/**
+ * Race a shared promise against a caller's AbortSignal without coupling the
+ * underlying work to that signal. The shared promise keeps running (and caches
+ * its result) even when an individual caller bails out.
+ */
+export function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(signal.reason ?? new AIError.AbortError());
+	const { promise: aborted, reject } = Promise.withResolvers<never>();
+	const onAbort = () => reject(signal.reason ?? new AIError.AbortError());
+	signal.addEventListener("abort", onAbort, { once: true });
+	return Promise.race([promise, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+}

package/src/utils/anthropic-auth.ts

@@ -0,0 +1,93 @@
+/**
+ * Anthropic Authentication
+ *
+ * Thin helper for turning an already-resolved API key into the request-shaping
+ * config consumed by {@link buildAnthropicSearchHeaders} / {@link buildAnthropicUrl}.
+ *
+ * Credential storage and refresh live in `AuthStorage` — call
+ * `authStorage.getApiKey("anthropic", sessionId)` first, then pass the result
+ * through {@link buildAnthropicAuthConfig} for header/URL shaping.
+ */
+import { $env } from "jeopi-utils";
+import {
+	buildAnthropicHeaders as buildProviderAnthropicHeaders,
+	normalizeAnthropicBaseUrl,
+	resolveAnthropicCustomHeadersForBaseUrl,
+} from "../providers/anthropic";
+import { isFoundryEnabled } from "./foundry";
+
+/** Auth configuration for Anthropic */
+export interface AnthropicAuthConfig {
+	apiKey: string;
+	baseUrl: string;
+	isOAuth: boolean;
+}
+
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+
+function normalizeBaseUrl(baseUrl: string | undefined): string | undefined {
+	const trimmed = baseUrl?.trim();
+	return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
+}
+
+export function resolveAnthropicBaseUrlFromEnv(): string | undefined {
+	if (isFoundryEnabled()) {
+		const foundryBaseUrl = normalizeBaseUrl($env.FOUNDRY_BASE_URL);
+		if (foundryBaseUrl) return foundryBaseUrl;
+	}
+	const anthropicBaseUrl = normalizeBaseUrl($env.ANTHROPIC_BASE_URL);
+	return anthropicBaseUrl || undefined;
+}
+
+/**
+ * Checks if a token is an OAuth token by looking for sk-ant-oat prefix.
+ */
+export function isOAuthToken(apiKey: string): boolean {
+	return apiKey.includes("sk-ant-oat");
+}
+
+/**
+ * Build an {@link AnthropicAuthConfig} from an already-resolved API key.
+ *
+ * `apiKey` is whatever the caller chose for `Authorization`/`x-api-key` —
+ * usually `authStorage.getApiKey("anthropic")`. `baseUrl` overrides the
+ * env-derived base; pass `undefined` to fall back to FOUNDRY/ANTHROPIC env
+ * resolution and finally `DEFAULT_BASE_URL`.
+ *
+ * `isOAuth` is derived from the token prefix so the helper stays pure: callers
+ * never have to thread the OAuth flag through their own resolution logic.
+ */
+export function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig {
+	return {
+		apiKey,
+		baseUrl: normalizeBaseUrl(baseUrl) ?? resolveAnthropicBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
+		isOAuth: isOAuthToken(apiKey),
+	};
+}
+
+/**
+ * Builds HTTP headers for Anthropic API requests (search variant).
+ *
+ * Forwards `ANTHROPIC_CUSTOM_HEADERS` when the resolver deems them applicable
+ * (Foundry mode, or a non-Anthropic base URL — typically an enterprise
+ * gateway), matching the streaming path so web search behaves identically.
+ */
+export function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string> {
+	return buildProviderAnthropicHeaders({
+		apiKey: auth.apiKey,
+		baseUrl: auth.baseUrl,
+		isOAuth: auth.isOAuth,
+		extraBetas: ["web-search-2025-03-05"],
+		stream: false,
+		modelHeaders: resolveAnthropicCustomHeadersForBaseUrl(auth.baseUrl),
+	});
+}
+
+/**
+ * Builds the full API URL for Anthropic messages endpoint.
+ */
+export function buildAnthropicUrl(auth: AnthropicAuthConfig): string {
+	const normalizedBaseUrl = normalizeAnthropicBaseUrl(auth.baseUrl);
+	const base = `${normalizedBaseUrl}/v1/messages`;
+	return `${base}?beta=true`;
+}

package/src/utils/block-symbols.ts

@@ -0,0 +1,32 @@
+/** Stores streamed tool-call argument JSON for live renderers and parser recovery. */
+export const kStreamingPartialJson = Symbol("provider.block.partialJson");
+
+/** Carries streamed tool-call argument JSON without exposing a string-keyed property. */
+export type StreamingPartialJsonCarrier = object & { [kStreamingPartialJson]?: string };
+
+/** Reads streamed tool-call argument JSON from a block or event snapshot. */
+export function getStreamingPartialJson(block: StreamingPartialJsonCarrier | null | undefined): string | undefined {
+	return block?.[kStreamingPartialJson];
+}
+
+/** Writes streamed tool-call argument JSON to a block or clears it with `undefined`. */
+export function setStreamingPartialJson(block: StreamingPartialJsonCarrier, value: string | undefined): void {
+	block[kStreamingPartialJson] = value;
+}
+
+/** Clears streamed tool-call argument JSON without deleting or changing object shape. */
+export function clearStreamingPartialJson(block: StreamingPartialJsonCarrier): void {
+	if (Object.hasOwn(block, kStreamingPartialJson)) block[kStreamingPartialJson] = undefined;
+}
+
+/** Stores a provider-local stream block index without exposing a string-keyed property. */
+export const kStreamingBlockIndex = Symbol("provider.block.index");
+
+/** Stores the last parsed argument prefix length for throttled streaming JSON parsing. */
+export const kStreamingLastParseLen = Symbol("provider.block.lastParseLen");
+
+/** Marks streamed tool-call arguments that already received an authoritative done payload. */
+export const kStreamingArgumentsDone = Symbol("provider.block.argumentsDone");
+
+/** Classifies Cursor's in-flight tool-call kind without leaking provider-private state. */
+export const kStreamingBlockKind = Symbol("provider.block.kind");

package/src/utils/deterministic-id.ts

@@ -0,0 +1,20 @@
+/**
+ * A UUID-shaped string: five hex groups in the canonical 8-4-4-4-12 layout.
+ *
+ * NOT a spec-compliant RFC 4122 UUID — the version/variant nibbles are left as
+ * raw hash output — but the shape passes everywhere a UUID string is expected.
+ */
+export type DeterministicUuid = `${string}-${string}-${string}-${string}-${string}`;
+
+/**
+ * Format the leading 128 bits of `seed`'s SHA-256 digest as a v4-shape UUID
+ * (8-4-4-4-12 hex groups).
+ *
+ * Deterministic: identical seeds always map to the same id, so callers get
+ * stable ids across requests / conversation turns (reusing message-blob ids,
+ * keying prompt caches) without persisting a seed→id mapping.
+ */
+export function deterministicUuid(seed: string): DeterministicUuid {
+	const hex = new Bun.CryptoHasher("sha256").update(seed).digest("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/src/utils/empty-completion-retry.ts

@@ -0,0 +1,159 @@
+/**
+ * Bounded retries for an empty assistant completion.
+ *
+ * Some providers — and especially flaky OpenAI-/Anthropic-compatible gateways —
+ * intermittently return a benign terminal stop carrying no content and no usage
+ * (e.g. a single OpenAI `delta: {}` + `finish_reason: "stop"` chunk). Delivered
+ * as-is the agent loop has nothing to act on and silently halts mid-task, so the
+ * request must be retried instead of surfaced.
+ *
+ * This wraps a single-attempt provider stream and re-invokes it (a fresh request
+ * with its own message state) when an attempt produces no meaningful content.
+ * Only a stream that streamed nothing meaningful is retried: the moment any
+ * text/thinking/tool delta is forwarded the attempt is committed, so live
+ * streaming (including thinking) is never delayed, retried, or duplicated.
+ *
+ * Mirrors the Gemini empty-response policy in `google-shared` (which keeps its
+ * own integrated loop) and is shared by the OpenAI-completions and
+ * Anthropic-messages providers.
+ */
+import { scheduler } from "node:timers/promises";
+import type { AssistantMessage, AssistantMessageEvent, Context } from "../types";
+import { AssistantMessageEventStream } from "./event-stream";
+
+export const MAX_EMPTY_COMPLETION_RETRIES = 2;
+export const EMPTY_COMPLETION_BASE_DELAY_MS = 500;
+
+const NON_WHITESPACE_RE = /\S/;
+
+/**
+ * Whether a completed assistant message carries content worth delivering: a tool
+ * call or any non-whitespace text. An empty/whitespace-only message — or one
+ * that only ever produced thinking — is the "empty response" failure.
+ */
+export function hasVisibleAssistantContent(message: AssistantMessage): boolean {
+	for (const block of message.content) {
+		if (block.type === "toolCall") return true;
+		if (block.type === "text" && NON_WHITESPACE_RE.test(block.text)) return true;
+	}
+	return false;
+}
+
+/** A streamed event that delivers content worth committing the attempt for. */
+function isMeaningfulCompletionEvent(event: AssistantMessageEvent): boolean {
+	switch (event.type) {
+		case "text_delta":
+		case "thinking_delta":
+		case "toolcall_delta":
+			return event.delta.length > 0;
+		case "text_end":
+		case "thinking_end":
+			return event.content.length > 0;
+		case "toolcall_start":
+		case "toolcall_end":
+			return true;
+		default:
+			return false;
+	}
+}
+
+interface EmptyCompletionRetryOptions {
+	signal?: AbortSignal;
+	providerRetryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Wrap a single-attempt provider stream with bounded empty-completion retries.
+ * `attempt` MUST create a fresh request (and its own output message) on each
+ * call so a retry never inherits stale metadata from an empty attempt.
+ */
+export function withEmptyCompletionRetry<M, O extends EmptyCompletionRetryOptions>(
+	model: M,
+	context: Context,
+	options: O | undefined,
+	attempt: (model: M, context: Context, options?: O) => AssistantMessageEventStream,
+): AssistantMessageEventStream {
+	const outer = new AssistantMessageEventStream();
+	const signal = options?.signal;
+	void (async () => {
+		for (let emptyAttempt = 0; ; emptyAttempt++) {
+			const inner = attempt(model, context, options);
+			const buffered: AssistantMessageEvent[] = [];
+			let committed = false;
+			let terminal: AssistantMessageEvent | undefined;
+			const flush = (): void => {
+				for (const event of buffered) outer.push(event);
+				buffered.length = 0;
+			};
+			try {
+				for await (const event of inner) {
+					if (event.type === "done" || event.type === "error") {
+						terminal = event;
+						break;
+					}
+					// Buffer pre-content events (start/*_start) so an empty attempt can
+					// be discarded; commit the moment real content streams.
+					if (!committed && !isMeaningfulCompletionEvent(event)) {
+						buffered.push(event);
+						continue;
+					}
+					committed = true;
+					flush();
+					outer.push(event);
+					if (outer.done) return;
+				}
+			} catch (error) {
+				flush();
+				outer.fail(error);
+				return;
+			}
+
+			// Retry only a genuinely degenerate completion: a normal stop that
+			// produced no visible content AND billed no output tokens (the flaky
+			// gateway signature — charged nothing, returned nothing). A stop that
+			// reports output tokens spent its budget somewhere (e.g. thinking) and
+			// is left alone.
+			const message = terminal?.type === "done" ? terminal.message : undefined;
+			const isRetryableEmpty =
+				!committed &&
+				message !== undefined &&
+				message.stopReason === "stop" &&
+				!message.errorMessage &&
+				(message.usage?.output ?? 0) <= 0 &&
+				!hasVisibleAssistantContent(message);
+
+			if (isRetryableEmpty && emptyAttempt < MAX_EMPTY_COMPLETION_RETRIES && !signal?.aborted) {
+				const delayMs = EMPTY_COMPLETION_BASE_DELAY_MS * 2 ** emptyAttempt;
+				try {
+					if (options?.providerRetryWait) await options.providerRetryWait(delayMs, signal);
+					else await scheduler.wait(delayMs, { signal });
+				} catch (waitError) {
+					// Aborted during backoff: deliver the empty result rather than hang.
+					// Any other wait failure is a real error and must surface.
+					flush();
+					if (signal?.aborted) {
+						if (terminal) outer.push(terminal);
+					} else {
+						outer.fail(waitError);
+					}
+					return;
+				}
+				// Discard the buffered `start` from this empty attempt and retry.
+				continue;
+			}
+
+			flush();
+			if (terminal) {
+				outer.push(terminal);
+			} else if (!outer.done) {
+				try {
+					outer.end(await inner.result());
+				} catch (error) {
+					outer.fail(error);
+				}
+			}
+			return;
+		}
+	})();
+	return outer;
+}

package/src/utils/event-stream.ts

@@ -0,0 +1,171 @@
+import * as AIError from "../error";
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	queue: T[] = [];
+	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	done = false;
+	/** True once finalResultPromise has been resolved or rejected. */
+	resultSettled = false;
+	#failed = false;
+	#error: unknown = undefined;
+	finalResultPromise: Promise<R>;
+	resolveFinalResult!: (result: R) => void;
+	rejectFinalResult!: (err: unknown) => void;
+	isComplete: (event: T) => boolean;
+	extractResult: (event: T) => R;
+
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R) {
+		const { promise, resolve, reject } = Promise.withResolvers<R>();
+		// Prevent an unhandled rejection when fail() is called but nobody awaits result().
+		// Callers who do await result() still receive the rejection normally.
+		promise.catch(() => {});
+		this.finalResultPromise = promise;
+		this.resolveFinalResult = resolve;
+		this.rejectFinalResult = reject;
+		this.isComplete = isComplete;
+		this.extractResult = extractResult;
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resultSettled = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		// Deliver to waiting consumer or queue it
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	deliver(event: T): void {
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	end(result?: R): void {
+		this.done = true;
+		if (result !== undefined) {
+			this.resultSettled = true;
+			this.resolveFinalResult(result);
+		} else if (!this.resultSettled) {
+			// end() without a terminal value must still settle result() —
+			// otherwise complete()/result() awaits hang forever.
+			this.resultSettled = true;
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
+		}
+		// Notify all waiting consumers that we're done
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	endWaiting(): void {
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	fail(err: unknown): void {
+		if (this.done) return;
+		this.done = true;
+		this.#failed = true;
+		this.#error = err;
+		this.resultSettled = true;
+		this.rejectFinalResult(err);
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.reject(err);
+		}
+	}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		while (true) {
+			if (this.queue.length > 0) {
+				yield this.queue.shift()!;
+			} else if (this.#failed) {
+				throw this.#error;
+			} else if (this.done) {
+				return;
+			} else {
+				const result = await new Promise<IteratorResult<T>>((resolve, reject) =>
+					this.waiting.push({ resolve, reject }),
+				);
+				if (result.done) return;
+				yield result.value;
+			}
+		}
+	}
+
+	result(): Promise<R> {
+		return this.finalResultPromise;
+	}
+}
+
+export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+	constructor() {
+		super(
+			event => event.type === "done" || event.type === "error",
+			event => {
+				if (event.type === "done") {
+					return event.message;
+				} else if (event.type === "error") {
+					return event.error;
+				}
+				throw new AIError.ProviderResponseError("Unexpected event type for final result", { kind: "envelope" });
+			},
+		);
+	}
+
+	override push(event: AssistantMessageEvent): void {
+		if (this.done) return;
+
+		if (event.type === "error" && event.error.stopReason === "error") {
+			AIError.classifyMessage(event.error);
+		}
+
+		// Completion resolves the final result and still emits the terminal event.
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resultSettled = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		this.deliver(event);
+	}
+
+	override end(result?: AssistantMessage): void {
+		this.done = true;
+		if (result !== undefined) {
+			if (result.stopReason === "error") {
+				AIError.classifyMessage(result);
+			}
+			this.resultSettled = true;
+			this.resolveFinalResult(result);
+		} else if (!this.resultSettled) {
+			// Mirror the base class: a result-less end() must not leave
+			// result() pending forever.
+			this.resultSettled = true;
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
+		}
+		this.endWaiting();
+	}
+}

package/src/utils/foundry.ts

@@ -0,0 +1,8 @@
+import { $env } from "jeopi-utils";
+
+export function isFoundryEnabled(): boolean {
+	const value = $env.CLAUDE_CODE_USE_FOUNDRY;
+	if (!value) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}

package/src/utils/google-validation.ts

@@ -0,0 +1,25 @@
+export function extractGoogleValidationUrl(errorBody: string): string | undefined {
+	if (!errorBody.includes("VALIDATION_REQUIRED")) return undefined;
+	const start = errorBody.indexOf("{");
+	if (start === -1) return undefined;
+	try {
+		const parsed = JSON.parse(errorBody.slice(start)) as {
+			error?: { details?: Array<{ reason?: string; metadata?: { validation_url?: string } }> };
+		};
+		const detail = parsed.error?.details?.find(
+			d => d.reason === "VALIDATION_REQUIRED" && typeof d.metadata?.validation_url === "string",
+		);
+		return detail?.metadata?.validation_url;
+	} catch {
+		return undefined;
+	}
+}
+
+export function formatGoogleValidationRequiredMessage(
+	validationUrl: string,
+	nextAction: string,
+	email?: string,
+): string {
+	const account = email ? ` for ${email}` : "";
+	return `Account verification required${account}. Visit ${validationUrl} to continue, then ${nextAction}.`;
+}