@schlenkr/ragents 0.1.0

package/packages/ai/src/utils/abort-signals.ts

@@ -0,0 +1,41 @@
+export interface CombinedAbortSignal {
+	signal?: AbortSignal;
+	cleanup: () => void;
+}
+
+export function combineAbortSignals(signals: readonly (AbortSignal | undefined)[]): CombinedAbortSignal {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => signal !== undefined);
+	if (activeSignals.length === 0) {
+		return { cleanup: () => {} };
+	}
+	if (activeSignals.length === 1) {
+		return { signal: activeSignals[0], cleanup: () => {} };
+	}
+
+	const controller = new AbortController();
+	const listeners: Array<{ signal: AbortSignal; listener: () => void }> = [];
+	const abort = (signal: AbortSignal) => {
+		if (!controller.signal.aborted) {
+			controller.abort(signal.reason);
+		}
+	};
+
+	for (const signal of activeSignals) {
+		if (signal.aborted) {
+			abort(signal);
+			break;
+		}
+		const listener = () => abort(signal);
+		signal.addEventListener("abort", listener, { once: true });
+		listeners.push({ signal, listener });
+	}
+
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			for (const { signal, listener } of listeners) {
+				signal.removeEventListener("abort", listener);
+			}
+		},
+	};
+}

package/packages/ai/src/utils/deferred-tools.ts

@@ -0,0 +1,39 @@
+import type { Context, Tool } from "../types.ts";
+
+type ToolNameNormalizer = (name: string) => string;
+
+const identityToolName: ToolNameNormalizer = (name) => name;
+
+/** Split current tools into prefix and transcript-loaded definitions. */
+export function splitDeferredTools(
+	context: Context,
+	enabled: boolean,
+	normalizeName: ToolNameNormalizer = identityToolName,
+): { immediate: Tool[]; deferred: Map<string, Tool> } {
+	const uniqueTools = new Map<string, Tool>();
+	for (const tool of context.tools ?? []) uniqueTools.set(normalizeName(tool.name), tool);
+	if (!enabled) return { immediate: [...uniqueTools.values()], deferred: new Map() };
+
+	const deferredNames = new Set<string>();
+	const usedNames = new Set<string>();
+	for (const message of context.messages) {
+		if (message.role === "assistant") {
+			for (const block of message.content) {
+				if (block.type === "toolCall") usedNames.add(normalizeName(block.name));
+			}
+		} else if (message.role === "toolResult") {
+			for (const name of message.addedToolNames ?? []) {
+				const normalizedName = normalizeName(name);
+				if (!usedNames.has(normalizedName)) deferredNames.add(normalizedName);
+			}
+		}
+	}
+
+	const immediate: Tool[] = [];
+	const deferred = new Map<string, Tool>();
+	for (const [name, tool] of uniqueTools) {
+		if (deferredNames.has(name)) deferred.set(name, tool);
+		else immediate.push(tool);
+	}
+	return { immediate, deferred };
+}

package/packages/ai/src/utils/diagnostics.ts

@@ -0,0 +1,45 @@
+export interface DiagnosticErrorInfo {
+	name?: string;
+	message: string;
+	stack?: string;
+	code?: string | number;
+}
+
+export interface AssistantMessageDiagnostic {
+	type: string;
+	timestamp: number;
+	error?: DiagnosticErrorInfo;
+	details?: Record<string, unknown>;
+}
+
+export function formatThrownValue(value: unknown): string {
+	if (value instanceof Error) return value.message || value.name;
+	if (typeof value === "string") return value;
+	return String(value);
+}
+
+export function extractDiagnosticError(error: unknown): DiagnosticErrorInfo {
+	if (!(error instanceof Error)) return { name: "ThrownValue", message: formatThrownValue(error) };
+	const code = (error as Error & { code?: unknown }).code;
+	return {
+		name: error.name || undefined,
+		message: error.message || error.name,
+		stack: error.stack,
+		code: typeof code === "string" || typeof code === "number" ? code : undefined,
+	};
+}
+
+export function createAssistantMessageDiagnostic(
+	type: string,
+	error: unknown,
+	details?: Record<string, unknown>,
+): AssistantMessageDiagnostic {
+	return { type, timestamp: Date.now(), error: extractDiagnosticError(error), details };
+}
+
+export function appendAssistantMessageDiagnostic<T extends { diagnostics?: AssistantMessageDiagnostic[] }>(
+	message: T,
+	diagnostic: AssistantMessageDiagnostic,
+): void {
+	message.diagnostics = [...(message.diagnostics ?? []), diagnostic];
+}

