@inkeep/agents-core 0.41.2 → 0.43.0

package/dist/context/ContextResolver.d.ts

@@ -1,60 +0,0 @@
-import { ContextConfigSelect } from "../types/entities.js";
-import "../types/index.js";
-import { CredentialStoreRegistry } from "../credential-stores/CredentialStoreRegistry.js";
-import { DatabaseClient } from "../db/client.js";
-
-//#region src/context/ContextResolver.d.ts
-interface ResolvedContext {
-  [templateKey: string]: unknown;
-}
-interface ContextResolutionOptions {
-  triggerEvent: 'initialization' | 'invocation';
-  conversationId: string;
-  headers?: Record<string, unknown>;
-  tenantId: string;
-}
-interface ContextResolutionResult {
-  resolvedContext: ResolvedContext;
-  headers: Record<string, unknown>;
-  fetchedDefinitions: string[];
-  cacheHits: string[];
-  cacheMisses: string[];
-  errors: Array<{
-    definitionId: string;
-    error: string;
-  }>;
-  skipped: Array<{
-    definitionId: string;
-    reason: string;
-  }>;
-  totalDurationMs: number;
-}
-declare class ContextResolver {
-  private fetcher;
-  private cache;
-  private tenantId;
-  private projectId;
-  constructor(tenantId: string, projectId: string, dbClient: DatabaseClient, credentialStoreRegistry?: CredentialStoreRegistry);
-  /**
-   * Resolve all contexts for a given configuration and trigger event
-   */
-  resolve(contextConfig: ContextConfigSelect, options: ContextResolutionOptions): Promise<ContextResolutionResult>;
-  /**
-   * Resolve a single context variable
-   */
-  private resolveSingleFetchDefinition;
-  /**
-   * Resolve the headers for a given conversation
-   */
-  resolveHeaders(conversationId: string, contextConfigId: string): Promise<Record<string, unknown>>;
-  /**
-   * Create a hash of the headers for cache invalidation
-   */
-  private createRequestHash;
-  /**
-   * Clear cache
-   */
-  clearCache(tenantId: string, projectId: string, conversationId: string): Promise<void>;
-}
-//#endregion
-export { ContextResolutionOptions, ContextResolutionResult, ContextResolver, ResolvedContext };

package/dist/context/ContextResolver.js

