@inkeep/agents-run-api 0.0.0-dev-20251222083114 → 0.0.0-dev-20251222193816

package/dist/index.cjs

@@ -4910,6 +4910,58 @@ function getCompressionConfigForModel(modelSettings) {
 	}
 }
 
+//#endregion
+//#region src/utils/token-estimator.ts
+/**
+* Token estimation utility for context tracking.
+*
+* Uses character-based approximation (~4 characters per token) which:
+* - Works universally for all models (OpenAI, Anthropic, Gemini, custom)
+* - Requires no external dependencies
+* - Is fast (simple string length calculation)
+* - Is accurate enough for relative comparisons between context components
+*/
+const CHARS_PER_TOKEN = 4;
+/**
+* Creates an empty context breakdown with all values set to 0.
+*/
+function createEmptyBreakdown() {
+	return {
+		systemPromptTemplate: 0,
+		coreInstructions: 0,
+		agentPrompt: 0,
+		toolsSection: 0,
+		artifactsSection: 0,
+		dataComponents: 0,
+		artifactComponents: 0,
+		transferInstructions: 0,
+		delegationInstructions: 0,
+		thinkingPreparation: 0,
+		conversationHistory: 0,
+		total: 0
+	};
+}
+/**
+* Estimates the number of tokens in a text string using character-based approximation.
+*
+* @param text - The text to estimate tokens for
+* @returns Estimated token count (approximately text.length / 4)
+*/
+function estimateTokens(text) {
+	if (!text) return 0;
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+* Calculates the total from all breakdown components and updates the total field.
+*
+* @param breakdown - The context breakdown to calculate total for
+* @returns The breakdown with updated total
+*/
+function calculateBreakdownTotal(breakdown) {
+	breakdown.total = breakdown.systemPromptTemplate + breakdown.coreInstructions + breakdown.agentPrompt + breakdown.toolsSection + breakdown.artifactsSection + breakdown.dataComponents + breakdown.artifactComponents + breakdown.transferInstructions + breakdown.delegationInstructions + breakdown.thinkingPreparation + breakdown.conversationHistory;
+	return breakdown;
+}
+
 //#endregion
 //#region src/a2a/client.ts
 const logger$12 = (0, __inkeep_agents_core.getLogger)("a2aClient");
@@ -5691,6 +5743,9 @@ var SystemPromptBuilder = class {
 			throw new Error(`Template loading failed: ${error}`);
 		}
 	}
