@od-oneapp/ai-platform 0.1.0

package/dist/error-handling-DNVkm6RY.mjs

@@ -0,0 +1,1334 @@
+//#region src/grounding/retrieval/in-memory-store.ts
+/**
+* Simple in-memory vector store using cosine similarity
+*
+* @example
+* ```ts
+* const store = new InMemoryVectorStore(embedFn);
+*
+* await store.add([
+*   { id: "1", content: "AI is transforming industries" },
+*   { id: "2", content: "Machine learning requires data" },
+* ]);
+*
+* const results = await store.search("artificial intelligence", 5);
+* ```
+*/
+var InMemoryVectorStore = class {
+	documents = /* @__PURE__ */ new Map();
+	embeddings = /* @__PURE__ */ new Map();
+	constructor(embedFn, options = {}) {
+		this.embedFn = embedFn;
+		this.options = options;
+	}
+	async add(sources) {
+		for (const source of sources) {
+			this.documents.set(source.id, source);
+			const embedding = await this.embedFn(source.content);
+			this.embeddings.set(source.id, embedding);
+		}
+	}
+	async search(query, limit = 10) {
+		const queryEmbedding = await this.embedFn(query);
+		const scores = [];
+		for (const [id, embedding] of this.embeddings) {
+			const score = cosineSimilarity(queryEmbedding, embedding);
+			scores.push({
+				id,
+				score
+			});
+		}
+		scores.sort((a, b) => b.score - a.score);
+		return scores.slice(0, limit).flatMap(({ id, score }) => {
+			const document = this.documents.get(id);
+			if (!document) return [];
+			return [{
+				...document,
+				score
+			}];
+		});
+	}
+	async delete(ids) {
+		for (const id of ids) {
+			this.documents.delete(id);
+			this.embeddings.delete(id);
+		}
+	}
+	/**
+	* Get document count
+	*/
+	size() {
+		return this.documents.size;
+	}
+	/**
+	* Clear all documents
+	*/
+	clear() {
+		this.documents.clear();
+		this.embeddings.clear();
+	}
+};
+/**
+* Calculate cosine similarity between two vectors
+*/
+function cosineSimilarity(a, b) {
+	if (a.length !== b.length) throw new Error("Vectors must have the same length");
+	let dotProduct = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < a.length; i++) {
+		const aValue = a[i] ?? 0;
+		const bValue = b[i] ?? 0;
+		dotProduct += aValue * bValue;
+		normA += aValue * aValue;
+		normB += bValue * bValue;
+	}
+	const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+	if (magnitude === 0) return 0;
+	return dotProduct / magnitude;
+}
+
+//#endregion
+//#region src/grounding/sources/index.ts
+/**
+* Creates a source registry for managing grounding sources.
+*
+* @example
+* ```typescript
+* const registry = createSourceRegistry({ maxSources: 1000 });
+*
+* registry.add({
+*   id: 'wiki-1',
+*   content: 'Climate change refers to...',
+*   url: 'https://example.com/climate',
+*   score: 0.85
+* });
+*
+* const source = registry.get('wiki-1');
+* console.log(source?.useCount); // 0
+*
+* registry.recordUsage('wiki-1');
+* console.log(registry.get('wiki-1')?.useCount); // 1
+* ```
+*/
+function createSourceRegistry(config = {}) {
+	const { maxSources = 1e4, autoDeduplicate = false, deduplicationStrategy = "id" } = config;
+	const sources = /* @__PURE__ */ new Map();
+	function add(source) {
+		if (sources.size >= maxSources) {
+			const oldestId = sources.keys().next().value;
+			if (oldestId) sources.delete(oldestId);
+		}
+		if (autoDeduplicate) {
+			if (checkDuplicate(source, Array.from(sources.values()), deduplicationStrategy)) return;
+		}
+		const enhanced = {
+			...source,
+			addedAt: /* @__PURE__ */ new Date(),
+			lastAccessedAt: /* @__PURE__ */ new Date(),
+			useCount: 0,
+			sourceType: inferSourceType(source)
+		};
+		sources.set(source.id, enhanced);
+	}
+	function addMany(newSources) {
+		for (const source of newSources) add(source);
+	}
+	function get(id) {
+		const source = sources.get(id);
+		if (source) source.lastAccessedAt = /* @__PURE__ */ new Date();
+		return source;
+	}
+	function getAll() {
+		return Array.from(sources.values());
+	}
+	function remove(id) {
+		return sources.delete(id);
+	}
+	function clear() {
+		sources.clear();
+	}
+	function has(id) {
+		return sources.has(id);
+	}
+	function size() {
+		return sources.size;
+	}
+	function search(query, limit = 10) {
+		const results = [];
+		for (const source of sources.values()) {
+			const similarity = computeTextSimilarity(query, source.content);
+			if (similarity > .1) results.push({
+				source,
+				similarity
+			});
+		}
+		return results.sort((a, b) => b.similarity - a.similarity).slice(0, limit).map((r) => r.source);
+	}
+	function recordUsage(id) {
+		const source = sources.get(id);
+		if (source) {
+			source.useCount = (source.useCount ?? 0) + 1;
+			source.lastAccessedAt = /* @__PURE__ */ new Date();
+		}
+	}
+	return {
+		add,
+		addMany,
+		get,
+		getAll,
+		remove,
+		clear,
+		has,
+		size,
+		search,
+		recordUsage
+	};
+}
+/**
+* Validate a single grounding source.
+*
+* @example
+* ```typescript
+* const result = validateSource(source, { requireUrl: true, minContentLength: 50 });
+* if (!result.valid) {
+*   console.error('Validation errors:', result.errors);
+* }
+* ```
+*/
+function validateSource(source, options = {}) {
+	const { requireUrl = false, requireTitle = false, minContentLength = 1, maxContentLength = 1e5, requireScore = false } = options;
+	const errors = [];
+	const warnings = [];
+	if (!source.id || typeof source.id !== "string") errors.push("Source must have a valid string id");
+	if (!source.content || typeof source.content !== "string") errors.push("Source must have valid string content");
+	else {
+		if (source.content.length < minContentLength) errors.push(`Content must be at least ${minContentLength} characters`);
+		if (source.content.length > maxContentLength) errors.push(`Content must not exceed ${maxContentLength} characters`);
+	}
+	if (requireUrl && !source.url) errors.push("URL is required");
+	if (requireTitle && !source.title) errors.push("Title is required");
+	if (requireScore && (source.score === void 0 || source.score === null)) errors.push("Score is required");
+	if (source.score !== void 0 && (source.score < 0 || source.score > 1)) warnings.push("score should be between 0 and 1");
+	if (source.url && !isValidUrl(source.url)) warnings.push("URL appears to be invalid");
+	return {
+		valid: errors.length === 0,
+		sourceId: source.id ?? "unknown",
+		errors,
+		warnings
+	};
+}
+/**
+* Validate multiple sources.
+*
+* @example
+* ```typescript
+* const { valid, invalid, results } = validateSources(sources);
+* console.log(`${valid.length} valid, ${invalid.length} invalid`);
+* ```
+*/
+function validateSources(sources, options = {}) {
+	const results = sources.map((s) => validateSource(s, options));
+	const valid = [];
+	const invalid = [];
+	for (let i = 0; i < sources.length; i++) {
+		const result = results[i];
+		const source = sources[i];
+		if (!result || !source) continue;
+		if (result.valid) valid.push(source);
+		else invalid.push(source);
+	}
+	return {
+		valid,
+		invalid,
+		results
+	};
+}
+/**
+* Remove duplicate sources based on the specified strategy.
+*
+* @example
+* ```typescript
+* // By ID (exact match)
+* const unique = deduplicateSources(sources, { strategy: 'id' });
+*
+* // By content similarity
+* const unique = deduplicateSources(sources, {
+*   strategy: 'content',
+*   similarityThreshold: 0.9,
+*   keepStrategy: 'highest-score'
+* });
+* ```
+*/
+function deduplicateSources(sources, options = {}) {
+	const { strategy = "id", similarityThreshold = .9, keepStrategy = "first" } = options;
+	if (sources.length === 0) return [];
+	switch (strategy) {
+		case "id": return deduplicateById(sources, keepStrategy);
+		case "url": return deduplicateByUrl(sources, keepStrategy);
+		case "content": return deduplicateByContent(sources, similarityThreshold, keepStrategy);
+		case "hybrid": return deduplicateByContent(deduplicateByUrl(sources, keepStrategy), similarityThreshold, keepStrategy);
+		default: return sources;
+	}
+}
+function deduplicateById(sources, keepStrategy) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const existing = seen.get(source.id);
+		if (!existing) seen.set(source.id, source);
+		else if (keepStrategy === "highest-score") {
+			if ((source.score ?? 0) > (existing.score ?? 0)) seen.set(source.id, source);
+		}
+	}
+	return Array.from(seen.values());
+}
+function deduplicateByUrl(sources, keepStrategy) {
+	const seen = /* @__PURE__ */ new Map();
+	const noUrl = [];
+	for (const source of sources) {
+		if (!source.url) {
+			noUrl.push(source);
+			continue;
+		}
+		const normalizedUrl = normalizeUrl(source.url);
+		const existing = seen.get(normalizedUrl);
+		if (!existing) seen.set(normalizedUrl, source);
+		else if (keepStrategy === "highest-score") {
+			if ((source.score ?? 0) > (existing.score ?? 0)) seen.set(normalizedUrl, source);
+		}
+	}
+	return [...Array.from(seen.values()), ...noUrl];
+}
+function deduplicateByContent(sources, threshold, keepStrategy) {
+	const result = [];
+	for (const source of sources) {
+		let isDuplicate = false;
+		let duplicateIndex = -1;
+		for (let i = 0; i < result.length; i++) {
+			const existing = result[i];
+			if (!existing) continue;
+			if (computeTextSimilarity(source.content, existing.content) >= threshold) {
+				isDuplicate = true;
+				duplicateIndex = i;
+				break;
+			}
+		}
+		if (!isDuplicate) result.push(source);
+		else if (keepStrategy === "highest-score" && duplicateIndex >= 0) {
+			const current = result[duplicateIndex];
+			if (current && (source.score ?? 0) > (current.score ?? 0)) result[duplicateIndex] = source;
+		}
+	}
+	return result;
+}
+/**
+* Merge duplicate sources, combining their metadata.
+*
+* @example
+* ```typescript
+* const merged = mergeSources(sources, { strategy: 'url' });
+* ```
+*/
+function mergeSources(sources, options = {}) {
+	const { strategy = "id" } = options;
+	const groups = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		let key;
+		switch (strategy) {
+			case "url":
+				key = source.url ? normalizeUrl(source.url) : source.id;
+				break;
+			case "content":
+				key = hashContent(source.content);
+				break;
+			case "hybrid":
+				key = `${source.url ? normalizeUrl(source.url) : source.id}:${hashContent(source.content)}`;
+				break;
+			default: key = source.id;
+		}
+		const group = groups.get(key) ?? [];
+		group.push(source);
+		groups.set(key, group);
+	}
+	return Array.from(groups.values()).filter((group) => group.length > 0).map((group) => {
+		const first = group[0];
+		if (group.length === 1) return first;
+		return group.reduce((acc, s) => {
+			return {
+				...acc,
+				score: Math.max(acc.score ?? 0, s.score ?? 0),
+				metadata: {
+					...acc.metadata,
+					...s.metadata
+				}
+			};
+		}, first);
+	});
+}
+/**
+* Filter sources by relevance score.
+*
+* @example
+* ```typescript
+* const topSources = filterByScore(sources, { minScore: 0.7, limit: 5 });
+* ```
+*/
+function filterByScore(sources, options = {}) {
+	const { minScore = 0, maxScore = 1, limit } = options;
+	let filtered = sources.filter((s) => {
+		const score = s.score ?? 0;
+		return score >= minScore && score <= maxScore;
+	});
+	filtered.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+	if (limit && limit > 0) filtered = filtered.slice(0, limit);
+	return filtered;
+}
+/**
+* Filter sources by metadata fields.
+*
+* @example
+* ```typescript
+* const filtered = filterByMetadata(sources, {
+*   requiredFields: ['author', 'date'],
+*   matchValues: { category: 'science' }
+* });
+* ```
+*/
+function filterByMetadata(sources, options = {}) {
+	const { requiredFields = [], matchValues = {} } = options;
+	return sources.filter((source) => {
+		const metadata = source.metadata ?? {};
+		for (const field of requiredFields) if (!(field in metadata)) return false;
+		for (const [key, value] of Object.entries(matchValues)) if (metadata[key] !== value) return false;
+		return true;
+	});
+}
+/**
+* Select top N sources, optionally with diversity.
+*
+* @example
+* ```typescript
+* const top = selectTopSources(sources, 5, { diversify: true });
+* ```
+*/
+function selectTopSources(sources, limit, options = {}) {
+	const { diversify = false, diversityThreshold = .7 } = options;
+	const sorted = [...sources].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+	if (!diversify) return sorted.slice(0, limit);
+	const selected = [];
+	for (const candidate of sorted) {
+		if (selected.length >= limit) break;
+		if (!selected.some((s) => computeTextSimilarity(candidate.content, s.content) > diversityThreshold)) selected.push(candidate);
+	}
+	return selected;
+}
+/**
+* Group sources by a metadata field or custom function.
+*
+* @example
+* ```typescript
+* const byCategory = groupSources(sources, s => s.metadata?.category ?? 'other');
+* ```
+*/
+function groupSources(sources, keyFn) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const key = keyFn(source);
+		const group = groups.get(key) ?? [];
+		group.push(source);
+		groups.set(key, group);
+	}
+	return groups;
+}
+/**
+* Format sources as a bibliography string.
+*
+* @example
+* ```typescript
+* const bib = formatAsBibliography(sources, { style: 'apa' });
+* console.log(bib);
+* // [1] Author. Title. URL
+* // [2] Author. Title. URL
+* ```
+*/
+function formatAsBibliography(sources, options = {}) {
+	const { style = "numbered" } = options;
+	return sources.map((source, index) => {
+		const title = source.title ?? "Untitled";
+		const url = source.url ?? "";
+		switch (style) {
+			case "apa": return `${source.metadata?.author ?? "Unknown"} (${source.metadata?.year ?? "n.d."}). ${title}. ${url}`;
+			case "simple": return `${title}${url ? ` - ${url}` : ""}`;
+			default: {
+				const author = source.metadata?.author;
+				const authorPrefix = typeof author === "string" && author.trim().length > 0 ? `${author.trim()}. ` : "";
+				return `[${index + 1}] ${authorPrefix}${title}${url ? `. ${url}` : ""}`;
+			}
+		}
+	}).join("\n");
+}
+/**
+* Format sources as inline citations.
+*
+* @example
+* ```typescript
+* const citations = formatAsInlineCitations(sources);
+* // Returns: "[1], [2], [3]"
+* ```
+*/
+function formatAsInlineCitations(sources, options = {}) {
+	const { separator = ", ", format = "numbered" } = options;
+	return sources.map((source, index) => {
+		switch (format) {
+			case "id": return `[${source.id}]`;
+			case "title": return `[${source.title ?? source.id}]`;
+			default: return `[${index + 1}]`;
+		}
+	}).join(separator);
+}
+/**
+* Convert sources to context string for LLM prompts.
+*
+* @example
+* ```typescript
+* const context = sourcesToContext(sources, { includeMetadata: true });
+* ```
+*/
+function sourcesToContext(sources, options = {}) {
+	const { includeMetadata = false, includeScore = false, maxLength = 5e4, separator = "\n\n---\n\n" } = options;
+	let totalLength = 0;
+	const parts = [];
+	for (const source of sources) {
+		let part = "";
+		if (source.title) part += `# ${source.title}\n`;
+		if (includeScore && source.score !== void 0) part += `Relevance: ${(source.score * 100).toFixed(0)}%\n`;
+		if (source.url) part += `Source: ${source.url}\n`;
+		if (includeMetadata && source.metadata) {
+			const meta = Object.entries(source.metadata).map(([k, v]) => `${k}: ${v}`).join(", ");
+			part += `Metadata: ${meta}\n`;
+		}
+		part += `\n${source.content}`;
+		if (totalLength + part.length > maxLength) {
+			const remaining = maxLength - totalLength;
+			if (remaining > 100) parts.push(`${part.slice(0, remaining)}...`);
+			break;
+		}
+		parts.push(part);
+		totalLength += part.length + separator.length;
+	}
+	return parts.join(separator);
+}
+function computeTextSimilarity(text1, text2) {
+	const words1 = new Set(tokenize(text1));
+	const words2 = new Set(tokenize(text2));
+	if (words1.size === 0 || words2.size === 0) return 0;
+	let intersection = 0;
+	for (const word of words1) if (words2.has(word)) intersection++;
+	const union = words1.size + words2.size - intersection;
+	return union > 0 ? intersection / union : 0;
+}
+function tokenize(text) {
+	return text.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 2);
+}
+function isValidUrl(url) {
+	try {
+		new URL(url);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function normalizeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.protocol}//${parsed.host.toLowerCase()}${parsed.pathname.replace(/\/$/, "")}`;
+	} catch {
+		return url.toLowerCase();
+	}
+}
+function hashContent(content) {
+	let hash = 5381;
+	for (let i = 0; i < content.length; i++) {
+		const code = content.charCodeAt(i);
+		hash = hash * 33 ^ code;
+	}
+	return `content-${hash >>> 0}`;
+}
+function inferSourceType(source) {
+	if (!source.url) return "unknown";
+	const url = source.url.toLowerCase();
+	if (url.includes("api.") || url.includes("/api/")) return "api";
+	if (url.includes(".pdf") || url.includes("/doc")) return "document";
+	if (url.includes("database") || url.includes("db.")) return "database";
+	if (url.startsWith("http")) return "webpage";
+	return "unknown";
+}
+function checkDuplicate(source, existing, strategy) {
+	switch (strategy) {
+		case "id": return existing.some((e) => e.id === source.id);
+		case "url":
+			if (!source.url) return false;
+			const normalizedUrl = normalizeUrl(source.url);
+			return existing.some((e) => e.url && normalizeUrl(e.url) === normalizedUrl);
+		case "content": return existing.some((e) => computeTextSimilarity(source.content, e.content) > .9);
+		case "hybrid": {
+			const idMatch = existing.some((e) => e.id === source.id);
+			const sourceUrl = source.url;
+			const urlMatch = sourceUrl ? existing.some((e) => e.url && normalizeUrl(e.url) === normalizeUrl(sourceUrl)) : false;
+			const contentMatch = existing.some((e) => computeTextSimilarity(source.content, e.content) > .9);
+			return idMatch || urlMatch || contentMatch;
+		}
+		default: return false;
+	}
+}
+
+//#endregion
+//#region src/grounding/context-engineering/tool-masking.ts
+/**
+* Creates a tool masker with rules.
+*
+* @param rules - Masking rules
+* @returns Tool masker function
+*
+* @example
+* ```ts
+* const maskTools = createToolMasker([
+*   {
+*     name: 'hide-admin-tools',
+*     toolPatterns: ['admin*', 'delete*'],
+*     condition: (ctx) => !ctx.roles?.includes('admin'),
+*     action: 'hide',
+*   },
+*   {
+*     name: 'limit-iterations',
+*     toolPatterns: ['*'],
+*     condition: (ctx) => (ctx.iteration ?? 0) > 5,
+*     action: 'disable',
+*   },
+* ]);
+*
+* const result = maskTools(allTools, { userId: 'user-1', roles: ['user'] });
+* ```
+*/
+function createToolMasker(rules) {
+	return function maskTools(tools, context) {
+		const result = {
+			tools: { ...tools },
+			activeTools: Object.keys(tools),
+			hidden: [],
+			disabled: [],
+			requiresApproval: [],
+			appliedRules: []
+		};
+		outer: for (const toolName of Object.keys(tools)) for (const rule of rules) {
+			if (!matchesPattern(toolName, rule.toolPatterns)) continue;
+			if (!rule.condition(context)) continue;
+			result.appliedRules.push(`${rule.name}:${toolName}`);
+			switch (rule.action) {
+				case "hide":
+					delete result.tools[toolName];
+					result.activeTools = result.activeTools.filter((t) => t !== toolName);
+					result.hidden.push(toolName);
+					continue outer;
+				case "disable":
+					result.activeTools = result.activeTools.filter((t) => t !== toolName);
+					result.disabled.push(toolName);
+					break;
+				case "require-approval":
+					result.requiresApproval.push(toolName);
+					break;
+			}
+		}
+		return result;
+	};
+}
+/**
+* Checks if a tool name matches any of the patterns.
+*/
+function matchesPattern(toolName, patterns) {
+	return patterns.some((pattern) => {
+		if (pattern === "*") return true;
+		if (pattern.endsWith("*")) return toolName.startsWith(pattern.slice(0, -1));
+		if (pattern.startsWith("*")) return toolName.endsWith(pattern.slice(1));
+		return toolName === pattern;
+	});
+}
+/**
+* Pre-built masking rules.
+*/
+const MaskingRules = {
+	limitIterations: (maxIterations, toolPatterns = ["*"]) => ({
+		name: "limit-iterations",
+		toolPatterns,
+		condition: (ctx) => (ctx.iteration ?? 0) >= maxIterations,
+		action: "hide"
+	}),
+	requireRole: (role, toolPatterns) => ({
+		name: `require-role-${role}`,
+		toolPatterns,
+		condition: (ctx) => !ctx.roles?.includes(role),
+		action: "hide"
+	}),
+	preventRepeated: (toolPatterns, maxCalls = 1) => ({
+		name: "prevent-repeated",
+		toolPatterns,
+		condition: (ctx) => {
+			const calls = ctx.previousToolCalls ?? [];
+			for (const pattern of toolPatterns) if (calls.filter((c) => matchesPattern(c, [pattern])).length >= maxCalls) return true;
+			return false;
+		},
+		action: "hide"
+	}),
+	requireApproval: (toolPatterns) => ({
+		name: "require-approval",
+		toolPatterns,
+		condition: () => true,
+		action: "require-approval"
+	})
+};
+/**
+* Creates progressive tool disclosure.
+* Reveals tools based on conversation progress.
+*
+* @param stages - Tool revelation stages
+* @returns Tool masker
+*/
+function createProgressiveDisclosure(stages) {
+	const sortedStages = [...stages].sort((a, b) => a.turn - b.turn);
+	return (tools, context) => {
+		const currentTurn = context.turn ?? 0;
+		const availableTools = /* @__PURE__ */ new Set();
+		for (const stage of sortedStages) if (stage.turn <= currentTurn) stage.tools.forEach((t) => availableTools.add(t));
+		const result = {
+			tools: {},
+			activeTools: [],
+			hidden: [],
+			disabled: [],
+			requiresApproval: [],
+			appliedRules: []
+		};
+		for (const [name, tool] of Object.entries(tools)) if (availableTools.has(name) || availableTools.has("*")) {
+			result.tools[name] = tool;
+			result.activeTools.push(name);
+		} else {
+			result.hidden.push(name);
+			result.appliedRules.push(`progressive:${name}`);
+		}
+		return result;
+	};
+}
+/**
+* Creates an activeTools selector for SDK v6.
+* Instead of filtering the tools object, use activeTools parameter.
+*
+* @example
+* ```typescript
+* const selector = createActiveToolsSelector(allTools, [
+*   MaskingRules.requireRole('admin', ['delete*', 'admin*']),
+*   MaskingRules.limitIterations(5),
+* ]);
+*
+* // Use with generateText
+* const result = await generateText({
+*   model,
+*   tools: allTools,  // Pass ALL tools
+*   activeTools: selector(context),  // But only activate some
+*   prompt: 'Do something',
+* });
+* ```
+*/
+function createActiveToolsSelector(tools, rules) {
+	const masker = createToolMasker(rules);
+	return (context) => {
+		return masker(tools, context).activeTools;
+	};
+}
+/**
+* Simple phase-based tool activation.
+* Different tools are active in different phases of execution.
+*
+* @example
+* ```typescript
+* const activator = createPhasedToolActivation({
+*   planning: ['search', 'browse'],
+*   execution: ['code', 'file_write', 'run_command'],
+*   review: ['code_review', 'test'],
+* });
+*
+* const result = await generateText({
+*   model,
+*   tools: allTools,
+*   activeTools: activator('planning'),
+*   prompt: 'Research the topic',
+* });
+* ```
+*/
+function createPhasedToolActivation(phases) {
+	return (phase) => phases[phase] ?? [];
+}
+/**
+* Context-aware tool activation based on user input analysis.
+*
+* @example
+* ```typescript
+* const activator = createContextualToolActivation([
+*   { keywords: ['search', 'find', 'look up'], tools: ['web_search', 'browse'] },
+*   { keywords: ['code', 'write', 'implement'], tools: ['code_edit', 'file_write'] },
+*   { keywords: ['run', 'execute', 'test'], tools: ['run_command', 'test'] },
+* ]);
+*
+* const activeTools = activator(userQuery);
+* ```
+*/
+function createContextualToolActivation(rules, defaultTools = []) {
+	return (input) => {
+		const lowerInput = input.toLowerCase();
+		const matchedTools = new Set(defaultTools);
+		for (const rule of rules) if (rule.keywords.some((kw) => lowerInput.includes(kw.toLowerCase()))) rule.tools.forEach((t) => matchedTools.add(t));
+		return Array.from(matchedTools);
+	};
+}
+
+//#endregion
+//#region src/grounding/context-engineering/memory.ts
+/**
+* In-memory store implementation.
+*/
+var InMemoryStore = class {
+	store = /* @__PURE__ */ new Map();
+	maxEntries;
+	accessOrder = [];
+	constructor(options) {
+		this.maxEntries = options?.maxEntries;
+	}
+	async get(key) {
+		const entry = this.store.get(key);
+		if (entry && this.maxEntries) {
+			const index = this.accessOrder.indexOf(key);
+			if (index >= 0) this.accessOrder.splice(index, 1);
+			this.accessOrder.push(key);
+		}
+		return entry;
+	}
+	async set(key, entry) {
+		if (this.maxEntries) {
+			const index = this.accessOrder.indexOf(key);
+			if (index >= 0) this.accessOrder.splice(index, 1);
+			this.accessOrder.push(key);
+		}
+		this.store.set(key, entry);
+		if (this.maxEntries && this.store.size > this.maxEntries) {
+			const oldest = this.accessOrder.shift();
+			if (oldest) this.store.delete(oldest);
+		}
+	}
+	async delete(key) {
+		const deleted = this.store.delete(key);
+		if (deleted && this.maxEntries) {
+			const index = this.accessOrder.indexOf(key);
+			if (index >= 0) this.accessOrder.splice(index, 1);
+		}
+		return deleted;
+	}
+	async keys() {
+		return Array.from(this.store.keys());
+	}
+	async clear() {
+		this.store.clear();
+		this.accessOrder = [];
+	}
+};
+/**
+* Creates a memory manager for conversation state.
+*
+* @param config - Memory manager configuration
+* @returns Memory manager
+*
+* @example
+* ```ts
+* const memory = createMemoryManager({
+*   store: new InMemoryStore(),
+*   maxMessages: 100,
+*   enableSummarization: true,
+*   summarize: async (messages) => {
+*     // Use LLM to summarize
+*     return 'Summary of conversation...';
+*   },
+* });
+*
+* await memory.addMessage('session-1', { role: 'user', content: 'Hello' });
+* const context = await memory.getContext('session-1', 10);
+* ```
+*/
+function createMemoryManager(config) {
+	const { store, maxMessages = 100, maxTokens, enableSummarization = false, summarize } = config;
+	return {
+		async getOrCreate(key) {
+			const existing = await store.get(key);
+			if (existing) return existing;
+			const entry = {
+				id: key,
+				messages: [],
+				createdAt: Date.now(),
+				updatedAt: Date.now()
+			};
+			await store.set(key, entry);
+			return entry;
+		},
+		async addMessage(key, message) {
+			const entry = await this.getOrCreate(key);
+			entry.messages.push({
+				...message,
+				timestamp: message.timestamp ?? Date.now()
+			});
+			entry.updatedAt = Date.now();
+			if (entry.messages.length > maxMessages) {
+				const excess = entry.messages.splice(0, entry.messages.length - maxMessages);
+				if (enableSummarization && summarize && excess.length > 0) {
+					const newSummary = await summarize(excess);
+					entry.summary = entry.summary ? `${entry.summary}\n\n${newSummary}` : newSummary;
+				}
+			}
+			await store.set(key, entry);
+		},
+		async getContext(key, recentCount = 10) {
+			const entry = await store.get(key);
+			if (!entry) return { messages: [] };
+			return {
+				summary: entry.summary,
+				messages: entry.messages.slice(-recentCount)
+			};
+		},
+		async getMessages(key) {
+			return (await store.get(key))?.messages ?? [];
+		},
+		async clear(key) {
+			await store.delete(key);
+		},
+		async updateMetadata(key, metadata) {
+			const entry = await this.getOrCreate(key);
+			entry.metadata = {
+				...entry.metadata,
+				...metadata
+			};
+			entry.updatedAt = Date.now();
+			await store.set(key, entry);
+		},
+		async search(key, query) {
+			const entry = await store.get(key);
+			if (!entry) return [];
+			const lowerQuery = query.toLowerCase();
+			return entry.messages.filter((m) => m.content.toLowerCase().includes(lowerQuery));
+		}
+	};
+}
+/**
+* Sliding window context builder.
+* Keeps recent messages within token/message limits.
+*
+* @deprecated Use createKVCachePreservingContext for better performance.
+* This version breaks KV-cache by removing messages from the start.
+*/
+function createSlidingWindowContext(config) {
+	const { maxMessages = 20, maxTokens = 4e3, estimateTokens = (text) => Math.ceil(text.length / 4) } = config;
+	return function buildContext(messages) {
+		const result = [];
+		let tokenCount = 0;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const msg = messages[i];
+			if (!msg) continue;
+			const tokens = estimateTokens(msg.content);
+			if (result.length >= maxMessages) break;
+			if (tokenCount + tokens > maxTokens) break;
+			result.unshift(msg);
+			tokenCount += tokens;
+		}
+		return result;
+	};
+}
+/**
+* KV-cache preserving context builder.
+*
+* SDK v6 pattern: Always keep system prompt at the very start to maximize
+* KV-cache hits. When trimming, remove messages from the middle, not the start.
+*
+* This is critical for performance with Claude and other models that support
+* prompt caching - the cache key is based on the prefix of the prompt.
+*
+* @example
+* ```typescript
+* const buildContext = createKVCachePreservingContext({
+*   maxTokens: 100000,
+*   systemPrompt: 'You are a helpful assistant...',
+* });
+*
+* // Messages are trimmed from middle, keeping system prompt at start
+* const contextMessages = buildContext(allMessages);
+* ```
+*/
+function createKVCachePreservingContext(config) {
+	const { maxTokens = 1e5, maxMessages = 100, systemPrompt, estimateTokens = (text) => Math.ceil(text.length / 4), messagePriority } = config;
+	const defaultPriority = (message, index, total) => {
+		if (index < 2) return 100;
+		if (index >= total - 5) return 90 - (total - 1 - index);
+		return 50 - (total - 1 - index) * .5;
+	};
+	const getPriority = messagePriority ?? defaultPriority;
+	return function buildContext(messages) {
+		const systemTokens = systemPrompt ? estimateTokens(systemPrompt) : 0;
+		const availableMessages = maxMessages;
+		const sorted = [...messages.map((msg, index) => ({
+			message: msg,
+			tokens: estimateTokens(msg.content),
+			priority: getPriority(msg, index, messages.length),
+			originalIndex: index
+		}))].sort((a, b) => b.priority - a.priority);
+		const selected = [];
+		let totalTokens = systemTokens;
+		for (const item of sorted) {
+			if (selected.length >= availableMessages) break;
+			if (totalTokens + item.tokens > maxTokens) continue;
+			selected.push(item);
+			totalTokens += item.tokens;
+		}
+		selected.sort((a, b) => a.originalIndex - b.originalIndex);
+		return {
+			systemPrompt,
+			messages: selected.map((s) => s.message),
+			trimmedCount: messages.length - selected.length,
+			totalTokens
+		};
+	};
+}
+/**
+* Immutable context builder that only appends.
+* Never removes messages from the start, maximizing KV-cache hits.
+*
+* When context gets too long, returns a signal to summarize and reset.
+*
+* @example
+* ```typescript
+* const contextBuilder = createImmutableContextBuilder({
+*   systemPrompt: 'You are helpful...',
+*   maxTokens: 100000,
+*   compactionThreshold: 80000, // Start warning at 80%
+* });
+*
+* const context = contextBuilder.append(newMessage);
+* if (context.shouldCompact) {
+*   // Summarize and start fresh context
+*   const summary = await summarize(context.messages);
+*   contextBuilder.reset(summary);
+* }
+* ```
+*/
+function createImmutableContextBuilder(config) {
+	const { systemPrompt, maxTokens = 1e5, compactionThreshold = maxTokens * .8, estimateTokens = (text) => Math.ceil(text.length / 4) } = config;
+	const systemTokens = systemPrompt ? estimateTokens(systemPrompt) : 0;
+	let messages = [];
+	let totalTokens = systemTokens;
+	return {
+		append(message) {
+			const msgTokens = estimateTokens(message.content);
+			totalTokens += msgTokens;
+			messages.push(message);
+			return {
+				systemPrompt,
+				messages: [...messages],
+				totalTokens,
+				shouldCompact: totalTokens >= compactionThreshold,
+				isFull: totalTokens >= maxTokens
+			};
+		},
+		getContext() {
+			return {
+				systemPrompt,
+				messages: [...messages],
+				totalTokens
+			};
+		},
+		reset(summary) {
+			messages = [];
+			totalTokens = systemTokens;
+			if (summary) {
+				const summaryMessage = {
+					role: "system",
+					content: `Previous conversation summary:\n${summary}`,
+					timestamp: Date.now()
+				};
+				messages.push(summaryMessage);
+				totalTokens += estimateTokens(summaryMessage.content);
+			}
+		},
+		get tokenCount() {
+			return totalTokens;
+		},
+		get messageCount() {
+			return messages.length;
+		}
+	};
+}
+/**
+* Creates a compacting memory that summarizes old messages.
+*/
+function createCompactingMemory(config) {
+	const { store, summarize, compactThreshold = 50, keepRecent = 10, maxMessages, maxTokens, enableSummarization } = config;
+	return {
+		...createMemoryManager({
+			store,
+			maxMessages,
+			maxTokens,
+			enableSummarization,
+			summarize
+		}),
+		async compact(key) {
+			const entry = await store.get(key);
+			if (!entry || entry.messages.length < compactThreshold) return;
+			const toKeep = entry.messages.slice(-keepRecent);
+			const toSummarize = entry.messages.slice(0, -keepRecent);
+			if (toSummarize.length === 0) return;
+			const newSummary = await summarize(toSummarize);
+			entry.messages = toKeep;
+			entry.summary = entry.summary ? `${entry.summary}\n\n${newSummary}` : newSummary;
+			entry.updatedAt = Date.now();
+			await store.set(key, entry);
+		}
+	};
+}
+
+//#endregion
+//#region src/grounding/context-engineering/error-handling.ts
+/**
+* AI error with typed classification.
+*/
+var AIError = class extends Error {
+	type;
+	retryable;
+	retryAfter;
+	details;
+	constructor(message, type, options) {
+		super(message, { cause: options?.cause });
+		this.name = "AIError";
+		this.type = type;
+		this.retryable = options?.retryable ?? isRetryableByDefault(type);
+		this.retryAfter = options?.retryAfter;
+		this.details = options?.details;
+	}
+};
+/**
+* Determines if an error type is retryable by default.
+*/
+function isRetryableByDefault(type) {
+	switch (type) {
+		case "rate-limit":
+		case "timeout":
+		case "api-error": return true;
+		case "context-length":
+		case "content-filter":
+		case "tool-error":
+		case "validation":
+		case "unknown": return false;
+	}
+}
+/**
+* Classifies an error into an AIError type.
+*/
+function classifyError(error) {
+	if (error instanceof AIError) return error;
+	const message = error instanceof Error ? error.message : String(error);
+	const cause = error instanceof Error ? error : void 0;
+	if (message.includes("rate limit") || message.includes("429") || message.includes("too many requests")) return new AIError(message, "rate-limit", {
+		retryable: true,
+		retryAfter: extractRetryAfter(message),
+		cause
+	});
+	if (message.includes("context length") || message.includes("maximum context") || message.includes("token limit") || message.includes("too long")) return new AIError(message, "context-length", {
+		retryable: false,
+		cause
+	});
+	if (message.includes("content filter") || message.includes("content policy") || message.includes("safety")) return new AIError(message, "content-filter", {
+		retryable: false,
+		cause
+	});
+	if (message.includes("timeout") || message.includes("timed out") || message.includes("ETIMEDOUT")) return new AIError(message, "timeout", {
+		retryable: true,
+		cause
+	});
+	if (message.includes("500") || message.includes("502") || message.includes("503") || message.includes("API error")) return new AIError(message, "api-error", {
+		retryable: true,
+		cause
+	});
+	return new AIError(message, "unknown", { cause });
+}
+/**
+* Extracts retry-after value from error message.
+*/
+function extractRetryAfter(message) {
+	const match = message.match(/retry.+?(\d+)\s*(s|seconds?|ms|milliseconds?)/i);
+	if (match?.[1] && match[2]) {
+		const value = parseInt(match[1], 10);
+		return match[2].toLowerCase().startsWith("ms") ? value : value * 1e3;
+	}
+}
+/**
+* Creates an error recovery handler.
+*
+* @param strategies - Recovery strategies in priority order
+* @returns Recovery handler
+*
+* @example
+* ```ts
+* const recover = createErrorRecovery([
+*   {
+*     errorTypes: ['rate-limit'],
+*     action: { type: 'retry', backoff: 'exponential', baseDelay: 1000 },
+*     maxRetries: 3,
+*   },
+*   {
+*     errorTypes: ['context-length'],
+*     action: { type: 'reduce-context', factor: 0.5 },
+*   },
+*   {
+*     errorTypes: ['content-filter'],
+*     action: { type: 'fail', message: 'Content blocked by safety filters' },
+*   },
+* ]);
+*
+* try {
+*   await generateText(...);
+* } catch (e) {
+*   const result = await recover(e, { attempt: 1 });
+*   if (result.continueExecution) {
+*     // Retry with modified params
+*   }
+* }
+* ```
+*/
+function createErrorRecovery(strategies) {
+	const retryCounters = /* @__PURE__ */ new Map();
+	return async function recover(error, context) {
+		const aiError = classifyError(error);
+		const strategy = strategies.find((s) => s.errorTypes.includes(aiError.type));
+		if (!strategy) return {
+			success: false,
+			action: "none",
+			continueExecution: false,
+			error: aiError
+		};
+		const currentRetries = retryCounters.get(aiError.type) ?? 0;
+		if (strategy.maxRetries !== void 0 && currentRetries >= strategy.maxRetries) return {
+			success: false,
+			action: "max-retries-exceeded",
+			continueExecution: false,
+			error: aiError
+		};
+		switch (strategy.action.type) {
+			case "retry": {
+				retryCounters.set(aiError.type, currentRetries + 1);
+				const delay = calculateDelay(strategy.action, context.attempt);
+				if (aiError.retryAfter) await sleep(aiError.retryAfter);
+				else await sleep(delay);
+				return {
+					success: true,
+					action: "retry",
+					continueExecution: true
+				};
+			}
+			case "reduce-context": {
+				const factor = strategy.action.factor ?? .5;
+				return {
+					success: true,
+					action: "reduce-context",
+					continueExecution: true,
+					modifiedParams: { maxMessages: Math.floor((context.maxMessages ?? 20) * factor) }
+				};
+			}
+			case "switch-model": return {
+				success: true,
+				action: "switch-model",
+				continueExecution: true,
+				modifiedParams: { model: strategy.action.fallbackModel }
+			};
+			case "fail": return {
+				success: false,
+				action: "fail",
+				continueExecution: false,
+				error: new AIError(strategy.action.message ?? aiError.message, aiError.type)
+			};
+			case "custom": return strategy.action.handler(aiError);
+		}
+	};
+}
+/**
+* Calculates delay based on backoff strategy.
+*/
+function calculateDelay(action, attempt) {
+	const baseDelay = action.baseDelay ?? 1e3;
+	const backoff = action.backoff ?? "fixed";
+	switch (backoff) {
+		case "exponential": return baseDelay * Math.pow(2, attempt - 1);
+		case "linear": return baseDelay * attempt;
+		case "fixed": return baseDelay;
+		default: {
+			const exhaustiveCheck = backoff;
+			throw new Error(`Unknown backoff strategy: ${exhaustiveCheck}`);
+		}
+	}
+}
+/**
+* Sleep helper.
+*/
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Default recovery strategies.
+*/
+const DefaultRecoveryStrategies = [
+	{
+		errorTypes: ["rate-limit"],
+		action: {
+			type: "retry",
+			backoff: "exponential",
+			baseDelay: 1e3
+		},
+		maxRetries: 5
+	},
+	{
+		errorTypes: ["timeout"],
+		action: {
+			type: "retry",
+			backoff: "exponential",
+			baseDelay: 2e3
+		},
+		maxRetries: 3
+	},
+	{
+		errorTypes: ["api-error"],
+		action: {
+			type: "retry",
+			backoff: "exponential",
+			baseDelay: 1e3
+		},
+		maxRetries: 3
+	},
+	{
+		errorTypes: ["context-length"],
+		action: {
+			type: "reduce-context",
+			factor: .5
+		},
+		maxRetries: 2
+	},
+	{
+		errorTypes: ["content-filter"],
+		action: {
+			type: "fail",
+			message: "Content was blocked by safety filters"
+		}
+	}
+];
+
+//#endregion
+export { groupSources as C, validateSource as D, sourcesToContext as E, validateSources as O, formatAsInlineCitations as S, selectTopSources as T, createSourceRegistry as _, InMemoryStore as a, filterByScore as b, createKVCachePreservingContext as c, MaskingRules as d, createActiveToolsSelector as f, createToolMasker as g, createProgressiveDisclosure as h, createErrorRecovery as i, InMemoryVectorStore as k, createMemoryManager as l, createPhasedToolActivation as m, DefaultRecoveryStrategies as n, createCompactingMemory as o, createContextualToolActivation as p, classifyError as r, createImmutableContextBuilder as s, AIError as t, createSlidingWindowContext as u, deduplicateSources as v, mergeSources as w, formatAsBibliography as x, filterByMetadata as y };
+//# sourceMappingURL=error-handling-DNVkm6RY.mjs.map