@@ -1,278 +0,0 @@
-import { getLogger } from "../utils/logger.js";
-import { setSpanWithError } from "../utils/tracer-factory.js";
-import "../utils/index.js";
-import { tracer } from "../utils/tracer.js";
-import { ContextCache } from "./contextCache.js";
-import { ContextFetcher, MissingRequiredVariableError } from "./ContextFetcher.js";
-import crypto from "node:crypto";
-import { SpanStatusCode } from "@opentelemetry/api";
-
-//#region src/context/ContextResolver.ts
-const logger = getLogger("context-resolver");
-var ContextResolver = class {
-	fetcher;
-	cache;
-	tenantId;
-	projectId;
-	constructor(tenantId, projectId, dbClient, credentialStoreRegistry) {
-		this.tenantId = tenantId;
-		this.projectId = projectId;
-		this.fetcher = new ContextFetcher(tenantId, projectId, dbClient, credentialStoreRegistry);
-		this.cache = new ContextCache(tenantId, projectId, dbClient);
-		logger.info({
-			tenantId: this.tenantId,
-			hasCredentialSupport: !!credentialStoreRegistry
-		}, "ContextResolver initialized");
-	}
-	/**
-	* Resolve all contexts for a given configuration and trigger event
-	*/
-	async resolve(contextConfig, options) {
-		const startTime = Date.now();
-		logger.info({
-			contextConfigId: contextConfig.id,
-			triggerEvent: options.triggerEvent,
-			conversationId: options.conversationId
-		}, "Starting context resolution");
-		return tracer.startActiveSpan("context.resolve", { attributes: {
-			"context.config_id": contextConfig.id,
-			"context.trigger_event": options.triggerEvent
-		} }, async (parentSpan) => {
-			try {
-				const result = {
-					resolvedContext: {},
-					headers: options.headers || {},
-					fetchedDefinitions: [],
-					cacheHits: [],
-					cacheMisses: [],
-					errors: [],
-					skipped: [],
-					totalDurationMs: 0
-				};
-				result.resolvedContext.headers = result.headers;
-				const currentHeaders = await this.cache.get({
-					conversationId: options.conversationId,
-					contextConfigId: contextConfig.id,
-					contextVariableKey: "headers"
-				});
-				if (options.headers && Object.keys(options.headers).length > 0) {
-					await this.cache.invalidateHeaders(this.tenantId, this.projectId, options.conversationId, contextConfig.id);
-					logger.info({
-						conversationId: options.conversationId,
-						contextConfigId: contextConfig.id
-					}, "Invalidated headers in cache");
-					await this.cache.set({
-						contextConfigId: contextConfig.id,
-						contextVariableKey: "headers",
-						conversationId: options.conversationId,
-						value: options.headers,
-						tenantId: this.tenantId
-					});
-					logger.info({
-						conversationId: options.conversationId,
-						contextConfigId: contextConfig.id
-					}, "Headers set in cache");
-				} else if (currentHeaders) result.headers = currentHeaders.value;
-				else result.headers = {};
-				result.resolvedContext.headers = result.headers;
-				const contextVariables = contextConfig.contextVariables || {};
-				const contextVariableEntries = Object.entries(contextVariables);
-				if (contextVariableEntries.length === 0) {
-					logger.info({ contextConfigId: contextConfig.id }, "No context variables in context config");
-					result.totalDurationMs = Date.now() - startTime;
-					parentSpan.setStatus({ code: SpanStatusCode.OK });
-					return result;
-				}
-				contextVariableEntries.filter(([, def]) => def.trigger === "initialization");
-				const invocationDefs = contextVariableEntries.filter(([, def]) => def.trigger === "invocation");
-				if (options.triggerEvent === "invocation" && invocationDefs.length > 0) await this.cache.invalidateInvocationDefinitions(this.tenantId, this.projectId, options.conversationId, contextConfig.id, invocationDefs.map(([, def]) => def.id));
-				const requestHash = this.createRequestHash(result.headers);
-				const fetchPromises = contextVariableEntries.map(([templateKey, definition]) => this.resolveSingleFetchDefinition(contextConfig, definition, templateKey, options, requestHash, result).catch((error) => {
-					const errorMessage = error instanceof Error ? error.message : "Unknown error";
-					if (error instanceof MissingRequiredVariableError) {
-						logger.info({
-							contextConfigId: contextConfig.id,
-							definitionId: definition.id,
-							templateKey,
-							reason: errorMessage
-						}, "Context fetch skipped due to missing required variable");
-						result.skipped.push({
-							definitionId: definition.id,
-							reason: errorMessage
-						});
-						if (definition.defaultValue !== void 0) {
-							result.resolvedContext[templateKey] = definition.defaultValue;
-							logger.info({
-								contextConfigId: contextConfig.id,
-								definitionId: definition.id,
-								templateKey
-							}, "Using default value for skipped context variable");
-						}
-						return;
-					}
-					logger.error({
-						contextConfigId: contextConfig.id,
-						definitionId: definition.id,
-						templateKey,
-						error: errorMessage
-					}, "Failed to resolve context variable");
-					result.errors.push({
-						definitionId: definition.id,
-						error: errorMessage
-					});
-					if (definition.defaultValue !== void 0) {
-						result.resolvedContext[templateKey] = definition.defaultValue;
-						logger.info({
-							contextConfigId: contextConfig.id,
-							definitionId: definition.id,
-							templateKey
-						}, "Using default value for failed context variable");
-					}
-				}));
-				await Promise.all(fetchPromises);
-				result.totalDurationMs = Date.now() - startTime;
-				parentSpan.addEvent("context.resolution.completed", {
-					resolved_keys: Object.keys(result.resolvedContext),
-					fetched_definitions: result.fetchedDefinitions,
-					skipped_definitions: result.skipped.map((s) => s.definitionId)
-				});
-				if (result.errors.length > 0) parentSpan.setStatus({
-					code: SpanStatusCode.ERROR,
-					message: `Context resolution completed with errors`
-				});
-				else parentSpan.setStatus({ code: SpanStatusCode.OK });
-				logger.info({
-					contextConfigId: contextConfig.id,
-					resolvedKeys: Object.keys(result.resolvedContext),
-					fetchedDefinitions: result.fetchedDefinitions.length,
-					cacheHits: result.cacheHits.length,
-					cacheMisses: result.cacheMisses.length,
-					errors: result.errors.length,
-					skipped: result.skipped.length,
-					totalDurationMs: result.totalDurationMs
-				}, "Context resolution completed");
-				return result;
-			} catch (error) {
-				const durationMs = Date.now() - startTime;
-				setSpanWithError(parentSpan, error instanceof Error ? error : new Error(String(error)));
-				logger.error({
-					contextConfigId: contextConfig.id,
-					error: error instanceof Error ? error.message : String(error),
-					durationMs
-				}, "Context resolution failed");
-				throw error;
-			} finally {
-				parentSpan.end();
-			}
-		});
-	}
-	/**
-	* Resolve a single context variable
-	*/
-	async resolveSingleFetchDefinition(contextConfig, definition, templateKey, options, requestHash, result) {
-		const cachedEntry = await this.cache.get({
-			conversationId: options.conversationId,
-			contextConfigId: contextConfig.id,
-			contextVariableKey: templateKey,
-			requestHash
-		});
-		if (cachedEntry) {
-			result.resolvedContext[templateKey] = cachedEntry.value;
-			result.cacheHits.push(definition.id);
-			logger.debug({
-				definitionId: definition.id,
-				templateKey,
-				conversationId: options.conversationId
-			}, "Cache hit for context variable");
-			return;
-		}
-		result.cacheMisses.push(definition.id);
-		logger.debug({
-			definitionId: definition.id,
-			templateKey,
-			conversationId: options.conversationId
-		}, "Cache miss for context variable, fetching data");
-		const definitionWithConversationId = {
-			...definition,
-			fetchConfig: {
-				...definition.fetchConfig,
-				conversationId: options.conversationId
-			}
-		};
-		const fetchedData = await tracer.startActiveSpan("context-resolver.resolve_single_fetch_definition", { attributes: {
-			"context.definition_id": definition.id,
-			"context.template_key": templateKey,
-			"context.url_template": definition.fetchConfig.url,
-			"context.method": definition.fetchConfig.method,
-			"context.trigger": definition.trigger
-		} }, async (parentSpan) => {
-			try {
-				const { data, resolvedUrl } = await this.fetcher.fetch(definitionWithConversationId, result.resolvedContext);
-				parentSpan.setAttribute("context.url", resolvedUrl);
-				parentSpan.setStatus({ code: SpanStatusCode.OK });
-				parentSpan.addEvent("context.fetch_success", {
-					definition_id: definition.id,
-					template_key: templateKey,
-					source: resolvedUrl
-				});
-				return data;
-			} catch (error) {
-				if (error instanceof MissingRequiredVariableError) {
-					parentSpan.setStatus({ code: SpanStatusCode.OK });
-					parentSpan.addEvent("context.fetch_skipped", {
-						definition_id: definition.id,
-						template_key: templateKey,
-						reason: error.message
-					});
-				} else setSpanWithError(parentSpan, error instanceof Error ? error : new Error(String(error)));
-				throw error;
-			} finally {
-				parentSpan.end();
-			}
-		});
-		result.resolvedContext[templateKey] = fetchedData;
-		result.fetchedDefinitions.push(definition.id);
-		await this.cache.set({
-			contextConfigId: contextConfig.id,
-			contextVariableKey: templateKey,
-			conversationId: options.conversationId,
-			value: fetchedData,
-			requestHash,
-			tenantId: this.tenantId
-		});
-		logger.debug({
-			definitionId: definition.id,
-			templateKey,
-			conversationId: options.conversationId
-		}, "Context variable resolved and cached");
-	}
-	/**
-	* Resolve the headers for a given conversation
-	*/
-	async resolveHeaders(conversationId, contextConfigId) {
-		const cachedEntry = await this.cache.get({
-			conversationId,
-			contextConfigId,
-			contextVariableKey: "headers"
-		});
-		if (cachedEntry) return cachedEntry.value;
-		return {};
-	}
-	/**
-	* Create a hash of the headers for cache invalidation
-	*/
-	createRequestHash(headers) {
-		const contextString = JSON.stringify(headers, Object.keys(headers).sort());
-		return crypto.createHash("sha256").update(contextString).digest("hex").substring(0, 16);
-	}
-	/**
-	* Clear cache
-	*/
-	async clearCache(tenantId, projectId, conversationId) {
-		await this.cache.clearConversation(tenantId, projectId, conversationId);
-		logger.info({ conversationId }, "Context cache cleared for conversation");
-	}
-};
-
-//#endregion
-export { ContextResolver };

