@clinebot/llms 0.0.0

package/src/providers/utils/retry.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	calculateRetryDelay,
+	isRetriableError,
+	RetriableError,
+	retryAsync,
+	retryStream,
+} from "./retry";
+
+describe("retry utils", () => {
+	it("detects retriable errors from known patterns", () => {
+		expect(isRetriableError(new RetriableError("try again"))).toBe(true);
+		expect(isRetriableError(new Error("HTTP 429: Too Many Requests"))).toBe(
+			true,
+		);
+		expect(isRetriableError(new Error("upstream 503 failure"))).toBe(true);
+		expect(isRetriableError(new Error("network timeout occurred"))).toBe(true);
+		expect(isRetriableError(new Error("validation failed"))).toBe(false);
+		expect(isRetriableError("not-an-error")).toBe(false);
+	});
+
+	it("calculates exponential delay with jitter and max cap", () => {
+		const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0);
+
+		const noJitter = calculateRetryDelay(2, { baseDelay: 10, maxDelay: 1000 });
+		expect(noJitter).toBe(40);
+
+		randomSpy.mockReturnValue(1);
+		const capped = calculateRetryDelay(10, { baseDelay: 1000, maxDelay: 1500 });
+		expect(capped).toBe(1500);
+
+		randomSpy.mockRestore();
+	});
+
+	it("retries async function until success and calls onRetryAttempt", async () => {
+		let attempts = 0;
+		const onRetryAttempt = vi.fn();
+
+		const value = await retryAsync(
+			async () => {
+				attempts++;
+				if (attempts < 3) {
+					throw new RetriableError("retry me");
+				}
+				return "ok";
+			},
+			{
+				maxRetries: 3,
+				baseDelay: 0,
+				maxDelay: 0,
+				onRetryAttempt,
+			},
+		);
+
+		expect(value).toBe("ok");
+		expect(attempts).toBe(3);
+		expect(onRetryAttempt).toHaveBeenCalledTimes(2);
+		expect(onRetryAttempt).toHaveBeenNthCalledWith(
+			1,
+			1,
+			3,
+			0,
+			expect.any(RetriableError),
+		);
+		expect(onRetryAttempt).toHaveBeenNthCalledWith(
+			2,
+			2,
+			3,
+			0,
+			expect.any(RetriableError),
+		);
+	});
+
+	it("respects retry-after seconds for retriable errors", async () => {
+		let attempts = 0;
+		const onRetryAttempt = vi.fn();
+
+		vi.useFakeTimers();
+
+		const pending = retryAsync(
+			async () => {
+				attempts++;
+				if (attempts === 1) {
+					throw new RetriableError("rate limited", 2);
+				}
+				return "done";
+			},
+			{
+				maxRetries: 2,
+				onRetryAttempt,
+			},
+		);
+		await vi.runAllTimersAsync();
+		await pending;
+		vi.useRealTimers();
+
+		expect(onRetryAttempt).toHaveBeenCalledWith(
+			1,
+			2,
+			2000,
+			expect.any(RetriableError),
+		);
+	});
+
+	it("does not retry non-retriable errors", async () => {
+		const fn = vi.fn(async () => {
+			throw new Error("bad input");
+		});
+
+		await expect(
+			retryAsync(fn, {
+				maxRetries: 3,
+				baseDelay: 0,
+				maxDelay: 0,
+			}),
+		).rejects.toThrow("bad input");
+		expect(fn).toHaveBeenCalledTimes(1);
+	});
+
+	it("retries async generators and preserves yielded chunks", async () => {
+		let attempts = 0;
+		const chunks: Array<{ type: string; text?: string }> = [];
+		for await (const chunk of retryStream(
+			async function* () {
+				attempts++;
+				if (attempts < 3) {
+					throw new RetriableError("temporary");
+				}
+				yield { type: "text", text: "hello" };
+				yield { type: "done" };
+			},
+			{ maxRetries: 3, baseDelay: 0, maxDelay: 0 },
+		)) {
+			chunks.push(chunk);
+		}
+
+		expect(chunks).toEqual([{ type: "text", text: "hello" }, { type: "done" }]);
+		expect(attempts).toBe(3);
+	});
+});

package/src/providers/utils/retry.ts

