@gajae-code/ai 0.10.2 → 0.11.0

package/src/utils/event-stream.ts

@@ -1,10 +1,32 @@
 import type { AssistantMessage, AssistantMessageEvent } from "../types";
 
+interface EventQueueNode<T> {
+	type: "event";
+	event: T;
+}
+
+type QueueNode<T> = EventQueueNode<T> | { type: "consumer-drain"; drain: ConsumerDrain };
+
+interface ConsumerDrain {
+	settled: boolean;
+	signal: AbortSignal;
+	abortListener: () => void;
+	resolve: () => void;
+	reject: (reason: unknown) => void;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+
 // Generic event stream class for async iteration
+
 export class EventStream<T, R = T> implements AsyncIterable<T> {
-	#queue: T[] = [];
+	#queue: QueueNode<T>[] = [];
 	#queueHead = 0;
 	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	#pendingConsumerDrains = new Set<ConsumerDrain>();
+	#activeConsumerCount = 0;
 	done = false;
 	#failed = false;
 	#error: unknown = undefined;
@@ -26,20 +48,20 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.extractResult = extractResult;
 	}
 
-	#enqueue(event: T): void {
-		this.#queue.push(event);
+	#enqueue(node: QueueNode<T>): void {
+		this.#queue.push(node);
 	}
 
-	#dequeue(): T | undefined {
+	#dequeue(): QueueNode<T> | undefined {
 		if (this.#queueHead >= this.#queue.length) return undefined;
-		const event = this.#queue[this.#queueHead]!;
-		this.#queue[this.#queueHead] = undefined as T;
+		const node = this.#queue[this.#queueHead]!;
+		this.#queue[this.#queueHead] = undefined as unknown as QueueNode<T>;
 		this.#queueHead++;
 		if (this.#queueHead > 1024 && this.#queueHead * 2 >= this.#queue.length) {
 			this.#queue = this.#queue.slice(this.#queueHead);
 			this.#queueHead = 0;
 		}
-		return event;
+		return node;
 	}
 
 	get #queueLength(): number {