package/dist/context/context.d.ts

@@ -1,27 +0,0 @@
-import { CredentialStoreRegistry } from "../credential-stores/CredentialStoreRegistry.js";
-import { ResolvedContext } from "./ContextResolver.js";
-import "../index.js";
-import { DatabaseClient } from "../db/client.js";
-
-//#region src/context/context.d.ts
-declare function determineContextTrigger(tenantId: string, projectId: string, conversationId: string, dbClient: DatabaseClient): Promise<'initialization' | 'invocation'>;
-declare function handleContextConfigChange(tenantId: string, projectId: string, conversationId: string, agentId: string, newContextConfigId: string, dbClient: DatabaseClient, credentialStores?: CredentialStoreRegistry): Promise<void>;
-declare function handleContextResolution({
-  tenantId,
-  projectId,
-  agentId,
-  conversationId,
-  headers,
-  dbClient,
-  credentialStores
-}: {
-  tenantId: string;
-  projectId: string;
-  agentId: string;
-  conversationId: string;
-  headers: Record<string, unknown>;
-  dbClient: DatabaseClient;
-  credentialStores?: CredentialStoreRegistry;
-}): Promise<ResolvedContext | null>;
-//#endregion
-export { determineContextTrigger, handleContextConfigChange, handleContextResolution };

