@sayknow-cli/ai 0.2.2

package/src/utils/http-inspector.ts

@@ -0,0 +1,255 @@
+import * as path from "node:path";
+import { APP_NAME, extractHttpStatusFromError, getLogsDir } from "@sayknow-cli/utils";
+import { isCopilotTransientModelError } from "./retry.js";
+import { formatErrorMessageWithRetryAfter } from "./retry-after.js";
+
+export type RawHttpRequestDump = {
+	provider: string;
+	api: string;
+	model: string;
+	method?: string;
+	url?: string;
+	headers?: Record<string, string>;
+	body?: unknown;
+};
+
+export type CapturedHttpErrorResponse = {
+	status: number;
+	headers?: Headers;
+	bodyText?: string;
+	bodyJson?: unknown;
+};
+
+type ErrorWithStatus = {
+	status?: unknown;
+};
+
+const SENSITIVE_HEADERS = ["authorization", "x-api-key", "api-key", "cookie", "set-cookie", "proxy-authorization"];
+
+/**
+ * Privacy note appended next to a saved raw HTTP request dump. The dump is
+ * sanitized (secrets/thinking redacted) but can still contain prompt content
+ * and request metadata, so we explicitly discourage pasting it into public
+ * channels (issue #438).
+ */
+const RAW_HTTP_REQUEST_PRIVACY_NOTE =
+	"note: this local file is for your own debugging and may contain prompt content or request metadata — review it before sharing and do not paste its contents into public channels (issues, Discord, etc.).";
+
+/**
+ * Patterns that indicate the configured model is unavailable on the provider
+ * (e.g. OpenAI's "The requested model '...' does not exist."). Used to surface
+ * actionable model/provider guidance instead of only a raw 400 + log path.
+ */
+const MODEL_UNAVAILABLE_PATTERNS: readonly RegExp[] = [
+	/\bmodel\b[^\n]*\bdoes not exist\b/i,
+	/\bdoes not exist\b[^\n]*\bmodel\b/i,
+	/\bmodel\b[^\n]*\b(not found|unavailable|not supported|no access|does not have access)\b/i,
+	/\b(unknown|unsupported|invalid)\s+model\b/i,
+];
+
+/** Whether `message` (from a 400 response) signals an unavailable/unknown model. */
+export function isModelUnavailableError(message: string, error: unknown): boolean {
+	if (extractHttpStatusFromError(error) !== 400) return false;
+	return MODEL_UNAVAILABLE_PATTERNS.some(pattern => pattern.test(message));
+}
+
+/** Actionable guidance for selecting an available model/provider. */
+export function formatModelUnavailableGuidance(dump: RawHttpRequestDump | undefined): string {
+	const modelPart = dump?.model ? ` '${dump.model}'` : "";
+	const providerPart = dump?.provider ? ` on provider '${dump.provider}'` : "";
+	return [
+		`The configured model${modelPart}${providerPart} is not available on this account/provider.`,
+		"Pick an available model before retrying:",
+		`  • List available models:  ${APP_NAME} --list-models`,
+		`  • Run with a model:        ${APP_NAME} --model <model>`,
+		`  • Configure a provider:    ${APP_NAME} setup provider`,
+	].join("\n");
+}
+
+export async function appendRawHttpRequestDumpFor400(
+	message: string,
+	error: unknown,
+	dump: RawHttpRequestDump | undefined,
+): Promise<string> {
+	if (!dump || extractHttpStatusFromError(error) !== 400) {
+		return message;
+	}
+
+	const sanitizedDump = sanitizeDump(dump);
+	const fileName = `${Date.now()}-${Bun.hash(JSON.stringify(sanitizedDump)).toString(36)}.json`;
+	const filePath = path.join(getLogsDir(), "http-400-requests", fileName);
+
+	try {
+		await Bun.write(filePath, `${JSON.stringify(sanitizedDump, null, 2)}\n`);
+		return `${message}\nraw-http-request=${filePath}\n${RAW_HTTP_REQUEST_PRIVACY_NOTE}`;
+	} catch (writeError) {
+		const writeMessage = writeError instanceof Error ? writeError.message : String(writeError);
+		return `${message}\nraw-http-request-save-failed=${writeMessage}`;
+	}
+}
+
+export async function finalizeErrorMessage(
+	error: unknown,
+	rawRequestDump: RawHttpRequestDump | undefined,
+	capturedErrorResponse?: CapturedHttpErrorResponse,
+): Promise<string> {
+	let message = formatErrorMessageWithRetryAfter(error, capturedErrorResponse?.headers);
+	const capturedMessage = formatCapturedHttpError(capturedErrorResponse);
+	if (capturedMessage) {
+		if (/\bstatus code\s*\(no body\)/i.test(message)) {
+			message = `${capturedErrorResponse?.status ?? "HTTP"} status code: ${capturedMessage}`;
+		} else if (!message.includes(capturedMessage)) {
+			message = `${message}\n${capturedMessage}`;
+		}
+	}
+	if (isModelUnavailableError(message, error)) {
+		message = `${message}\n\n${formatModelUnavailableGuidance(rawRequestDump)}`;
+	}
+	return appendRawHttpRequestDumpFor400(message, error, rawRequestDump);
+}
+
+export function withHttpStatus(error: unknown, status: number): Error {
+	const wrapped = error instanceof Error ? error : new Error(String(error));
+	(wrapped as ErrorWithStatus).status = status;
+	return wrapped;
+}
+
+/**
+ * Rewrite error message for GitHub Copilot request failures.
+ * Must run AFTER finalizeErrorMessage since it replaces the message entirely.
+ *
+ * 400 `model_not_supported` = Copilot routing rollout gap for our OAuth client.
+ *        A preview model (gpt-5.3-OpenAI code backend, gpt-5.4*, ...) flaps between 200 and
+ *        400 because only some of Copilot's backends have the model. After the
+ *        in-request retry exhausts, surface guidance rather than the raw error.
+ * 401 = token invalid/expired → credential removal is safe, prompt re-login.
+ * 403 = token valid but access denied (plan, model policy, org restriction) →
+ *       do NOT reuse the auth-failed string (which triggers credential removal).
+ */
+export function rewriteCopilotError(errorMessage: string, error: unknown, provider: string): string {
+	if (provider !== "github-copilot") return errorMessage;
+	const status = extractHttpStatusFromError(error);
+	if (status === 401) {
+		return `GitHub Copilot authentication failed (HTTP 401). Your token may have been revoked. Please re-login with /login github-copilot`;
+	}
+	if (status === 403) {
+		return `GitHub Copilot access denied (HTTP 403). Your account may not have access to this model or feature. Check your Copilot plan or model policy settings.`;
+	}
+	if (isCopilotTransientModelError(error)) {
+		return `GitHub Copilot rejected this model (HTTP 400 model_not_supported) after retries. This is a known intermittent rollout gap for preview models on OAuth clients other than VS Code. Try again in a few seconds, switch to a GA model (gpt-5-mini, gpt-5.2), or run this model from VS Code.`;
+	}
+	return errorMessage;
+}
+
+function sanitizeDump(dump: RawHttpRequestDump): RawHttpRequestDump {
+	return {
+		...dump,
+		headers: redactHeaders(dump.headers),
+		body: sanitizeDumpBody(dump.body),
+	};
+}
+
+function sanitizeDumpBody(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(item => sanitizeDumpBody(item));
+	}
+	if (!isObject(value)) {
+		return value;
+	}
+
+	const type = typeof value.type === "string" ? value.type : undefined;
+	const redactedKeys = getRedactedBodyKeys(type);
+	const sanitized: Record<string, unknown> = {};
+	for (const [key, property] of Object.entries(value)) {
+		if (redactedKeys.has(key)) {
+			sanitized[key] = "[redacted]";
+			continue;
+		}
+		sanitized[key] = sanitizeDumpBody(property);
+	}
+	return sanitized;
+}
+
+function getRedactedBodyKeys(type: string | undefined): Set<string> {
+	const keys = new Set<string>();
+	if (type === "thinking") {
+		keys.add("thinking");
+		keys.add("signature");
+		keys.add("thinkingSignature");
+		keys.add("thoughtSignature");
+	}
+	if (type === "redacted_thinking" || type === "redactedThinking") {
+		keys.add("data");
+	}
+	return keys;
+}
+
+function redactHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
+	if (!headers) {
+		return undefined;
+	}
+
+	const redacted: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+			redacted[key] = "[redacted]";
+			continue;
+		}
+		redacted[key] = value;
+	}
+	return redacted;
+}
+
+function formatCapturedHttpError(captured: CapturedHttpErrorResponse | undefined): string | undefined {
+	if (!captured) return undefined;
+	const bodyText = captured.bodyText?.trim();
+	if (!bodyText) return undefined;
+	const payload = parseCapturedErrorPayload(captured);
+	if (!payload) return bodyText;
+
+	const errorPayload = getObjectProperty(payload, "error") ?? payload;
+	// {"error": "string"} — the error value is a plain string, not a nested object.
+	// Fall back to it when the structured fields ("message", etc.) are absent.
+	const stringError = errorPayload === payload ? getStringProperty(payload, "error") : undefined;
+	const message =
+		getStringProperty(errorPayload, "message") ?? getStringProperty(payload, "message") ?? stringError ?? bodyText;
+	const extras = [
+		getStringProperty(errorPayload, "type") ?? getStringProperty(payload, "type"),
+		getStringProperty(errorPayload, "param") ?? getStringProperty(payload, "param"),
+		getStringProperty(errorPayload, "code") ?? getStringProperty(payload, "code"),
+	]
+		.filter(Boolean)
+		.map((value, index) => {
+			if (index === 0) return `type=${value}`;
+			if (index === 1) return `param=${value}`;
+			return `code=${value}`;
+		});
+	return extras.length > 0 ? `${message} (${extras.join(" ")})` : message;
+}
+
+function parseCapturedErrorPayload(captured: CapturedHttpErrorResponse): Record<string, unknown> | undefined {
+	if (isObject(captured.bodyJson)) {
+		return captured.bodyJson;
+	}
+	if (!captured.bodyText) return undefined;
+	try {
+		const parsed = JSON.parse(captured.bodyText);
+		return isObject(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function getObjectProperty(value: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
+	const property = value[key];
+	return isObject(property) ? property : undefined;
+}
+
+function getStringProperty(value: Record<string, unknown>, key: string): string | undefined {
+	const property = value[key];
+	return typeof property === "string" && property.trim().length > 0 ? property : undefined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/utils/idle-iterator.ts

@@ -0,0 +1,257 @@
+import { $env } from "@sayknow-cli/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);
+			// The idle deadline may already have elapsed because the *consumer*
+			// was slow, not because the provider stalled — and the next item may
+			// already be buffered and ready to deliver. Clamp to 0 instead of
+			// throwing eagerly so the next() race below still gets a chance to
+			// win (it settles on a microtask, ahead of the 0ms timer). Only a
+			// genuinely hung iterator loses that race and surfaces as a stall.
+			if (activeTimeoutMs < 0) {
+				activeTimeoutMs = 0;
+			}
+		}
+
+		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 &&
+			(awaitingFirstItem ? activeTimeoutMs > 0 : 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;
+		}
+	}
+}