@@ -49,10 +71,54 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	/**
 	 * Read-only snapshot of the not-yet-consumed events. Always a fresh copy:
 	 * external code can never mutate internal queue state or observe head-index
-	 * tombstones, so the deque cannot desynchronize.
+	 * tombstones or private consumer-drain sentinels, so the deque cannot desynchronize.
 	 */
 	get queue(): T[] {
-		return this.#queue.slice(this.#queueHead);
+		return this.#queue.slice(this.#queueHead).flatMap(node => (node.type === "event" ? [node.event] : []));
+	}
+
+	/** Read-only test seam for outstanding consumer-drain waiters. */
+	get pendingConsumerDrainCountForTests(): number {
+		return this.#pendingConsumerDrains.size;
+	}
+
+	#settleConsumerDrain(drain: ConsumerDrain, status: "resolve" | "reject", reason?: unknown): void {
+		if (drain.settled) return;
+		drain.settled = true;
+		this.#pendingConsumerDrains.delete(drain);
+		drain.signal.removeEventListener("abort", drain.abortListener);
+		if (status === "resolve") {
+			drain.resolve();
+		} else {
+			drain.reject(reason);
+		}
+	}
+
+	#settleAllConsumerDrains(status: "resolve" | "reject", reason?: unknown): void {
+		for (const drain of this.#pendingConsumerDrains) {
+			this.#settleConsumerDrain(drain, status, reason);
+		}
+	}
+
+	#drainQueuedNodesToWaitingConsumers(): void {
+		while (this.waiting.length > 0 && this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "consumer-drain") {
+				this.#settleConsumerDrain(node.drain, "resolve");
+
+				continue;
+			}
+			this.waiting.shift()!.resolve({ value: node.event, done: false });
+		}
+	}
+
+	#dequeueEvent(): EventQueueNode<T> | undefined {
+		while (this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "event") return node;
+			this.#settleConsumerDrain(node.drain, "resolve");
+		}
+		return undefined;
 	}
 
 	push(event: T): void {
@@ -63,26 +129,52 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 			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.#enqueue(event);
-		}
+		this.deliver(event);
 	}
 
 	deliver(event: T): void {
-		const waiter = this.waiting.shift();
-		if (waiter) {
-			waiter.resolve({ value: event, done: false });
-		} else {
-			this.#enqueue(event);
+		if (this.#queueLength === 0) {
+			const waiter = this.waiting.shift();
+			if (waiter) {
+				waiter.resolve({ value: event, done: false });
+				return;
+			}
+		}
+		this.#enqueue({ type: "event", event });
+		this.#drainQueuedNodesToWaitingConsumers();
+	}
+
+	/**
+	 * Resolves after every event enqueued before this call has been yielded and
+	 * the consumer asks the iterator for its next node. The private sentinel is
+	 * never exposed through the async iterator.
+	 */
+	waitForConsumerDrain(signal: AbortSignal): Promise<void> {
+		if (signal.aborted) return Promise.reject(abortReason(signal));
+		if (this.#failed) return Promise.reject(this.#error);
+		if (this.done && this.#activeConsumerCount === 0) {
+			if (this.#queueLength === 0) return Promise.resolve();
+			return Promise.reject(new Error("Event stream ended before queued events could be drained"));
 		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		let drain!: ConsumerDrain;
+		const abortListener = () => this.#settleConsumerDrain(drain, "reject", abortReason(signal));
+
+		drain = { settled: false, signal, abortListener, resolve, reject };
+		this.#pendingConsumerDrains.add(drain);
+		signal.addEventListener("abort", abortListener, { once: true });
+		this.#enqueue({ type: "consumer-drain", drain });
+		this.#drainQueuedNodesToWaitingConsumers();
+		return promise;
 	}
 
 	end(result?: R): void {
 		this.done = true;
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
+
 		if (result !== undefined) {
 			this.resolveFinalResult(result);
 		}
@@ -94,6 +186,9 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	}
 
 	endWaiting(): void {
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
 		while (this.waiting.length > 0) {
 			const waiter = this.waiting.shift()!;
 			waiter.resolve({ value: undefined as any, done: true });
@@ -105,6 +200,8 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 		this.done = true;
 		this.#failed = true;
 		this.#error = err;
+		this.#settleAllConsumerDrains("reject", err);
+
 		this.rejectFinalResult(err);
 		while (this.waiting.length > 0) {
 			const waiter = this.waiting.shift()!;
@@ -113,20 +210,27 @@ export class EventStream<T, R = T> implements AsyncIterable<T> {
 	}
 
 	async *[Symbol.asyncIterator](): AsyncIterator<T> {
-		while (true) {
-			if (this.#queueLength > 0) {
-				yield this.#dequeue()!;
-			} 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;
+		this.#activeConsumerCount += 1;
+		try {
+			while (true) {
+				const node = this.#dequeueEvent();
+				if (node !== undefined) {
+					yield node.event;
+				} 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;
+				}
 			}
+		} finally {
+			this.#activeConsumerCount -= 1;
+			this.#settleAllConsumerDrains("reject", new Error("Event stream consumer stopped before drain completed"));
 		}
 	}
 
@@ -149,24 +253,4 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 			},
 		);
 	}
-
-	override push(event: AssistantMessageEvent): void {
-		if (this.done) return;
-
-		// Completion resolves the final result and still emits the terminal event.
-		if (this.isComplete(event)) {
-			this.done = true;
-			this.resolveFinalResult(this.extractResult(event));
-		}
-
-		this.deliver(event);
-	}
-
-	override end(result?: AssistantMessage): void {
-		this.done = true;
-		if (result !== undefined) {
-			this.resolveFinalResult(result);
-		}
-		this.endWaiting();
-	}
 }

package/src/utils/fallback-transport.ts

@@ -0,0 +1,185 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+
+export interface FallbackTrigger {
+	class: FallbackTriggerClass;
+	retryAfterMs?: number;
+}
+
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ */
+export interface TransportFailureFacts {
+	kind: "transport";
+	status?: number;
+	providerCode?: string;
+	headers?: TransportHeaders;
+}
+
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+	readonly modelKey: string;
+	readonly attemptId: string | number;
+}
+
+const issuedAttemptTokens = new WeakSet<object>();
+const consumedAttemptTokens = new WeakSet<object>();
+
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken {
+	const token = Object.freeze({ modelKey, attemptId });
+	issuedAttemptTokens.add(token);
+	return token;
+}
+
+export function assertManagedAttempt(
+	options: { fallbackManaged?: boolean; fallbackAttempt?: FallbackAttemptToken } | undefined,
+): void {
+	if (!options?.fallbackManaged) return;
+	const token = options.fallbackAttempt;
+	if (!token || !issuedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation requires a token returned by beginAttempt()");
+	}
+	if (consumedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation cannot reuse a beginAttempt() token");
+	}
+	consumedAttemptTokens.add(token);
+}
+
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+	status?: number;
+	providerCode?: string;
+	code?: string;
+	headers?: TransportHeaders;
+	response?: { status?: number; headers?: TransportHeaders };
+	error?: { code?: string; type?: string };
+}
+
+function isTransportHeaders(value: unknown): value is TransportHeaders {
+	return value instanceof Headers || (!!value && typeof value === "object");
+}
+
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export function transportFailureFacts(
+	error: unknown,
+	capturedResponse?: { status?: number; headers?: TransportHeaders },
+): TransportFailureFacts | undefined {
+	if (!error || typeof error !== "object") return undefined;
+	const value = error as FallbackTriggerInput & { kind?: unknown; type?: unknown };
+	const status =
+		typeof value.status === "number"
+			? value.status
+			: typeof value.response?.status === "number"
+				? value.response.status
+				: capturedResponse?.status;
+	const providerCode =
+		typeof value.providerCode === "string"
+			? value.providerCode
+			: typeof value.code === "string"
+				? value.code
+				: typeof value.error?.code === "string"
+					? value.error.code
+					: typeof value.type === "string"
+						? value.type
+						: typeof value.error?.type === "string"
+							? value.error.type
+							: undefined;
+	const headers = isTransportHeaders(value.headers)
+		? value.headers
+		: isTransportHeaders(value.response?.headers)
+			? value.response.headers
+			: capturedResponse?.headers;
+	const normalizedCode = providerCode?.toLowerCase();
+	if (
+		status === undefined &&
+		headers === undefined &&
+		!isQuotaCode(normalizedCode) &&
+		!isAuthCode(normalizedCode) &&
+		!isRateLimitCode(normalizedCode)
+	) {
+		return undefined;
+	}
+	return { kind: "transport", status, providerCode, headers };
+}
+
+function headersOf(headers: TransportHeaders | undefined): Headers | undefined {
+	if (headers instanceof Headers) return headers;
+	return headers ? new Headers(headers as Record<string, string>) : undefined;
+}
+
+function parseRetryAfterSeconds(value: string | null, now = Date.now()): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+	const date = Date.parse(value);
+	return Number.isFinite(date) ? Math.max(0, date - now) : undefined;
+}
+
+function parseRetryAfterMilliseconds(value: string | null): number | undefined {
+	if (!value) return undefined;
+	const milliseconds = Number(value);
+	return Number.isFinite(milliseconds) && milliseconds >= 0 ? Math.round(milliseconds) : undefined;
+}
+
+function isQuotaCode(code: string | undefined): boolean {
+	return (
+		code === "insufficient_quota" ||
+		code === "quota_exceeded" ||
+		code === "quota_exhausted" ||
+		code === "usage_limit_reached" ||
+		code === "usage_not_included" ||
+		code === "out_of_credits"
+	);
+}
+
+function isAuthCode(code: string | undefined): boolean {
+	return (
+		code === "authentication_error" ||
+		code === "invalid_api_key" ||
+		code === "invalid_token" ||
+		code === "token_expired" ||
+		code === "unauthorized" ||
+		code === "forbidden"
+	);
+}
+
+function isRateLimitCode(code: string | undefined): boolean {
+	return (
+		code === "rate_limit" ||
+		code === "rate_limit_error" ||
+		code === "rate_limit_exceeded" ||
+		code === "too_many_requests"
+	);
+}
+
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export function classifyFallbackTrigger(
+	errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown,
+): FallbackTrigger {
+	const facts = transportFailureFacts(errorOrFacts);
+	if (!facts) return { class: "other" };
+	const headers = headersOf(facts.headers);
+	const retryAfterMs =
+		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
+		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
+	const code = facts.providerCode?.toLowerCase();
+	const triggerClass: FallbackTriggerClass = isQuotaCode(code)
+		? "quota"
+		: facts.status === 401 || facts.status === 403 || isAuthCode(code)
+			? "auth"
+			: facts.status === 429 || isRateLimitCode(code)
+				? "rate_limit"
+				: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
+					? "server"
+					: "other";
+	return retryAfterMs === undefined ? { class: triggerClass } : { class: triggerClass, retryAfterMs };
+}