+	/**
+	* Build the system prompt and return both the prompt string and token breakdown
+	*/
 	buildSystemPrompt(config) {
 		this.loadTemplates();
 		this.validateTemplateVariables(config);
@@ -5767,12 +5822,17 @@ var Phase1Config = class Phase1Config {
 		return inputSchema;
 	}
 	assemble(templates, config) {
-		const systemPromptTemplate = templates.get("system-prompt");
-		if (!systemPromptTemplate) throw new Error("System prompt template not loaded");
-		let systemPrompt = systemPromptTemplate;
-		if (config.corePrompt && config.corePrompt.trim()) systemPrompt = systemPrompt.replace("{{CORE_INSTRUCTIONS}}", config.corePrompt);
-		else systemPrompt = systemPrompt.replace(/<core_instructions>\s*\{\{CORE_INSTRUCTIONS\}\}\s*<\/core_instructions>/g, "");
+		const breakdown = createEmptyBreakdown();
+		const systemPromptTemplateContent = templates.get("system-prompt");
+		if (!systemPromptTemplateContent) throw new Error("System prompt template not loaded");
+		breakdown.systemPromptTemplate = estimateTokens(systemPromptTemplateContent.replace("{{CORE_INSTRUCTIONS}}", "").replace("{{AGENT_CONTEXT_SECTION}}", "").replace("{{ARTIFACTS_SECTION}}", "").replace("{{TOOLS_SECTION}}", "").replace("{{THINKING_PREPARATION_INSTRUCTIONS}}", "").replace("{{TRANSFER_INSTRUCTIONS}}", "").replace("{{DELEGATION_INSTRUCTIONS}}", ""));
+		let systemPrompt = systemPromptTemplateContent;
+		if (config.corePrompt && config.corePrompt.trim()) {
+			breakdown.coreInstructions = estimateTokens(config.corePrompt);
+			systemPrompt = systemPrompt.replace("{{CORE_INSTRUCTIONS}}", config.corePrompt);
+		} else systemPrompt = systemPrompt.replace(/<core_instructions>\s*\{\{CORE_INSTRUCTIONS\}\}\s*<\/core_instructions>/g, "");
 		const agentContextSection = this.generateAgentContextSection(config.prompt);
+		breakdown.agentPrompt = estimateTokens(agentContextSection);
 		systemPrompt = systemPrompt.replace("{{AGENT_CONTEXT_SECTION}}", agentContextSection);
 		const toolData = (this.isToolDataArray(config.tools) ? config.tools : Phase1Config.convertMcpToolsToToolData(config.tools)).map((tool$2) => ({
 			...tool$2,
@@ -5780,16 +5840,26 @@ var Phase1Config = class Phase1Config {
 		}));
 		const hasArtifactComponents = config.artifactComponents && config.artifactComponents.length > 0;
 		const artifactsSection = this.generateArtifactsSection(templates, config.artifacts, hasArtifactComponents, config.artifactComponents, config.hasAgentArtifactComponents);
+		breakdown.artifactsSection = estimateTokens(artifactsSection);
+		if (hasArtifactComponents) breakdown.artifactComponents = estimateTokens(this.getArtifactCreationInstructions(hasArtifactComponents, config.artifactComponents));
 		systemPrompt = systemPrompt.replace("{{ARTIFACTS_SECTION}}", artifactsSection);
 		const toolsSection = this.generateToolsSection(templates, toolData);
+		breakdown.toolsSection = estimateTokens(toolsSection);
 		systemPrompt = systemPrompt.replace("{{TOOLS_SECTION}}", toolsSection);
 		const thinkingPreparationSection = this.generateThinkingPreparationSection(templates, config.isThinkingPreparation);
+		breakdown.thinkingPreparation = estimateTokens(thinkingPreparationSection);
 		systemPrompt = systemPrompt.replace("{{THINKING_PREPARATION_INSTRUCTIONS}}", thinkingPreparationSection);
 		const transferSection = this.generateTransferInstructions(config.hasTransferRelations);
+		breakdown.transferInstructions = estimateTokens(transferSection);
 		systemPrompt = systemPrompt.replace("{{TRANSFER_INSTRUCTIONS}}", transferSection);
 		const delegationSection = this.generateDelegationInstructions(config.hasDelegateRelations);
+		breakdown.delegationInstructions = estimateTokens(delegationSection);
 		systemPrompt = systemPrompt.replace("{{DELEGATION_INSTRUCTIONS}}", delegationSection);
-		return systemPrompt;
+		calculateBreakdownTotal(breakdown);
+		return {
+			prompt: systemPrompt,
+			breakdown
+		};
 	}
 	generateAgentContextSection(prompt) {
 		if (!prompt || prompt.trim() === "") return "";
@@ -6612,16 +6682,16 @@ var Agent = class {
 	*/
 	simpleCompression(messages, targetTokens) {
 		if (messages.length === 0) return messages;
-		const estimateTokens = (msg) => {
+		const estimateTokens$1 = (msg) => {
 			const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
 			return Math.ceil(content.length / 4);
 		};
-		let totalTokens = messages.reduce((sum, msg) => sum + estimateTokens(msg), 0);
+		let totalTokens = messages.reduce((sum, msg) => sum + estimateTokens$1(msg), 0);
 		if (totalTokens <= targetTokens) return messages;
 		const result = [...messages];
 		while (totalTokens > targetTokens && result.length > 1) {
 			const dropped = result.shift();
-			if (dropped) totalTokens -= estimateTokens(dropped);
+			if (dropped) totalTokens -= estimateTokens$1(dropped);
 		}
 		return result;
 	}
@@ -7753,7 +7823,7 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 				if (streamRequestId && this.artifactComponents.length > 0) agentSessionManager.updateArtifactComponents(streamRequestId, this.artifactComponents);
 				const conversationId = runtimeContext?.metadata?.conversationId;
 				if (conversationId) this.setConversationId(conversationId);
-				const [mcpTools, systemPrompt, thinkingSystemPrompt, functionTools, relationTools, defaultTools] = await tracer.startActiveSpan("agent.load_tools", { attributes: {
+				const [mcpTools, systemPromptResult, thinkingSystemPromptResult, functionTools, relationTools, defaultTools] = await tracer.startActiveSpan("agent.load_tools", { attributes: {
 					"subAgent.name": this.config.name,
 					"session.id": sessionId || "none"
 				} }, async (childSpan) => {
@@ -7775,6 +7845,9 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 						childSpan.end();
 					}
 				});
+				const systemPrompt = systemPromptResult.prompt;
+				const thinkingSystemPrompt = thinkingSystemPromptResult.prompt;
+				const contextBreakdown = systemPromptResult.breakdown;
 				const allTools = {
 					...mcpTools,
 					...functionTools,
@@ -7812,6 +7885,22 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 						}
 					});
 				}
+				contextBreakdown.conversationHistory = estimateTokens(conversationHistory);
+				calculateBreakdownTotal(contextBreakdown);
+				span.setAttributes({
+					"context.breakdown.system_template_tokens": contextBreakdown.systemPromptTemplate,
+					"context.breakdown.core_instructions_tokens": contextBreakdown.coreInstructions,
+					"context.breakdown.agent_prompt_tokens": contextBreakdown.agentPrompt,
+					"context.breakdown.tools_tokens": contextBreakdown.toolsSection,
+					"context.breakdown.artifacts_tokens": contextBreakdown.artifactsSection,
+					"context.breakdown.data_components_tokens": contextBreakdown.dataComponents,
+					"context.breakdown.artifact_components_tokens": contextBreakdown.artifactComponents,
+					"context.breakdown.transfer_instructions_tokens": contextBreakdown.transferInstructions,
+					"context.breakdown.delegation_instructions_tokens": contextBreakdown.delegationInstructions,
+					"context.breakdown.thinking_preparation_tokens": contextBreakdown.thinkingPreparation,
+					"context.breakdown.conversation_history_tokens": contextBreakdown.conversationHistory,
+					"context.breakdown.total_tokens": contextBreakdown.total
+				});
 				const primaryModelSettings = this.getPrimaryModel();
 				const modelSettings = __inkeep_agents_core.ModelFactory.prepareGenerationConfig(primaryModelSettings);
 				let response;

package/dist/index.js

@@ -4906,6 +4906,58 @@ function getCompressionConfigForModel(modelSettings) {
 	}
 }
 
+//#endregion
+//#region src/utils/token-estimator.ts
+/**
+* Token estimation utility for context tracking.
+*
+* Uses character-based approximation (~4 characters per token) which:
+* - Works universally for all models (OpenAI, Anthropic, Gemini, custom)
+* - Requires no external dependencies
+* - Is fast (simple string length calculation)
+* - Is accurate enough for relative comparisons between context components
+*/
+const CHARS_PER_TOKEN = 4;
+/**
+* Creates an empty context breakdown with all values set to 0.
+*/
+function createEmptyBreakdown() {
+	return {
+		systemPromptTemplate: 0,
+		coreInstructions: 0,
+		agentPrompt: 0,
+		toolsSection: 0,
+		artifactsSection: 0,
+		dataComponents: 0,
+		artifactComponents: 0,
+		transferInstructions: 0,
+		delegationInstructions: 0,
+		thinkingPreparation: 0,
+		conversationHistory: 0,
+		total: 0
+	};
+}
+/**
+* Estimates the number of tokens in a text string using character-based approximation.
+*
+* @param text - The text to estimate tokens for
+* @returns Estimated token count (approximately text.length / 4)
+*/
+function estimateTokens(text) {
+	if (!text) return 0;
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+* Calculates the total from all breakdown components and updates the total field.
+*
+* @param breakdown - The context breakdown to calculate total for
+* @returns The breakdown with updated total
+*/
+function calculateBreakdownTotal(breakdown) {
+	breakdown.total = breakdown.systemPromptTemplate + breakdown.coreInstructions + breakdown.agentPrompt + breakdown.toolsSection + breakdown.artifactsSection + breakdown.dataComponents + breakdown.artifactComponents + breakdown.transferInstructions + breakdown.delegationInstructions + breakdown.thinkingPreparation + breakdown.conversationHistory;
+	return breakdown;
+}
+
 //#endregion
 //#region src/a2a/client.ts
 const logger$12 = getLogger("a2aClient");
@@ -5687,6 +5739,9 @@ var SystemPromptBuilder = class {
 			throw new Error(`Template loading failed: ${error}`);
 		}
 	}
+	/**
+	* Build the system prompt and return both the prompt string and token breakdown
+	*/
 	buildSystemPrompt(config) {
 		this.loadTemplates();
 		this.validateTemplateVariables(config);
@@ -5763,12 +5818,17 @@ var Phase1Config = class Phase1Config {
 		return inputSchema;
 	}
 	assemble(templates, config) {
-		const systemPromptTemplate = templates.get("system-prompt");
-		if (!systemPromptTemplate) throw new Error("System prompt template not loaded");
-		let systemPrompt = systemPromptTemplate;
-		if (config.corePrompt && config.corePrompt.trim()) systemPrompt = systemPrompt.replace("{{CORE_INSTRUCTIONS}}", config.corePrompt);
-		else systemPrompt = systemPrompt.replace(/<core_instructions>\s*\{\{CORE_INSTRUCTIONS\}\}\s*<\/core_instructions>/g, "");
+		const breakdown = createEmptyBreakdown();
+		const systemPromptTemplateContent = templates.get("system-prompt");
+		if (!systemPromptTemplateContent) throw new Error("System prompt template not loaded");
+		breakdown.systemPromptTemplate = estimateTokens(systemPromptTemplateContent.replace("{{CORE_INSTRUCTIONS}}", "").replace("{{AGENT_CONTEXT_SECTION}}", "").replace("{{ARTIFACTS_SECTION}}", "").replace("{{TOOLS_SECTION}}", "").replace("{{THINKING_PREPARATION_INSTRUCTIONS}}", "").replace("{{TRANSFER_INSTRUCTIONS}}", "").replace("{{DELEGATION_INSTRUCTIONS}}", ""));
+		let systemPrompt = systemPromptTemplateContent;
+		if (config.corePrompt && config.corePrompt.trim()) {
+			breakdown.coreInstructions = estimateTokens(config.corePrompt);
+			systemPrompt = systemPrompt.replace("{{CORE_INSTRUCTIONS}}", config.corePrompt);
+		} else systemPrompt = systemPrompt.replace(/<core_instructions>\s*\{\{CORE_INSTRUCTIONS\}\}\s*<\/core_instructions>/g, "");
 		const agentContextSection = this.generateAgentContextSection(config.prompt);
+		breakdown.agentPrompt = estimateTokens(agentContextSection);
 		systemPrompt = systemPrompt.replace("{{AGENT_CONTEXT_SECTION}}", agentContextSection);
 		const toolData = (this.isToolDataArray(config.tools) ? config.tools : Phase1Config.convertMcpToolsToToolData(config.tools)).map((tool$1) => ({
 			...tool$1,
@@ -5776,16 +5836,26 @@ var Phase1Config = class Phase1Config {
 		}));
 		const hasArtifactComponents = config.artifactComponents && config.artifactComponents.length > 0;
 		const artifactsSection = this.generateArtifactsSection(templates, config.artifacts, hasArtifactComponents, config.artifactComponents, config.hasAgentArtifactComponents);
+		breakdown.artifactsSection = estimateTokens(artifactsSection);
+		if (hasArtifactComponents) breakdown.artifactComponents = estimateTokens(this.getArtifactCreationInstructions(hasArtifactComponents, config.artifactComponents));
 		systemPrompt = systemPrompt.replace("{{ARTIFACTS_SECTION}}", artifactsSection);
 		const toolsSection = this.generateToolsSection(templates, toolData);
+		breakdown.toolsSection = estimateTokens(toolsSection);
 		systemPrompt = systemPrompt.replace("{{TOOLS_SECTION}}", toolsSection);
 		const thinkingPreparationSection = this.generateThinkingPreparationSection(templates, config.isThinkingPreparation);
+		breakdown.thinkingPreparation = estimateTokens(thinkingPreparationSection);
 		systemPrompt = systemPrompt.replace("{{THINKING_PREPARATION_INSTRUCTIONS}}", thinkingPreparationSection);
 		const transferSection = this.generateTransferInstructions(config.hasTransferRelations);
+		breakdown.transferInstructions = estimateTokens(transferSection);
 		systemPrompt = systemPrompt.replace("{{TRANSFER_INSTRUCTIONS}}", transferSection);
 		const delegationSection = this.generateDelegationInstructions(config.hasDelegateRelations);
+		breakdown.delegationInstructions = estimateTokens(delegationSection);
 		systemPrompt = systemPrompt.replace("{{DELEGATION_INSTRUCTIONS}}", delegationSection);
-		return systemPrompt;
+		calculateBreakdownTotal(breakdown);
+		return {
+			prompt: systemPrompt,
+			breakdown
+		};
 	}
 	generateAgentContextSection(prompt) {
 		if (!prompt || prompt.trim() === "") return "";
@@ -6608,16 +6678,16 @@ var Agent = class {
 	*/
 	simpleCompression(messages, targetTokens) {
 		if (messages.length === 0) return messages;
-		const estimateTokens = (msg) => {
+		const estimateTokens$1 = (msg) => {
 			const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
 			return Math.ceil(content.length / 4);
 		};
-		let totalTokens = messages.reduce((sum, msg) => sum + estimateTokens(msg), 0);
+		let totalTokens = messages.reduce((sum, msg) => sum + estimateTokens$1(msg), 0);
 		if (totalTokens <= targetTokens) return messages;
 		const result = [...messages];
 		while (totalTokens > targetTokens && result.length > 1) {
 			const dropped = result.shift();
-			if (dropped) totalTokens -= estimateTokens(dropped);
+			if (dropped) totalTokens -= estimateTokens$1(dropped);
 		}
 		return result;
 	}
@@ -7749,7 +7819,7 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 				if (streamRequestId && this.artifactComponents.length > 0) agentSessionManager.updateArtifactComponents(streamRequestId, this.artifactComponents);
 				const conversationId = runtimeContext?.metadata?.conversationId;
 				if (conversationId) this.setConversationId(conversationId);
-				const [mcpTools, systemPrompt, thinkingSystemPrompt, functionTools, relationTools, defaultTools] = await tracer.startActiveSpan("agent.load_tools", { attributes: {
+				const [mcpTools, systemPromptResult, thinkingSystemPromptResult, functionTools, relationTools, defaultTools] = await tracer.startActiveSpan("agent.load_tools", { attributes: {
 					"subAgent.name": this.config.name,
 					"session.id": sessionId || "none"
 				} }, async (childSpan) => {
@@ -7771,6 +7841,9 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 						childSpan.end();
 					}
 				});
+				const systemPrompt = systemPromptResult.prompt;
+				const thinkingSystemPrompt = thinkingSystemPromptResult.prompt;
+				const contextBreakdown = systemPromptResult.breakdown;
 				const allTools = {
 					...mcpTools,
 					...functionTools,
@@ -7808,6 +7881,22 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 						}
 					});
 				}
+				contextBreakdown.conversationHistory = estimateTokens(conversationHistory);
+				calculateBreakdownTotal(contextBreakdown);
+				span.setAttributes({
+					"context.breakdown.system_template_tokens": contextBreakdown.systemPromptTemplate,
+					"context.breakdown.core_instructions_tokens": contextBreakdown.coreInstructions,
+					"context.breakdown.agent_prompt_tokens": contextBreakdown.agentPrompt,
+					"context.breakdown.tools_tokens": contextBreakdown.toolsSection,
+					"context.breakdown.artifacts_tokens": contextBreakdown.artifactsSection,
+					"context.breakdown.data_components_tokens": contextBreakdown.dataComponents,
+					"context.breakdown.artifact_components_tokens": contextBreakdown.artifactComponents,
+					"context.breakdown.transfer_instructions_tokens": contextBreakdown.transferInstructions,
+					"context.breakdown.delegation_instructions_tokens": contextBreakdown.delegationInstructions,
+					"context.breakdown.thinking_preparation_tokens": contextBreakdown.thinkingPreparation,
+					"context.breakdown.conversation_history_tokens": contextBreakdown.conversationHistory,
+					"context.breakdown.total_tokens": contextBreakdown.total
+				});
 				const primaryModelSettings = this.getPrimaryModel();
 				const modelSettings = ModelFactory.prepareGenerationConfig(primaryModelSettings);
 				let response;