@gajae-code/ai 0.1.1

package/src/utils/idle-iterator.ts

@@ -0,0 +1,250 @@
+import { $env } from "@gajae-code/utils";
+
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120_000;
+const DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS = 100_000;
+
+function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): number | undefined {
+	if (value === undefined) return fallback;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed)) return fallback;
+	if (parsed <= 0) return undefined;
+	return Math.trunc(parsed);
+}
+
+/**
+ * Returns the idle timeout used for provider streaming transports.
+ *
+ * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * Set `PI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers that legitimately stream much slower than the global default can pass
+ * `fallbackMs` to widen the floor used when neither env var nor caller option is set.
+ * Caller options still take precedence; env overrides still trump the fallback.
+ */
+export function getStreamIdleTimeoutMs(fallbackMs: number = DEFAULT_STREAM_IDLE_TIMEOUT_MS): number | undefined {
+	return normalizeIdleTimeoutMs($env.PI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS, fallbackMs);
+}
+
+/**
+ * Returns the idle timeout used for OpenAI-family streaming transports.
+ *
+ * Set `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ */
+export function getOpenAIStreamIdleTimeoutMs(): number | undefined {
+	return normalizeIdleTimeoutMs(
+		$env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS,
+		DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+	);
+}
+
+/**
+ * Returns the timeout used while waiting for the first stream event.
+ * The first token can legitimately take longer than later inter-event gaps,
+ * so the default never undershoots the steady-state idle timeout.
+ *
+ * Set `PI_STREAM_FIRST_EVENT_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers whose first response can legitimately take longer (heavy reasoning,
+ * slow cold-start proxies) can pass `fallbackMs` to widen the floor used when
+ * neither env var nor caller option is set. Caller options still take precedence;
+ * env overrides still trump the fallback.
+ */
+export function getStreamFirstEventTimeoutMs(
+	idleTimeoutMs?: number,
+	fallbackMs: number = DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS,
+): number | undefined {
+	const fallback = idleTimeoutMs === undefined ? fallbackMs : Math.max(fallbackMs, idleTimeoutMs);
+	return normalizeIdleTimeoutMs($env.PI_STREAM_FIRST_EVENT_TIMEOUT_MS, fallback);
+}
+
+export type Watchdog = NodeJS.Timeout | undefined;
+
+const dummyWatchdog = setTimeout(() => {}, 1);
+clearTimeout(dummyWatchdog);
+
+/**
+ * Starts a watchdog that aborts a request if no first stream event arrives in time.
+ * Call `markFirstEventReceived()` as soon as the first event is observed.
+ */
+export function createWatchdog(timeoutMs: number | undefined, onTimeout: () => void): Watchdog {
+	if (timeoutMs !== undefined && timeoutMs > 0) {
+		return setTimeout(onTimeout, timeoutMs);
+	}
+	return undefined;
+}
+
+export interface IdleTimeoutIteratorOptions {
+	watchdog?: Watchdog;
+	idleTimeoutMs?: number;
+	firstItemTimeoutMs?: number;
+	errorMessage: string;
+	firstItemErrorMessage?: string;
+	onIdle?: () => void;
+	onFirstItemTimeout?: () => void;
+	/**
+	 * Optional semantic-progress predicate. Non-progress items are still yielded,
+	 * but they do not reset the idle deadline. This prevents provider
+	 * keepalive/no-op events from keeping a stalled tool call alive forever.
+	 */
+	isProgressItem?: (item: unknown) => boolean;
+	/**
+	 * Cancel iteration as soon as this signal aborts. Required for caller-driven
+	 * cancellation (ESC) when the underlying transport does not surface signal
+	 * aborts to the iterator (HTTP/2 proxies, native sockets, mocked fetch).
+	 * Without this, the consumer sleeps on iterator.next() until the idle/first
+	 * -event watchdog fires — observable as the issue #912 "Working… forever"
+	 * symptom on the github-copilot provider.
+	 */
+	abortSignal?: AbortSignal;
+}
+
+/**
+ * Yields items from an async iterable while enforcing a maximum idle gap between items.
+ *
+ * The first item may use a shorter timeout so stuck requests can be aborted and retried
+ * before any user-visible content has streamed.
+ */
+export async function* iterateWithIdleTimeout<T>(
+	iterable: AsyncIterable<T>,
+	options: IdleTimeoutIteratorOptions,
+): AsyncGenerator<T> {
+	let watchdog = options.watchdog;
+	const firstItemTimeoutMs = options.firstItemTimeoutMs ?? options.idleTimeoutMs;
+	const abortSignal = options.abortSignal;
+	const iterator = iterable[Symbol.asyncIterator]();
+
+	const closeIterator = (): void => {
+		const returnPromise = iterator.return?.();
+		if (returnPromise) {
+			void returnPromise.catch(() => {});
+		}
+	};
+
+	if (abortSignal?.aborted) {
+		closeIterator();
+		throw abortReason(abortSignal);
+	}
+
+	const withRacy = <T>(promise: Promise<T>) =>
+		promise.then(
+			result => ({ kind: "next" as const, result }),
+			error => ({ kind: "error" as const, error }),
+		);
+
+	let awaitingFirstItem = true;
+	const markFirstItemReceived = () => {
+		watchdog && clearTimeout(watchdog);
+		watchdog = undefined;
+		awaitingFirstItem = false;
+	};
+	const isProgressItem = (item: T): boolean => {
+		if (!options.isProgressItem) return true;
+		try {
+			return options.isProgressItem(item);
+		} catch {
+			return true;
+		}
+	};
+	let lastProgressAt = Date.now();
+
+	const noTimeoutEnforced =
+		(firstItemTimeoutMs === undefined || firstItemTimeoutMs <= 0) &&
+		(options.idleTimeoutMs === undefined || options.idleTimeoutMs <= 0);
+
+	while (true) {
+		let activeTimeoutMs: number | undefined;
+		if (awaitingFirstItem) {
+			activeTimeoutMs = firstItemTimeoutMs;
+		} else if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0) {
+			activeTimeoutMs = options.idleTimeoutMs - (Date.now() - lastProgressAt);
+			if (activeTimeoutMs <= 0) {
+				options.onIdle?.();
+				closeIterator();
+				throw new Error(options.errorMessage);
+			}
+		}
+
+		const nextResultPromise = withRacy(iterator.next());
+
+		const racers: Array<
+			Promise<
+				| { kind: "next"; result: IteratorResult<T> }
+				| { kind: "error"; error: unknown }
+				| { kind: "timeout" }
+				| { kind: "abort" }
+			>
+		> = [nextResultPromise];
+
+		let timer: NodeJS.Timeout | undefined;
+		let resolveTimeout: ((value: { kind: "timeout" }) => void) | undefined;
+		const enforceTimeout = !noTimeoutEnforced && activeTimeoutMs !== undefined && activeTimeoutMs > 0;
+		if (enforceTimeout) {
+			const { promise, resolve } = Promise.withResolvers<{ kind: "timeout" }>();
+			resolveTimeout = resolve;
+			timer = setTimeout(() => resolve({ kind: "timeout" }), activeTimeoutMs);
+			racers.push(promise);
+		}
+
+		let abortListener: (() => void) | undefined;
+		let resolveAbort: ((value: { kind: "abort" }) => void) | undefined;
+		if (abortSignal) {
+			const { promise, resolve } = Promise.withResolvers<{ kind: "abort" }>();
+			resolveAbort = resolve;
+			abortListener = () => resolve({ kind: "abort" });
+			abortSignal.addEventListener("abort", abortListener, { once: true });
+			racers.push(promise);
+		}
+
+		try {
+			const outcome = await Promise.race(racers);
+			if (outcome.kind === "abort") {
+				closeIterator();
+				throw abortReason(abortSignal!);
+			}
+			if (outcome.kind === "timeout") {
+				if (!awaitingFirstItem) {
+					options.onIdle?.();
+				} else {
+					options.onFirstItemTimeout?.();
+				}
+				closeIterator();
+				throw new Error(
+					!awaitingFirstItem ? options.errorMessage : (options.firstItemErrorMessage ?? options.errorMessage),
+				);
+			}
+			if (outcome.kind === "error") {
+				throw outcome.error;
+			}
+			if (outcome.result.done) {
+				markFirstItemReceived();
+				return;
+			}
+			const item = outcome.result.value;
+			// Non-progress items (e.g. provider keepalives, synthetic `start` events that
+			// arrive before the model has produced any tokens) MUST NOT flip us out of
+			// `awaitingFirstItem`. Otherwise the next iteration switches from the (longer)
+			// first-item watchdog to the (shorter) idle watchdog while we're still waiting
+			// on the model's first real output.
+			if (isProgressItem(item)) {
+				markFirstItemReceived();
+				lastProgressAt = Date.now();
+			}
+			yield item;
+		} finally {
+			if (timer !== undefined) clearTimeout(timer);
+			// Resolve dangling promises so the racers don't leak (Promise.race is one-shot).
+			resolveTimeout?.({ kind: "timeout" });
+			if (abortListener && abortSignal) {
+				abortSignal.removeEventListener("abort", abortListener);
+			}
+			resolveAbort?.({ kind: "abort" });
+		}
+	}
+}
+
+function abortReason(signal: AbortSignal): Error {
+	const reason = signal.reason;
+	if (reason instanceof Error) return reason;
+	if (typeof reason === "string") return new Error(reason);
+	return new Error("Request was aborted");
+}