package/src/utils/retry.ts

@@ -34,9 +34,9 @@ const COPILOT_MODEL_RETRY_BASE_DELAY_MS = 400;
  */
 export async function callWithCopilotModelRetry<T>(
 	fn: () => Promise<T>,
-	options: { provider: string; signal?: AbortSignal; retryBaseDelayMs?: number },
+	options: { provider: string; signal?: AbortSignal; retryBaseDelayMs?: number; fallbackManaged?: boolean },
 ): Promise<T> {
-	if (options.provider !== "github-copilot") return fn();
+	if (options.provider !== "github-copilot" || options.fallbackManaged) return fn();
 
 	let lastError: unknown;
 	const retryBaseDelayMs = options.retryBaseDelayMs ?? COPILOT_MODEL_RETRY_BASE_DELAY_MS;

package/src/utils.ts

@@ -119,7 +119,8 @@ export function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record
 		return sanitized ? [sanitized] : [];
 	});
 }
-const RESERVED_CONTROL_TOKEN_RE = /<\|(?=[A-Za-z0-9_]{1,32}\|>)/g;
+const RESERVED_CONTROL_TOKEN_RE =
+	/<\|(?=(?:[A-Za-z0-9_]+|(?:system|developer|user|assistant|tool)[ \t]+to=[^\s<>|]+)\|>)/g;
 /**
  * Neutralize leaked OpenAI Harmony / control tokens (`<|channel|>`, `<|message|>`,
  * `<|call|>`, `<|constrain|>`, `<|recipient|>`, `<|content|>`, ...) in replayed
@@ -130,6 +131,23 @@ const RESERVED_CONTROL_TOKEN_RE = /<\|(?=[A-Za-z0-9_]{1,32}\|>)/g;
  * the offending item is re-sent on each turn. Insert a zero-width space after `<`
  * so the delimiter can no longer be tokenized as a reserved control token while the
  * text stays human-readable.
+ *
+ * The pattern matches the two control-token shapes only, so ordinary text and pipe
+ * syntax is left untouched:
+ *   - simple form `<|ident|>` — a leading run of identifier chars then `|>`; and
+ *   - header form `<|role to=recipient|>` — a known Harmony role
+ *     (`system`/`developer`/`user`/`assistant`/`tool`) followed by a single
+ *     recipient assignment `to=<recipient>` whose value is an unbounded run of
+ *     non-delimiter, non-whitespace chars (so long MCP/custom tool recipients like
+ *     `to=functions.<long.name>` are covered).
+ * The header branch is deliberately scoped to the known role + `to=` recipient
+ * grammar rather than an arbitrary `key=value`, so request-boundary sanitization
+ * never rewrites non-control delimiter text such as `<|foo bar=baz|>`. A single-line
+ * body (no `\n`) and the required leading identifier char also leave compact
+ * pipe/operator syntax alone — e.g. F# `value <| f |> g` (space after `<|`),
+ * `sum<|a+b|>c` (punctuation body), and `<|foo bar|>` (no assignment) never match.
+ * The simple branch is a strict superset of the original identifier-only pattern:
+ * every marker the old regex caught still matches.
  */
 export function neutralizeReservedControlTokens(text: string): string {
 	if (!text.includes("<|")) return text;