package/packages/ai/src/utils/error-body.ts

@@ -0,0 +1,129 @@
+// Shared normalization for provider HTTP error objects.
+//
+// Endpoints behind a proxy / gateway may return a non-2xx response whose body
+// the provider SDK cannot fold into `error.message`. The SDK error object still
+// carries the HTTP status and the raw/parsed body, but under SDK-specific field
+// names. Provider catch blocks that read only `error.message` therefore drop
+// the body and surface opaque messages like `"403 status code (no body)"` or
+// collapse to `"Unknown: UnknownError"`.
+//
+// `normalizeProviderError` probes the known SDK field shapes (Mistral,
+// `openai`, `@google/genai`, AWS Bedrock) and returns a struct each provider
+// composes into its display string. The `messageCarriesBody` flag captures the
+// Anthropic / `@google/genai` happy path where the SDK already folded the body
+// into the message, so providers can preserve it without double-printing.
+
+export const MAX_PROVIDER_ERROR_BODY_CHARS = 4000;
+
+export interface NormalizedProviderError {
+	/** HTTP status code, when one could be extracted from the SDK error object. */
+	status?: number;
+	/** Raw HTTP body reason, already trimmed and truncated to the cap. */
+	body?: string;
+	/** `error.message`, or `safeJsonStringify(error)` for a non-`Error` throw. */
+	message: string;
+	/** True when `message` already contains the body (no separate body to add). */
+	messageCarriesBody: boolean;
+}
+
+type SdkErrorShape = Error & {
+	statusCode?: unknown;
+	status?: unknown;
+	body?: unknown;
+	responseBody?: unknown;
+	error?: unknown;
+	$metadata?: { httpStatusCode?: unknown };
+	$response?: { statusCode?: unknown; body?: unknown };
+};
+
+export function normalizeProviderError(error: unknown): NormalizedProviderError {
+	if (!(error instanceof Error)) {
+		return { message: safeJsonStringify(error), messageCarriesBody: false };
+	}
+
+	const sdkError = error as SdkErrorShape;
+	const status = extractStatus(sdkError);
+	const body = extractBody(sdkError);
+	const messageCarriesBody = body === undefined || error.message.includes(body);
+
+	return {
+		status,
+		body,
+		message: error.message,
+		messageCarriesBody,
+	} satisfies NormalizedProviderError;
+}
+
+/**
+ * Probe the HTTP status, first numeric hit wins, in SDK-field order:
+ * `statusCode` (Mistral) → `status` (`openai`, `@google/genai`) →
+ * `$metadata.httpStatusCode` (Bedrock) → `$response.statusCode` (Bedrock).
+ */
+function extractStatus(error: SdkErrorShape): number | undefined {
+	if (typeof error.statusCode === "number") return error.statusCode;
+	if (typeof error.status === "number") return error.status;
+	if (typeof error.$metadata?.httpStatusCode === "number") return error.$metadata.httpStatusCode;
+	if (typeof error.$response?.statusCode === "number") return error.$response.statusCode;
+	return undefined;
+}
+
+/**
+ * Probe the raw body reason, first usable hit wins, in SDK-field order:
+ * `body` string (Mistral) → `error` parsed JSON body object (`openai` SDK's
+ * `this.error`) → `$response.body` (Bedrock). Empty objects are treated as no
+ * body so an empty parsed body does not surface as `"{}"`. The chosen body is
+ * truncated to the cap.
+ */
+function extractBody(error: SdkErrorShape): string | undefined {
+	const bodyText = pickBodyText(error);
+	if (bodyText === undefined) return undefined;
+	const trimmed = bodyText.trim();
+	if (trimmed.length === 0) return undefined;
+	return truncateErrorText(trimmed, MAX_PROVIDER_ERROR_BODY_CHARS);
+}
+
+function pickBodyText(error: SdkErrorShape): string | undefined {
+	if (typeof error.responseBody === "string") return error.responseBody;
+	if (typeof error.body === "string") return error.body;
+	if (isNonEmptyObject(error.error)) return safeJsonStringify(error.error);
+	const responseBody = error.$response?.body;
+	if (typeof responseBody === "string") return responseBody;
+	if (isNonEmptyObject(responseBody)) return safeJsonStringify(responseBody);
+	return undefined;
+}
+
+function isNonEmptyObject(value: unknown): boolean {
+	return typeof value === "object" && value !== null && Object.keys(value).length > 0;
+}
+
+/**
+ * Compose a display string from a normalized error. When the message already
+ * carries the body (Anthropic / `@google/genai` happy path) or no body/status
+ * was extracted, the message is returned unchanged. Otherwise the status and
+ * body are surfaced, with an optional provider prefix.
+ *
+ * - no prefix: `"<status>: <body>"`
+ * - prefix:    `"<prefix> (<status>): <body>"`
+ */
+export function formatProviderError(norm: NormalizedProviderError, prefix?: string): string {
+	if (norm.messageCarriesBody || norm.status === undefined || norm.body === undefined) {
+		return prefix !== undefined && norm.status !== undefined
+			? `${prefix} (${norm.status}): ${norm.message}`
+			: norm.message;
+	}
+	return prefix !== undefined ? `${prefix} (${norm.status}): ${norm.body}` : `${norm.status}: ${norm.body}`;
+}
+
+export function truncateErrorText(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}... [truncated ${text.length - maxChars} chars]`;
+}
+
+export function safeJsonStringify(value: unknown): string {
+	try {
+		const serialized = JSON.stringify(value);
+		return serialized === undefined ? String(value) : serialized;
+	} catch {
+		return String(value);
+	}
+}

package/packages/ai/src/utils/estimate.ts

@@ -0,0 +1,146 @@
+import type { AssistantMessage, Context, Message, Tool, Usage, UserContent } from "../types.ts";
+
+export interface ContextUsageEstimate {
+	/** Estimated total context tokens. */
+	tokens: number;
+	/** Tokens reported by the most recent applicable assistant usage block. */
+	usageTokens: number;
+	/** Estimated tokens after the most recent applicable assistant usage block. */
+	trailingTokens: number;
+	/** Index of the applicable message that provided usage, or null when none exists. */
+	lastUsageIndex: number | null;
+}
+
+const CHARS_PER_TOKEN = 4;
+const ESTIMATED_IMAGE_CHARS = 4800;
+
+export function calculateContextTokens(usage: Usage): number {
+	return usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+
+function safeJsonStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? "undefined";
+	} catch {
+		return "[unserializable]";
+	}
+}
+
+function estimateTextAndImageContentChars(content: string | UserContent[]): number {
+	if (typeof content === "string") return content.length;
+
+	let chars = 0;
+	for (const block of content) {
+		chars += block.type === "text" ? block.text.length
+			: block.type === "image" ? ESTIMATED_IMAGE_CHARS : Math.max(ESTIMATED_IMAGE_CHARS, block.data.length);
+	}
+	return chars;
+}
+
+export function estimateTextTokens(text: string): number {
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function estimateTextAndImageContentTokens(content: string | UserContent[]): number {
+	return Math.ceil(estimateTextAndImageContentChars(content) / CHARS_PER_TOKEN);
+}
+
+export function estimateMessageTokens(message: Message): number {
+	let chars = 0;
+
+	if (message.role === "user") return estimateTextAndImageContentTokens(message.content);
+	if (message.role === "toolResult") return estimateTextAndImageContentTokens(message.content);
+
+	for (const block of message.content) {
+		if (block.type === "text") {
+			chars += block.text.length;
+		} else if (block.type === "thinking") {
+			chars += block.thinking.length;
+		} else {
+			chars += block.name.length + safeJsonStringify(block.arguments).length;
+		}
+	}
+	return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+function getLastAssistantUsageInfo(messages: readonly Message[]): { usage: Usage; index: number } | undefined {
+	let latestPrefixTimestamp = Number.NEGATIVE_INFINITY;
+	let usageInfo: { usage: Usage; index: number } | undefined;
+
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i];
+		if (message.role === "assistant") {
+			const assistant = message as AssistantMessage;
+			// A newer prefix message was inserted after this response (for example, a
+			// compaction summary), so its usage cannot describe the current prefix.
+			const usageAppliesToPrefix = assistant.timestamp >= latestPrefixTimestamp;
+			if (
+				usageAppliesToPrefix &&
+				assistant.stopReason !== "aborted" &&
+				assistant.stopReason !== "error" &&
+				calculateContextTokens(assistant.usage) > 0
+			) {
+				usageInfo = { usage: assistant.usage, index: i };
+			}
+		}
+		latestPrefixTimestamp = Math.max(latestPrefixTimestamp, message.timestamp);
+	}
+
+	return usageInfo;
+}
+
+function estimateMessages(messages: readonly Message[]): ContextUsageEstimate {
+	const usageInfo = getLastAssistantUsageInfo(messages);
+	if (usageInfo) {
+		const usageTokens = calculateContextTokens(usageInfo.usage);
+		let trailingTokens = 0;
+		for (let i = usageInfo.index + 1; i < messages.length; i++) {
+			trailingTokens += estimateMessageTokens(messages[i]);
+		}
+		return { tokens: usageTokens + trailingTokens, usageTokens, trailingTokens, lastUsageIndex: usageInfo.index };
+	}
+
+	let tokens = 0;
+	for (const message of messages) tokens += estimateMessageTokens(message);
+	return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
+}
+
+function estimateToolsTokens(tools: readonly Tool[] | undefined): number {
+	if (!tools || tools.length === 0) return 0;
+	return estimateTextTokens(safeJsonStringify(tools));
+}
+
+function isMessageArray(value: Context | readonly Message[]): value is readonly Message[] {
+	return Array.isArray(value);
+}
+
+export function estimateContextTokens(context: Context | readonly Message[]): ContextUsageEstimate {
+	if (isMessageArray(context)) return estimateMessages(context);
+
+	const estimate = estimateMessages(context.messages);
+	if (estimate.lastUsageIndex !== null) {
+		const addedNames = new Set(
+			context.messages
+				.slice(estimate.lastUsageIndex + 1)
+				.filter((message) => message.role === "toolResult")
+				.flatMap((message) => message.addedToolNames ?? []),
+		);
+		const addedToolTokens = estimateToolsTokens(context.tools?.filter((tool) => addedNames.has(tool.name)));
+		return {
+			tokens: estimate.tokens + addedToolTokens,
+			usageTokens: estimate.usageTokens,
+			trailingTokens: estimate.trailingTokens + addedToolTokens,
+			lastUsageIndex: estimate.lastUsageIndex,
+		};
+	}
+
+	const prefixTokens =
+		(context.systemPrompt ? estimateTextTokens(context.systemPrompt) : 0) + estimateToolsTokens(context.tools);
+
+	return {
+		tokens: estimate.tokens + prefixTokens,
+		usageTokens: estimate.usageTokens,
+		trailingTokens: estimate.trailingTokens + prefixTokens,
+		lastUsageIndex: estimate.lastUsageIndex,
+	};
+}

package/packages/ai/src/utils/event-stream.ts

@@ -0,0 +1,88 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types.ts";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	private queue: T[] = [];
+	private waiting: ((value: IteratorResult<T>) => void)[] = [];
+	private done = false;
+	private finalResultPromise: Promise<R>;
+	private resolveFinalResult!: (result: R) => void;
+	private isComplete: (event: T) => boolean;
+	private extractResult: (event: T) => R;
+
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R) {
+		this.isComplete = isComplete;
+		this.extractResult = extractResult;
+		this.finalResultPromise = new Promise((resolve) => {
+			this.resolveFinalResult = resolve;
+		});
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		// Deliver to waiting consumer or queue it
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	end(result?: R): void {
+		this.done = true;
+		if (result !== undefined) {
+			this.resolveFinalResult(result);
+		}
+		// Notify all waiting consumers that we're done
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter({ value: undefined as any, done: true });
+		}
+	}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		while (true) {
+			if (this.queue.length > 0) {
+				yield this.queue.shift()!;
+			} else if (this.done) {
+				return;
+			} else {
+				const result = await new Promise<IteratorResult<T>>((resolve) => this.waiting.push(resolve));
+				if (result.done) return;
+				yield result.value;
+			}
+		}
+	}
+
+	result(): Promise<R> {
+		return this.finalResultPromise;
+	}
+}
+
+export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+	constructor() {
+		super(
+			(event) => event.type === "done" || event.type === "error",
+			(event) => {
+				if (event.type === "done") {
+					return event.message;
+				} else if (event.type === "error") {
+					return event.error;
+				}
+				throw new Error("Unexpected event type for final result");
+			},
+		);
+	}
+}
+
+/** Factory function for AssistantMessageEventStream (for use in extensions) */
+export function createAssistantMessageEventStream(): AssistantMessageEventStream {
+	return new AssistantMessageEventStream();
+}

package/packages/ai/src/utils/hash.ts

@@ -0,0 +1,13 @@
+/** Fast deterministic hash to shorten long strings */
+export function shortHash(str: string): string {
+	let h1 = 0xdeadbeef;
+	let h2 = 0x41c6ce57;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+	h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+	return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}

package/packages/ai/src/utils/headers.ts

@@ -0,0 +1,18 @@
+import type { ProviderHeaders } from "../types.ts";
+
+export function headersToRecord(headers: Headers): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const [key, value] of headers.entries()) {
+		result[key] = value;
+	}
+	return result;
+}
+
+export function providerHeadersToRecord(headers: ProviderHeaders | undefined): Record<string, string> | undefined {
+	if (!headers) return undefined;
+	const result: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value !== null) result[key] = value;
+	}
+	return Object.keys(result).length > 0 ? result : undefined;
+}

package/packages/ai/src/utils/json-parse.ts

@@ -0,0 +1,124 @@
+import { parse as partialParse } from "partial-json";
+
+const VALID_JSON_ESCAPES = new Set(['"', "\\", "/", "b", "f", "n", "r", "t", "u"]);
+
+function isControlCharacter(char: string): boolean {
+	const codePoint = char.codePointAt(0);
+	return codePoint !== undefined && codePoint >= 0x00 && codePoint <= 0x1f;
+}
+
+function escapeControlCharacter(char: string): string {
+	switch (char) {
+		case "\b":
+			return "\\b";
+		case "\f":
+			return "\\f";
+		case "\n":
+			return "\\n";
+		case "\r":
+			return "\\r";
+		case "\t":
+			return "\\t";
+		default:
+			return `\\u${char.codePointAt(0)?.toString(16).padStart(4, "0") ?? "0000"}`;
+	}
+}
+
+/**
+ * Repairs malformed JSON string literals by:
+ * - escaping raw control characters inside strings
+ * - doubling backslashes before invalid escape characters
+ */
+export function repairJson(json: string): string {
+	let repaired = "";
+	let inString = false;
+
+	for (let index = 0; index < json.length; index++) {
+		const char = json[index];
+
+		if (!inString) {
+			repaired += char;
+			if (char === '"') {
+				inString = true;
+			}
+			continue;
+		}
+
+		if (char === '"') {
+			repaired += char;
+			inString = false;
+			continue;
+		}
+
+		if (char === "\\") {
+			const nextChar = json[index + 1];
+			if (nextChar === undefined) {
+				repaired += "\\\\";
+				continue;
+			}
+
+			if (nextChar === "u") {
+				const unicodeDigits = json.slice(index + 2, index + 6);
+				if (/^[0-9a-fA-F]{4}$/.test(unicodeDigits)) {
+					repaired += `\\u${unicodeDigits}`;
+					index += 5;
+					continue;
+				}
+			}
+
+			if (VALID_JSON_ESCAPES.has(nextChar)) {
+				repaired += `\\${nextChar}`;
+				index += 1;
+				continue;
+			}
+
+			repaired += "\\\\";
+			continue;
+		}
+
+		repaired += isControlCharacter(char) ? escapeControlCharacter(char) : char;
+	}
+
+	return repaired;
+}
+
+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 {
+	if (!partialJson || partialJson.trim() === "") {
+		return {} as T;
+	}
+
+	try {
+		return parseJsonWithRepair<T>(partialJson);
+	} catch {
+		try {
+			const result = partialParse(partialJson);
+			return (result ?? {}) as T;
+		} catch {
+			try {
+				const result = partialParse(repairJson(partialJson));
+				return (result ?? {}) as T;
+			} catch {
+				return {} as T;
+			}
+		}
+	}
+}