@inkeep/agents-api 0.0.1

package/dist/domains/run/context/ContextFetcher.js

@@ -0,0 +1,276 @@
+import { validateAgainstJsonSchema } from "./validation.js";
+import { CredentialStuffer, JsonTransformer, TemplateEngine, getLogger } from "@inkeep/agents-core";
+
+//#region src/domains/run/context/ContextFetcher.ts
+const logger = getLogger("context-fetcher");
+var MissingRequiredVariableError = class extends Error {
+	constructor(variable) {
+		super(`Missing required variable: ${variable}`);
+		this.name = "MissingRequiredVariableError";
+	}
+};
+/**
+* GraphQL error checker - validates response for GraphQL errors and throws if found
+*/
+const checkGraphQLErrors = (data) => {
+	if (data && typeof data === "object" && "errors" in data) {
+		const errorObj = data;
+		if (Array.isArray(errorObj.errors) && errorObj.errors.length > 0) {
+			const agentqlErrors = errorObj.errors;
+			const errorMessage = `GraphQL request failed with ${agentqlErrors.length} errors: ${agentqlErrors.map((e) => e.message || "Unknown error").join(", ")}`;
+			throw new Error(errorMessage);
+		}
+	}
+};
+const responseErrorCheckers = [checkGraphQLErrors];
+var ContextFetcher = class {
+	executionContext;
+	defaultTimeout;
+	credentialStuffer;
+	constructor(executionContext, credentialStoreRegistry, defaultTimeout = 1e4) {
+		this.executionContext = executionContext;
+		this.defaultTimeout = defaultTimeout;
+		if (credentialStoreRegistry) this.credentialStuffer = new CredentialStuffer(credentialStoreRegistry);
+		logger.info({
+			tenantId: this.executionContext.tenantId,
+			defaultTimeout: this.defaultTimeout,
+			hasCredentialSupport: !!this.credentialStuffer
+		}, "ContextFetcher initialized");
+	}
+	/**
+	* Fetch data according to a fetch definition
+	*/
+	async fetch(definition, context) {
+		const startTime = Date.now();
+		logger.info({
+			definitionId: definition.id,
+			url: definition.fetchConfig.url
+		}, "Starting context fetch");
+		try {
+			const resolvedConfig = await this.resolveTemplateVariables(definition.fetchConfig, context, definition.credentialReferenceId);
+			const response = await this.performRequest(resolvedConfig);
+			let transformedData = response.data;
+			if (definition.fetchConfig.transform) transformedData = await this.transformResponse(response.data, definition.fetchConfig.transform);
+			if (definition.responseSchema) this.validateResponseWithJsonSchema(transformedData, definition.responseSchema, definition.id);
+			const durationMs = Date.now() - startTime;
+			logger.info({
+				definitionId: definition.id,
+				source: response.source,
+				durationMs
+			}, "Context fetch completed successfully");
+			return {
+				data: transformedData,
+				resolvedUrl: resolvedConfig.url
+			};
+		} catch (error) {
+			const durationMs = Date.now() - startTime;
+			const errorMessage = error instanceof Error ? error.message : "Unknown error";
+			if (error instanceof MissingRequiredVariableError) logger.error({
+				definitionId: definition.id,
+				error: errorMessage,
+				durationMs
+			}, "Context fetch skipped due to missing required variable");
+			logger.error({
+				definitionId: definition.id,
+				error: errorMessage,
+				durationMs
+			}, "Context fetch failed");
+			throw error;
+		}
+	}
+	async getCredential(credentialReferenceId) {
+		const { project, tenantId, projectId } = this.executionContext;
+		try {
+			const credentialReference = project.credentialReferences?.[credentialReferenceId];
+			logger.info({ credentialReference }, "Credential reference");
+			if (!credentialReference || !this.credentialStuffer) throw new Error(`Credential store not found for reference ID: ${credentialReferenceId}`);
+			const credentialContext = {
+				tenantId,
+				projectId
+			};
+			const storeReference = {
+				credentialStoreId: credentialReference.credentialStoreId,
+				retrievalParams: credentialReference.retrievalParams || {}
+			};
+			return await this.credentialStuffer.getCredentials(credentialContext, storeReference);
+		} catch (error) {
+			logger.error({
+				credentialReferenceId,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to resolve credentials for fetch request");
+			throw error;
+		}
+	}
+	/**
+	* Resolve template variables in fetch configuration and inject credential headers
+	*/
+	async resolveTemplateVariables(fetchConfig, context, credentialReferenceId) {
+		const resolved = { ...fetchConfig };
+		const filteredRequiredToFetch = fetchConfig.requiredToFetch?.filter((variable) => variable.startsWith("{{") && variable.endsWith("}}"));
+		if (filteredRequiredToFetch) for (const variable of filteredRequiredToFetch) {
+			let resolvedVariable;
+			try {
+				resolvedVariable = this.interpolateTemplate(variable, context);
+			} catch {
+				throw new MissingRequiredVariableError(variable);
+			}
+			if (resolvedVariable === "" || resolvedVariable === variable) throw new MissingRequiredVariableError(variable);
+		}
+		resolved.url = this.interpolateTemplate(fetchConfig.url, context);
+		logger.info({ resolvedUrl: resolved.url }, "Resolved URL");
+		if (fetchConfig.headers) {
+			resolved.headers = {};
+			for (const [key, value] of Object.entries(fetchConfig.headers)) resolved.headers[key] = this.interpolateTemplate(value, context);
+		}
+		if (fetchConfig.body) resolved.body = this.interpolateObjectTemplates(fetchConfig.body, context);
+		if (credentialReferenceId && this.credentialStuffer) try {
+			const credentialHeaders = (await this.getCredential(credentialReferenceId))?.headers;
+			if (credentialHeaders) {
+				resolved.headers = {
+					...resolved.headers,
+					...credentialHeaders
+				};
+				logger.info({ credentialReferenceId }, "Added credential headers to fetch request");
+			}
+		} catch (error) {
+			logger.error({
+				credentialReferenceId,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to resolve credentials for fetch request");
+			throw error;
+		}
+		return resolved;
+	}
+	/**
+	* Interpolate template variables in a string using TemplateEngine
+	*/
+	interpolateTemplate(template, context) {
+		try {
+			return TemplateEngine.render(template, context, {
+				strict: false,
+				preserveUnresolved: true
+			});
+		} catch (error) {
+			logger.error({
+				template,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to interpolate template variable");
+			return template;
+		}
+	}
+	/**
+	* Interpolate template variables in an object recursively using TemplateEngine
+	*/
+	interpolateObjectTemplates(obj, context) {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) if (typeof value === "string") result[key] = this.interpolateTemplate(value, context);
+		else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = this.interpolateObjectTemplates(value, context);
+		else result[key] = value;
+		return result;
+	}
+	/**
+	* Perform HTTP request
+	*/
+	async performRequest(config) {
+		const startTime = Date.now();
+		try {
+			logger.debug({
+				url: config.url,
+				method: config.method
+			}, "Performing HTTP request");
+			const response = await fetch(config.url, {
+				method: config.method,
+				headers: config.headers,
+				body: config.body ? JSON.stringify(config.body) : void 0,
+				signal: AbortSignal.timeout(config.timeout || this.defaultTimeout)
+			});
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw /* @__PURE__ */ new Error(`HTTP ${response.status}: ${response.statusText} - ${errorText}`);
+			}
+			const contentType = response.headers.get("content-type") || "";
+			let data;
+			if (contentType.includes("application/json")) data = await response.json();
+			else data = await response.text();
+			const durationMs = Date.now() - startTime;
+			for (const checker of responseErrorCheckers) checker(data);
+			return {
+				data,
+				source: config.url,
+				durationMs
+			};
+		} catch (error) {
+			const durationMs = Date.now() - startTime;
+			const requestError = error instanceof Error ? error : /* @__PURE__ */ new Error("Unknown error");
+			logger.warn({
+				url: config.url,
+				error: requestError.message,
+				durationMs
+			}, "HTTP request failed");
+			throw requestError;
+		}
+	}
+	/**
+	* Transform response data using JsonTransformer (JMESPath)
+	*/
+	async transformResponse(data, transform) {
+		try {
+			return await JsonTransformer.transform(data, transform);
+		} catch (error) {
+			logger.error({
+				transform,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to transform response data");
+			return data;
+		}
+	}
+	/**
+	* Validate response against JSON Schema
+	*/
+	validateResponseWithJsonSchema(data, jsonSchema, definitionId) {
+		try {
+			if (!validateAgainstJsonSchema(jsonSchema, data)) throw new Error("Data does not match JSON Schema");
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : "Unknown validation error";
+			logger.error({
+				definitionId,
+				jsonSchema,
+				error: errorMessage
+			}, "JSON Schema response validation failed");
+			throw new Error(`Response validation failed: ${errorMessage}`);
+		}
+	}
+	/**
+	* Test a fetch definition without caching
+	*/
+	async test(definition, context) {
+		const startTime = Date.now();
+		try {
+			const result = await this.fetch(definition, context);
+			return {
+				success: true,
+				data: result.data,
+				resolvedUrl: result.resolvedUrl,
+				durationMs: Date.now() - startTime
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : "Unknown error",
+				durationMs: Date.now() - startTime
+			};
+		}
+	}
+	/**
+	* Get fetcher statistics
+	*/
+	getStats() {
+		return {
+			tenantId: this.executionContext.tenantId,
+			defaultTimeout: this.defaultTimeout
+		};
+	}
+};
+
+//#endregion
+export { ContextFetcher, MissingRequiredVariableError };

package/dist/domains/run/context/ContextResolver.d.ts

@@ -0,0 +1,56 @@
+import { ContextConfigApiSelect, CredentialStoreRegistry, FullExecutionContext } from "@inkeep/agents-core";
+
+//#region src/domains/run/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 executionContext;
+  constructor(executionContext: FullExecutionContext, credentialStoreRegistry?: CredentialStoreRegistry);
+  /**
+   * Resolve all contexts for a given configuration and trigger event
+   */
+  resolve(contextConfig: ContextConfigApiSelect, 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/domains/run/context/ContextResolver.js

@@ -0,0 +1,273 @@
+import { ContextCache } from "./contextCache.js";
+import { ContextFetcher, MissingRequiredVariableError } from "./ContextFetcher.js";
+import { getLogger, getTracer, setSpanWithError } from "@inkeep/agents-core";
+import { SpanStatusCode } from "@opentelemetry/api";
+import crypto from "node:crypto";
+
+//#region src/domains/run/context/ContextResolver.ts
+const logger = getLogger("context-resolver");
+const tracer = getTracer("context-resolver");
+var ContextResolver = class {
+	fetcher;
+	cache;
+	executionContext;
+	constructor(executionContext, credentialStoreRegistry) {
+		this.executionContext = executionContext;
+		this.fetcher = new ContextFetcher(executionContext, credentialStoreRegistry);
+		this.cache = new ContextCache(executionContext);
+		logger.info({
+			tenantId: this.executionContext.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.executionContext.tenantId, this.executionContext.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.executionContext.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.executionContext.tenantId, this.executionContext.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.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.executionContext.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$1) {
+		const contextString = JSON.stringify(headers$1, Object.keys(headers$1).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/domains/run/context/context.d.ts

@@ -0,0 +1,19 @@
+import { ResolvedContext } from "./ContextResolver.js";
+import { CredentialStoreRegistry, FullExecutionContext } from "@inkeep/agents-core";
+
+//#region src/domains/run/context/context.d.ts
+declare function determineContextTrigger(tenantId: string, projectId: string, conversationId: string): Promise<'initialization' | 'invocation'>;
+declare function handleContextConfigChange(executionContext: FullExecutionContext, conversationId: string, newContextConfigId: string, credentialStores?: CredentialStoreRegistry): Promise<void>;
+declare function handleContextResolution({
+  executionContext,
+  conversationId,
+  headers,
+  credentialStores
+}: {
+  executionContext: FullExecutionContext;
+  conversationId: string;
+  headers: Record<string, unknown>;
+  credentialStores?: CredentialStoreRegistry;
+}): Promise<ResolvedContext | null>;
+//#endregion
+export { determineContextTrigger, handleContextConfigChange, handleContextResolution };