@gajae-code/ai 0.11.10 → 0.11.11

package/CHANGELOG.md

@@ -2,7 +2,12 @@
 
 ## [Unreleased]
 
-## [0.11.10] - 2026-07-25
+## [0.11.11] - 2026-07-26
+
+### Fixed
+
+- Anthropic `ping` keepalives no longer reset stream progress, so responses that stop producing content now reach the idle timeout instead of hanging indefinitely.
+- The documented `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` environment variable now takes effect: the stream-watchdog idle-timeout helpers resolve it GJC-first before the legacy `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` / `PI_STREAM_IDLE_TIMEOUT_MS` aliases (previously only the `PI_`-prefixed names were read, so setting the documented GJC name was a silent no-op).
 
 ## [0.11.9] - 2026-07-24
 ### Fixed

package/dist/types/utils/idle-iterator.d.ts

@@ -2,7 +2,7 @@ export declare function getProviderFirstEventTimeoutFallbackMs(provider: string)
 /**
  * Returns the idle timeout used for provider streaming transports.
  *
- * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` is honored first; `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is 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
@@ -13,7 +13,7 @@ export declare function getStreamIdleTimeoutMs(fallbackMs?: number): number | un
 /**
  * Returns the idle timeout used for OpenAI-family streaming transports.
  *
- * Set `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ * Honors `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` first (`PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is the legacy alias). Set `=0` to disable.
  */
 export declare function getOpenAIStreamIdleTimeoutMs(): number | undefined;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.11.10",
+	"version": "0.11.11",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.11.10",
+		"@gajae-code/utils": "0.11.11",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/anthropic.ts

@@ -1182,6 +1182,40 @@ function shouldIgnoreAnthropicPreambleEvent(eventType: unknown): boolean {
 	return !ANTHROPIC_PRE_MESSAGE_START_EVENT_TYPES.has(eventType);
 }
 