package/src/utils/json-parse.ts

@@ -0,0 +1,148 @@
+import { parse as partialParse } from "partial-json";
+
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const U = 0x75;
+
+// Valid chars after `\`: " \ / b f n r t u
+const VALID_ESCAPE_CHAR = new Uint8Array(128);
+for (const ch of '"\\/bfnrtu') VALID_ESCAPE_CHAR[ch.charCodeAt(0)] = 1;
+
+const CONTROL_ESCAPES: readonly string[] = (() => {
+	const e: string[] = [];
+	e[0x08] = "\\b";
+	e[0x09] = "\\t";
+	e[0x0a] = "\\n";
+	e[0x0c] = "\\f";
+	e[0x0d] = "\\r";
+	for (let cp = 0; cp <= 0x1f; cp++) {
+		e[cp] ??= `\\u${cp.toString(16).padStart(4, "0")}`;
+	}
+	return e;
+})();
+
+function isHexDigit(cp: number): boolean {
+	return (cp >= 0x30 && cp <= 0x39) || ((cp | 0x20) >= 0x61 && (cp | 0x20) <= 0x66);
+}
+
+export function repairJson(json: string): string {
+	const len = json.length;
+	const parts: string[] = [];
+	let lastEmit = 0;
+	let inString = false;
+	let i = 0;
+
+	while (i < len) {
+		if (!inString) {
+			// Fast scan: skip to next quote.
+			while (i < len && json.charCodeAt(i) !== QUOTE) i++;
+			if (i >= len) break;
+			inString = true;
+			i++;
+			continue;
+		}
+
+		// Fast scan inside string: advance past chars that need no handling.
+		while (i < len) {
+			const cp = json.charCodeAt(i);
+			if (cp < 0x20 || cp === QUOTE || cp === BACKSLASH) break;
+			i++;
+		}
+		if (i >= len) break;
+
+		const cp = json.charCodeAt(i);
+
+		if (cp === QUOTE) {
+			inString = false;
+			i++;
+			continue;
+		}
+
+		if (cp === BACKSLASH) {
+			// Need at least one char after the backslash; treat EOI as invalid escape.
+			if (i + 1 >= len) {
+				parts.push(json.slice(lastEmit, i), "\\\\");
+				lastEmit = i + 1;
+				i++;
+				continue;
+			}
+
+			const nextCp = json.charCodeAt(i + 1);
+
+			if (nextCp === U) {
+				// Need full \uXXXX, all four digits, all hex.
+				if (
+					i + 5 < len &&
+					isHexDigit(json.charCodeAt(i + 2)) &&
+					isHexDigit(json.charCodeAt(i + 3)) &&
+					isHexDigit(json.charCodeAt(i + 4)) &&
+					isHexDigit(json.charCodeAt(i + 5))
+				) {
+					i += 6;
+					continue;
+				}
+				// Truncated or non-hex \u — escape the backslash, re-process the rest.
+				parts.push(json.slice(lastEmit, i), "\\\\");
+				lastEmit = i + 1;
+				i++;
+				continue;
+			}
+
+			if (nextCp < 128 && VALID_ESCAPE_CHAR[nextCp] === 1) {
+				i += 2;
+				continue;
+			}
+
+			parts.push(json.slice(lastEmit, i), "\\\\");
+			lastEmit = i + 1;
+			i++;
+			continue;
+		}
+
+		// Control character (cp < 0x20).
+		parts.push(json.slice(lastEmit, i), CONTROL_ESCAPES[cp]);
+		lastEmit = i + 1;
+		i++;
+	}
+
+	if (!parts.length) return json;
+	if (lastEmit < len) parts.push(json.slice(lastEmit));
+	return parts.join("");
+}
+
+export function parseJsonWithRepair<T>(json: string): T {
+	try {
+		return JSON.parse(json) as T;
+	} catch (error) {
+		const repairedJson = repairJson(json);
+		if (repairedJson !== json) {
+			return JSON.parse(repairedJson) as T;
+		}
+		throw error;
+	}
+}
+
+/**
+ * Attempts to parse potentially incomplete JSON during streaming.
+ * Always returns a valid object, even if the JSON is incomplete.
+ *
+ * @param partialJson The partial JSON string from streaming
+ * @returns Parsed object or empty object if parsing fails
+ */
+export function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T {
+	partialJson = partialJson?.trimStart();
+	if (!partialJson) {
+		return {} as T;
+	}
+	try {
+		return JSON.parse(partialJson) as T;
+	} catch {
+		partialJson = repairJson(partialJson);
+		try {
+			return (partialParse(partialJson) ?? {}) as T;
+		} catch {
+			// If all parsing fails, return empty object
+			return {} as T;
+		}
+	}
+}