@@ -0,0 +1,188 @@
+/**
+ * Retry Utilities
+ *
+ * Provides retry logic with exponential backoff for API calls.
+ */
+
+export interface RetryOptions {
+	maxRetries?: number;
+	baseDelay?: number;
+	maxDelay?: number;
+	onRetryAttempt?: (
+		attempt: number,
+		maxRetries: number,
+		delay: number,
+		error: unknown,
+	) => void;
+}
+
+const DEFAULT_OPTIONS: Required<Omit<RetryOptions, "onRetryAttempt">> = {
+	maxRetries: 4,
+	baseDelay: 2000,
+	maxDelay: 15000,
+};
+
+/**
+ * Error that indicates the operation should be retried
+ */
+export class RetriableError extends Error {
+	constructor(
+		message: string,
+		public readonly retryAfterSeconds?: number,
+		options?: ErrorOptions,
+	) {
+		super(message, options);
+		this.name = "RetriableError";
+	}
+}
+
+/**
+ * Check if an error is retriable
+ */
+export function isRetriableError(error: unknown): boolean {
+	if (error instanceof RetriableError) {
+		return true;
+	}
+
+	if (error instanceof Error) {
+		const message = error.message.toLowerCase();
+
+		// Rate limit errors
+		if (
+			message.includes("429") ||
+			message.includes("rate limit") ||
+			message.includes("too many requests")
+		) {
+			return true;
+		}
+
+		// Server errors (5xx)
+		if (
+			message.includes("500") ||
+			message.includes("502") ||
+			message.includes("503") ||
+			message.includes("504")
+		) {
+			return true;
+		}
+
+		// Network errors
+		if (
+			message.includes("network") ||
+			message.includes("timeout") ||
+			message.includes("econnreset") ||
+			message.includes("econnrefused")
+		) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Calculate delay for retry attempt with exponential backoff and jitter
+ */
+export function calculateRetryDelay(
+	attempt: number,
+	options: RetryOptions = {},
+): number {
+	const {
+		baseDelay = DEFAULT_OPTIONS.baseDelay,
+		maxDelay = DEFAULT_OPTIONS.maxDelay,
+	} = options;
+
+	// Exponential backoff: 2^attempt * baseDelay
+	const exponentialDelay = 2 ** attempt * baseDelay;
+
+	// Add jitter (0-25% of delay)
+	const jitter = Math.random() * 0.25 * exponentialDelay;
+
+	// Cap at maxDelay
+	return Math.min(exponentialDelay + jitter, maxDelay);
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry an async generator factory using the same retry policy as retryAsync.
+ */
+export async function* retryStream<T>(
+	createStream: () => AsyncGenerator<T, void, unknown>,
+	options: RetryOptions = {},
+): AsyncGenerator<T, void, unknown> {
+	const { maxRetries = DEFAULT_OPTIONS.maxRetries, onRetryAttempt } = options;
+
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			yield* createStream();
+			return;
+		} catch (error) {
+			const isLastAttempt = attempt === maxRetries;
+			const shouldRetry = !isLastAttempt && isRetriableError(error);
+
+			if (!shouldRetry) {
+				throw error;
+			}
+
+			let delay: number;
+			if (error instanceof RetriableError && error.retryAfterSeconds) {
+				delay = error.retryAfterSeconds * 1000;
+			} else {
+				delay = calculateRetryDelay(attempt, options);
+			}
+
+			if (onRetryAttempt) {
+				onRetryAttempt(attempt + 1, maxRetries, delay, error);
+			}
+
+			await sleep(delay);
+		}
+	}
+
+	throw new Error("Retry logic exhausted without returning or throwing");
+}
+
+/**
+ * Wrap an async function with retry logic
+ */
+export async function retryAsync<T>(
+	fn: () => Promise<T>,
+	options: RetryOptions = {},
+): Promise<T> {
+	const { maxRetries = DEFAULT_OPTIONS.maxRetries, onRetryAttempt } = options;
+
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			return await fn();
+		} catch (error) {
+			const isLastAttempt = attempt === maxRetries;
+			const shouldRetry = !isLastAttempt && isRetriableError(error);
+
+			if (!shouldRetry) {
+				throw error;
+			}
+
+			let delay: number;
+			if (error instanceof RetriableError && error.retryAfterSeconds) {
+				delay = error.retryAfterSeconds * 1000;
+			} else {
+				delay = calculateRetryDelay(attempt, options);
+			}
+
+			if (onRetryAttempt) {
+				onRetryAttempt(attempt + 1, maxRetries, delay, error);
+			}
+
+			await sleep(delay);
+		}
+	}
+
+	// This should never be reached
+	throw new Error("Retry logic exhausted without returning or throwing");
+}