package/dist/context/context.js

@@ -1,128 +0,0 @@
-import { getLogger } from "../utils/logger.js";
-import { getContextConfigById } from "../data-access/contextConfigs.js";
-import { setSpanWithError } from "../utils/tracer-factory.js";
-import "../utils/index.js";
-import { getAgentWithDefaultSubAgent } from "../data-access/agents.js";
-import { getConversation, updateConversation } from "../data-access/conversations.js";
-import { tracer } from "../utils/tracer.js";
-import { ContextResolver } from "./ContextResolver.js";
-import "../index.js";
-import { SpanStatusCode } from "@opentelemetry/api";
-
-//#region src/context/context.ts
-const logger = getLogger("context");
-async function determineContextTrigger(tenantId, projectId, conversationId, dbClient) {
-	const conversation = await getConversation(dbClient)({
-		scopes: {
-			tenantId,
-			projectId
-		},
-		conversationId
-	});
-	if (!conversation || !conversation.lastContextResolution) return "initialization";
-	return "invocation";
-}
-async function handleContextConfigChange(tenantId, projectId, conversationId, agentId, newContextConfigId, dbClient, credentialStores) {
-	const conversation = await getConversation(dbClient)({
-		scopes: {
-			tenantId,
-			projectId
-		},
-		conversationId
-	});
-	if (!conversation) return;
-	if (conversation.lastContextResolution) {
-		await new ContextResolver(tenantId, projectId, dbClient, credentialStores).clearCache(tenantId, projectId, conversationId);
-		logger.info({
-			conversationId,
-			agentId,
-			contextConfigId: newContextConfigId
-		}, "Potential context config change for existing conversation, cache cleared");
-	}
-}
-async function handleContextResolution({ tenantId, projectId, agentId, conversationId, headers, dbClient, credentialStores }) {
-	return tracer.startActiveSpan("context.handle_context_resolution", { attributes: { "context.headers_keys": Object.keys(headers) } }, async (parentSpan) => {
-		let agent;
-		let trigger;
-		try {
-			agent = await getAgentWithDefaultSubAgent(dbClient)({ scopes: {
-				tenantId,
-				projectId,
-				agentId
-			} });
-			if (!agent?.contextConfigId) {
-				logger.debug({ agentId }, "No context config found for agent");
-				return null;
-			}
-			await handleContextConfigChange(tenantId, projectId, conversationId, agentId, agent.contextConfigId, dbClient, credentialStores);
-			trigger = await determineContextTrigger(tenantId, projectId, conversationId, dbClient);
-			const contextConfig = await getContextConfigById(dbClient)({
-				scopes: {
-					tenantId,
-					projectId,
-					agentId
-				},
-				id: agent.contextConfigId
-			});
-			if (!contextConfig) {
-				logger.warn({ contextConfigId: agent.contextConfigId }, "Context config not found, proceeding without context resolution");
-				parentSpan.setStatus({ code: SpanStatusCode.ERROR });
-				parentSpan.addEvent("context.config_not_found", { contextConfigId: agent.contextConfigId });
-				return null;
-			}
-			const contextResult = await new ContextResolver(tenantId, projectId, dbClient, credentialStores).resolve(contextConfig, {
-				triggerEvent: trigger,
-				conversationId,
-				headers,
-				tenantId
-			});
-			const resolvedContext = {
-				...contextResult.resolvedContext,
-				$env: process.env
-			};
-			await updateConversation(dbClient)({
-				scopes: {
-					tenantId,
-					projectId
-				},
-				conversationId,
-				data: { lastContextResolution: (/* @__PURE__ */ new Date()).toISOString() }
-			});
-			if (contextResult.errors.length > 0) parentSpan.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: `Context resolution completed with errors`
-			});
-			else parentSpan.setStatus({ code: SpanStatusCode.OK });
-			logger.info({
-				conversationId,
-				agentId,
-				contextConfigId: contextConfig.id,
-				trigger,
-				resolvedKeys: Object.keys(resolvedContext),
-				cacheHits: contextResult.cacheHits.length,
-				cacheMisses: contextResult.cacheMisses.length,
-				fetchedDefinitions: contextResult.fetchedDefinitions.length,
-				errors: contextResult.errors.length
-			}, "Context resolution completed (contextConfigId derived from agent)");
-			return resolvedContext;
-		} catch (error) {
-			const errorMessage = error instanceof Error ? error.message : "Unknown error";
-			parentSpan.setAttributes({
-				"context.final_status": "failed",
-				"context.error_message": errorMessage
-			});
-			setSpanWithError(parentSpan, error instanceof Error ? error : new Error(String(error)));
-			logger.error({
-				error: errorMessage,
-				contextConfigId: agent?.contextConfigId,
-				trigger: await determineContextTrigger(tenantId, projectId, conversationId, dbClient).catch(() => "unknown")
-			}, "Failed to resolve context, proceeding without context resolution");
-			return null;
-		} finally {
-			parentSpan.end();
-		}
-	});
-}
-
-//#endregion
-export { determineContextTrigger, handleContextConfigChange, handleContextResolution };