package/src/utils/oauth/alibaba-coding-plan.ts

@@ -0,0 +1,59 @@
+/**
+ * Alibaba Coding Plan login flow.
+ *
+ * Alibaba Coding Plan provides OpenAI-compatible models via https://coding-intl.dashscope.aliyuncs.com/v1.
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. Open browser to Alibaba Cloud DashScope API key settings
+ * 2. User copies their API key
+ * 3. User pastes the API key into the CLI
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://modelstudio.console.alibabacloud.com/";
+const API_BASE_URL = "https://coding-intl.dashscope.aliyuncs.com/v1";
+const VALIDATION_MODEL = "qwen3.5-plus";
+
+/**
+ * Login to Alibaba Coding Plan.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginAlibabaCodingPlan(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Alibaba Coding Plan login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your API key from the Alibaba Cloud DashScope console",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Alibaba Coding Plan API key",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.("Validating API key...");
+	await validateOpenAICompatibleApiKey({
+		provider: "Alibaba Coding Plan",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+
+	return trimmed;
+}

package/src/utils/oauth/anthropic.ts

@@ -0,0 +1,200 @@
+/**
+ * Anthropic OAuth flow (Anthropic model Pro/Max)
+ */
+import { OAuthCallbackFlow } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl");
+const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+const TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
+const CALLBACK_PORT = 54545;
+const CALLBACK_PATH = "/callback";
+const SCOPES = "org:create_api_key user:profile user:inference";
+
+function formatErrorDetails(error: unknown): string {
+	if (error instanceof Error) {
+		const details: string[] = [`${error.name}: ${error.message}`];
+		const errorWithCode = error as Error & { code?: string; errno?: number | string; cause?: unknown };
+		if (errorWithCode.code) details.push(`code=${errorWithCode.code}`);
+		if (typeof errorWithCode.errno !== "undefined") details.push(`errno=${String(errorWithCode.errno)}`);
+		if (typeof error.cause !== "undefined") {
+			details.push(`cause=${formatErrorDetails(error.cause)}`);
+		}
+		if (error.stack) {
+			details.push(`stack=${error.stack}`);
+		}
+		return details.join("; ");
+	}
+	return String(error);
+}
+
+async function postJson(url: string, body: Record<string, string | number>): Promise<string> {
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json",
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	const responseBody = await response.text();
+	if (!response.ok) {
+		throw new Error(`HTTP request failed. status=${response.status}; url=${url}; body=${responseBody}`);
+	}
+	return responseBody;
+}
+
+/**
+ * Decoded shape of Anthropic's `/v1/oauth/token` response (both
+ * `authorization_code` exchange and `refresh_token` refresh return the same
+ * envelope). The `account` block is inlined alongside the tokens, so we can
+ * surface `accountId` / `email` on {@link OAuthCredentials} without a separate
+ * `/api/oauth/profile` round-trip.
+ */
+interface AnthropicTokenResponse {
+	access_token: string;
+	refresh_token: string;
+	expires_in: number;
+	account?: { uuid?: string; email_address?: string };
+}
+
+function parseOAuthTokenResponse(responseBody: string, operation: string): AnthropicTokenResponse {
+	try {
+		return JSON.parse(responseBody) as AnthropicTokenResponse;
+	} catch (error) {
+		throw new Error(
+			`Anthropic ${operation} returned invalid JSON. url=${TOKEN_URL}; body=${responseBody}; details=${formatErrorDetails(error)}`,
+		);
+	}
+}
+
+/**
+ * Lift the OAuth response's `account: { uuid, email_address }` block onto
+ * {@link OAuthCredentials} so downstream identity propagation (e.g.
+ * `metadata.user_id.account_uuid`, usage tracking) works without a separate
+ * `/api/oauth/profile` round-trip. Returns `undefined` for either field when
+ * the response omits it or carries a non-string / empty value.
+ */
+function extractAccountFromTokenResponse(data: AnthropicTokenResponse): {
+	accountId?: string;
+	email?: string;
+} {
+	const accountUuid = data.account?.uuid;
+	const emailAddress = data.account?.email_address;
+	return {
+		accountId: typeof accountUuid === "string" && accountUuid.length > 0 ? accountUuid : undefined,
+		email: typeof emailAddress === "string" && emailAddress.length > 0 ? emailAddress : undefined,
+	};
+}
+
+export class AnthropicOAuthFlow extends OAuthCallbackFlow {
+	#verifier: string = "";
+	#challenge: string = "";
+
+	constructor(ctrl: OAuthController) {
+		super(ctrl, CALLBACK_PORT, CALLBACK_PATH);
+	}
+
+	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+		const pkce = await generatePKCE();
+		this.#verifier = pkce.verifier;
+		this.#challenge = pkce.challenge;
+
+		const authParams = new URLSearchParams({
+			code: "true",
+			client_id: CLIENT_ID,
+			response_type: "code",
+			redirect_uri: redirectUri,
+			scope: SCOPES,
+			code_challenge: this.#challenge,
+			code_challenge_method: "S256",
+			state,
+		});
+		const url = `${AUTHORIZE_URL}?${authParams.toString()}`;
+
+		return {
+			url,
+			instructions:
+				"Complete login in your browser. If the browser cannot reach this machine, paste the final redirect URL or authorization code when prompted.",
+		};
+	}
+
+	async exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials> {
+		let exchangeCode = code;
+		let exchangeState = state;
+		const codeFragmentIndex = code.indexOf("#");
+		if (codeFragmentIndex >= 0) {
+			exchangeCode = code.slice(0, codeFragmentIndex);
+			const codeFragmentState = code.slice(codeFragmentIndex + 1);
+			if (codeFragmentState.length > 0) {
+				exchangeState = codeFragmentState;
+			}
+		}
+
+		let responseBody: string;
+		try {
+			responseBody = await postJson(TOKEN_URL, {
+				grant_type: "authorization_code",
+				client_id: CLIENT_ID,
+				code: exchangeCode,
+				state: exchangeState,
+				redirect_uri: redirectUri,
+				code_verifier: this.#verifier,
+			});
+		} catch (error) {
+			throw new Error(
+				`Token exchange request failed. url=${TOKEN_URL}; redirect_uri=${redirectUri}; response_type=authorization_code; details=${formatErrorDetails(error)}`,
+			);
+		}
+
+		const tokenData = parseOAuthTokenResponse(responseBody, "token exchange");
+		const { accountId, email } = extractAccountFromTokenResponse(tokenData);
+
+		return {
+			refresh: tokenData.refresh_token,
+			access: tokenData.access_token,
+			expires: Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000,
+			accountId,
+			email,
+		};
+	}
+}
+
+/**
+ * Login with Anthropic OAuth
+ */
+export async function loginAnthropic(ctrl: OAuthController): Promise<OAuthCredentials> {
+	const flow = new AnthropicOAuthFlow(ctrl);
+	return flow.login();
+}
+
+/**
+ * Refresh Anthropic OAuth token
+ */
+export async function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials> {
+	let responseBody: string;
+	try {
+		responseBody = await postJson(TOKEN_URL, {
+			grant_type: "refresh_token",
+			client_id: CLIENT_ID,
+			refresh_token: refreshToken,
+		});
+	} catch (error) {
+		throw new Error(`Anthropic token refresh request failed. url=${TOKEN_URL}; details=${formatErrorDetails(error)}`);
+	}
+
+	const data = parseOAuthTokenResponse(responseBody, "token refresh");
+	const { accountId, email } = extractAccountFromTokenResponse(data);
+
+	return {
+		refresh: data.refresh_token || refreshToken,
+		access: data.access_token,
+		expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+		accountId,
+		email,
+	};
+}