package/src/providers/utils/stream-processor.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from "vitest";
+import { StreamResponseProcessor } from "./stream-processor";
+
+describe("StreamResponseProcessor", () => {
+	it("assembles text, reasoning, tool calls, usage, and completion metadata", () => {
+		const processor = new StreamResponseProcessor();
+
+		processor.process({
+			type: "reasoning",
+			id: "resp_1",
+			reasoning: "thinking...",
+			details: {
+				type: "reasoning.text",
+				text: "step 1",
+				signature: "sig-r",
+				format: "anthropic-claude-v1",
+				index: 0,
+			},
+			redacted_data: "encrypted",
+		});
+		processor.process({
+			type: "text",
+			id: "resp_1",
+			text: "Hello ",
+		});
+		processor.process({
+			type: "text",
+			id: "resp_1",
+			text: "world",
+			signature: "sig-text",
+		});
+		processor.process({
+			type: "tool_calls",
+			id: "resp_1",
+			signature: "sig-tool",
+			tool_call: {
+				call_id: "call_1",
+				function: {
+					id: "tool_1",
+					name: "read_file",
+					arguments: '{"path":"/tmp/a',
+				},
+			},
+		});
+		processor.process({
+			type: "tool_calls",
+			id: "resp_1",
+			tool_call: {
+				function: {
+					id: "tool_1",
+					arguments: '.ts"}',
+				},
+			},
+		});
+		processor.process({
+			type: "usage",
+			id: "resp_1",
+			inputTokens: 10,
+			outputTokens: 20,
+			cacheReadTokens: 5,
+			cacheWriteTokens: 0,
+			thoughtsTokenCount: 3,
+			totalCost: 0.001,
+		});
+		const partial = processor.process({
+			type: "done",
+			id: "resp_1",
+			success: true,
+			incompleteReason: "max_output_tokens",
+		});
+
+		expect(partial.responseId).toBe("resp_1");
+		expect(partial.content[0]).toMatchObject({
+			type: "thinking",
+			thinking: "thinking...",
+			signature: "sig-r",
+		});
+		expect(partial.content[1]).toMatchObject({
+			type: "text",
+			text: "Hello world",
+			signature: "sig-text",
+		});
+		expect(partial.content[2]).toMatchObject({
+			type: "tool_use",
+			id: "tool_1",
+			name: "read_file",
+			input: { path: "/tmp/a.ts" },
+			signature: "sig-tool",
+		});
+
+		const final = processor.finalize();
+		expect(final.responseId).toBe("resp_1");
+		expect(final.incompleteReason).toBe("max_output_tokens");
+		expect(final.usage).toEqual({
+			inputTokens: 10,
+			outputTokens: 20,
+			cacheReadTokens: 5,
+			cacheWriteTokens: 0,
+			thoughtsTokenCount: 3,
+			totalCost: 0.001,
+		});
+		expect(final.content[0]).toMatchObject({
+			type: "thinking",
+			thinking: "thinking...",
+			summary: [
+				{
+					type: "reasoning.text",
+					text: "step 1",
+					signature: "sig-r",
+					format: "anthropic-claude-v1",
+					index: 0,
+				},
+			],
+		});
+		expect(final.content[1]).toEqual({
+			type: "redacted_thinking",
+			data: "encrypted",
+			call_id: "resp_1",
+		});
+		expect(final.content[2]).toMatchObject({
+			type: "text",
+			text: "Hello world",
+			signature: "sig-text",
+			reasoning_details: [
+				{
+					type: "reasoning.text",
+					text: "step 1",
+					signature: "sig-r",
+					format: "anthropic-claude-v1",
+					index: 0,
+				},
+			],
+		});
+		expect(final.content[3]).toMatchObject({
+			type: "tool_use",
+			id: "tool_1",
+			name: "read_file",
+			input: { path: "/tmp/a.ts" },
+			signature: "sig-tool",
+		});
+	});
+
+	it("extracts partial JSON fields while arguments are incomplete", () => {
+		const processor = new StreamResponseProcessor();
+
+		const partial = processor.process({
+			type: "tool_calls",
+			id: "resp_2",
+			tool_call: {
+				call_id: "call_partial",
+				function: {
+					id: "tool_partial",
+					name: "run_command",
+					arguments:
+						'{"command":"echo \\"hi\\"","cwd":"/Users/beatrix/dev/cline-packages',
+				},
+			},
+		});
+
+		expect(partial.content).toEqual([
+			{
+				type: "tool_use",
+				id: "tool_partial",
+				name: "run_command",
+				input: {
+					command: 'echo "hi"',
+					cwd: "/Users/beatrix/dev/cline-packages",
+				},
+				call_id: "call_partial",
+				signature: undefined,
+			},
+		]);
+	});
+
+	it("handles object arguments and reset()", () => {
+		const processor = new StreamResponseProcessor();
+
+		processor.process({
+			type: "tool_calls",
+			id: "resp_3",
+			tool_call: {
+				call_id: "call_obj",
+				function: {
+					id: "tool_obj",
+					name: "edit_file",
+					arguments: {
+						path: "a.ts",
+						content: "x",
+					},
+				},
+			},
+		});
+
+		const finalBeforeReset = processor.finalize();
+		expect(finalBeforeReset.content).toEqual([
+			{
+				type: "tool_use",
+				id: "tool_obj",
+				name: "edit_file",
+				input: { path: "a.ts", content: "x" },
+				call_id: "call_obj",
+				signature: undefined,
+				reasoning_details: undefined,
+			},
+		]);
+
+		processor.reset();
+		expect(processor.finalize()).toEqual({
+			content: [],
+			usage: undefined,
+			responseId: undefined,
+			incompleteReason: undefined,
+		});
+	});
+
+	it("ignores tool call chunks that do not have an id", () => {
+		const processor = new StreamResponseProcessor();
+
+		processor.process({
+			type: "tool_calls",
+			id: "resp_4",
+			tool_call: {
+				function: {
+					name: "ignored",
+					arguments: "{}",
+				},
+			},
+		});
+
+		expect(processor.finalize().content).toEqual([]);
+	});
+});