package/dist/context/contextCache.d.ts

@@ -1,58 +0,0 @@
-import { DatabaseClient } from "../db/client.js";
-
-//#region src/context/contextCache.d.ts
-interface CacheEntry {
-  contextConfigId: string;
-  contextVariableKey: string;
-  conversationId: string;
-  value: unknown;
-  requestHash?: string;
-  tenantId: string;
-}
-/**
- * Context cache with request hash-based invalidation and graceful error handling.
- *
- * Implements conversation-scoped caching with smart cache invalidation based on
- * request hash changes. All cache errors are treated as cache misses to ensure
- * system reliability.
- */
-declare class ContextCache {
-  private tenantId;
-  private projectId;
-  private dbClient;
-  constructor(tenantId: string, projectId: string, dbClient: DatabaseClient);
-  /**
-   * Get cached context data for a conversation
-   */
-  get({
-    conversationId,
-    contextConfigId,
-    contextVariableKey,
-    requestHash
-  }: {
-    conversationId: string;
-    contextConfigId: string;
-    contextVariableKey: string;
-    requestHash?: string;
-  }): Promise<CacheEntry | null>;
-  /**
-   * Set cached context data for a conversation
-   */
-  set(entry: CacheEntry): Promise<void>;
-  /**
-   * Clear cache entries for a specific conversation
-   */
-  clearConversation(tenantId: string, projectId: string, conversationId: string): Promise<void>;
-  /**
-   * Clear all cache entries for a specific context configuration
-   */
-  clearContextConfig(tenantId: string, projectId: string, contextConfigId: string): Promise<void>;
-  /**
-   * Clean up expired or orphaned cache entries
-   */
-  cleanup(): Promise<void>;
-  invalidateInvocationDefinitions(tenantId: string, projectId: string, conversationId: string, contextConfigId: string, definitionIds: string[]): Promise<void>;
-  invalidateHeaders(tenantId: string, projectId: string, conversationId: string, contextConfigId: string): Promise<void>;
-}
-//#endregion
-export { CacheEntry, ContextCache };