+function createAnthropicStreamProgressPredicate(): (event: unknown) => boolean {
+	let outputTokens = -1;
+
+	return event => {
+		if (!isRecord(event) || typeof event.type !== "string") return false;
+		if (
+			event.type === "message_start" ||
+			event.type === "content_block_start" ||
+			event.type === "content_block_stop" ||
+			event.type === "message_stop"
+		) {
+			return true;
+		}
+		if (event.type === "content_block_delta") {
+			if (!isRecord(event.delta)) return false;
+			const delta = event.delta;
+			return (
+				(typeof delta.text === "string" && delta.text.length > 0) ||
+				(typeof delta.thinking === "string" && delta.thinking.length > 0) ||
+				(typeof delta.partial_json === "string" && delta.partial_json.length > 0) ||
+				(typeof delta.signature === "string" && delta.signature.length > 0)
+			);
+		}
+		if (event.type === "message_delta") {
+			if (isRecord(event.delta) && event.delta.stop_reason != null) return true;
+			if (!isRecord(event.usage) || typeof event.usage.output_tokens !== "number") return false;
+			if (event.usage.output_tokens <= outputTokens) return false;
+			outputTokens = event.usage.output_tokens;
+			return true;
+		}
+		return false;
+	};
+}
+
 function isTransientStreamEnvelopeError(error: unknown): boolean {
 	if (!(error instanceof Error)) return false;
 	return (
@@ -1457,6 +1491,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					let sawEvent = false;
 					let sawMessageStart = false;
 					let sawTerminalEnvelope = false;
+					const isProgressEvent = createAnthropicStreamProgressPredicate();
 
 					for await (const event of iterateWithIdleTimeout(anthropicStream, {
 						idleTimeoutMs,
@@ -1466,6 +1501,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						onIdle: () => activeAbortTracker.abortLocally(idleTimeoutAbortError),
 						onFirstItemTimeout: () => activeAbortTracker.abortLocally(firstEventTimeoutAbortError),
 						abortSignal: options?.signal,
+						isProgressItem: isProgressEvent,
 					})) {
 						sawEvent = true;
 						if (sawProviderSafetyStop) {

package/src/usage/claude.ts

@@ -17,6 +17,13 @@ const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
 const MAX_ATTEMPTS = 3;
 const BASE_RETRY_DELAY_MS = 500;
+/**
+ * Ceiling for a server-supplied `Retry-After`. Matches `OPENAI_RETRY_DELAY_CAP_MS`
+ * and `fetchWithRetry`'s `DEFAULT_MAX_DELAY_MS`. Without it a hostile or
+ * misconfigured endpoint stalls the usage fetch for as long as it likes
+ * (`Retry-After: 86400` previously produced a 24h sleep).
+ */
+const MAX_RETRY_DELAY_MS = 60_000;
 
 const CLAUDE_HEADERS = {
 	accept: "application/json, text/plain, */*",
@@ -140,13 +147,23 @@ function isAbortError(error: unknown, signal?: AbortSignal): boolean {
 	return error.name === "AbortError" || error.name === "TimeoutError";
 }
 
+/**
+ * Honour the server hint but never exceed `MAX_RETRY_DELAY_MS`, and never
+ * return a negative/non-finite delay. Keeps the sleep bounded so an abort has
+ * an upper bound to fire within.
+ */
+function clampRetryDelay(baseline: number, hintMs: number): number {
+	const hint = Number.isFinite(hintMs) ? Math.max(0, hintMs) : 0;
+	return Math.min(Math.max(baseline, hint), MAX_RETRY_DELAY_MS);
+}
+
 function retryDelayMs(attempt: number, retryAfter: string | null): number {
 	const baseline = BASE_RETRY_DELAY_MS * 2 ** attempt;
 	if (!retryAfter?.trim()) return baseline;
 	const seconds = Number.parseFloat(retryAfter);
-	if (Number.isFinite(seconds)) return Math.max(baseline, Math.max(0, seconds * 1000));
+	if (Number.isFinite(seconds)) return clampRetryDelay(baseline, seconds * 1000);
 	const dateDelay = Date.parse(retryAfter) - Date.now();
-	return Number.isFinite(dateDelay) ? Math.max(baseline, Math.max(0, dateDelay)) : baseline;
+	return Number.isFinite(dateDelay) ? clampRetryDelay(baseline, dateDelay) : baseline;
 }
 
 async function waitBeforeRetry(

package/src/utils/idle-iterator.ts

@@ -19,7 +19,7 @@ function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): nu
 /**
  * Returns the idle timeout used for provider streaming transports.
  *
- * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` is honored first; `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is 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
@@ -27,17 +27,20 @@ function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): nu
  * 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);
+	return normalizeIdleTimeoutMs(
+		$env.GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $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.
+ * Honors `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` first (`PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is the legacy alias). Set `=0` to disable.
  */
 export function getOpenAIStreamIdleTimeoutMs(): number | undefined {
 	return normalizeIdleTimeoutMs(
-		$env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS,
+		$env.GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS,
 		DEFAULT_STREAM_IDLE_TIMEOUT_MS,
 	);
 }
@@ -173,8 +176,6 @@ export async function* iterateWithIdleTimeout<T>(
 			}
 		}
 
-		const nextResultPromise = withRacy(iterator.next());
-
 		const racers: Array<
 			Promise<
 				| { kind: "next"; result: IteratorResult<T> }
@@ -182,7 +183,7 @@ export async function* iterateWithIdleTimeout<T>(
 				| { kind: "timeout" }
 				| { kind: "abort" }
 			>
-		> = [nextResultPromise];
+		> = [];
 
 		let timer: NodeJS.Timeout | undefined;
 		let resolveTimeout: ((value: { kind: "timeout" }) => void) | undefined;
@@ -207,6 +208,13 @@ export async function* iterateWithIdleTimeout<T>(
 			racers.push(promise);
 		}
 
+		// Arm timeout/abort races before asking the source for its next item. A
+		// periodic keepalive iterator commonly registers its own timer inside
+		// `next()`; registering that first lets equal-deadline keepalives win every
+		// race and extend the idle window forever. Already-buffered items still
+		// settle as microtasks before a 0ms watchdog.
+		racers.unshift(withRacy(iterator.next()));
+
 		try {
 			const outcome = await Promise.race(racers);
 			if (outcome.kind === "abort") {