@inkeep/agents-run-api 0.0.0-dev-20260113172432 → 0.0.0-dev-20260114183157

package/dist/agents/Agent.js

@@ -19,7 +19,7 @@ import { withJsonPostProcessing } from "../utils/json-postprocessor.js";
 import { calculateBreakdownTotal, estimateTokens } from "../utils/token-estimator.js";
 import { createDelegateToAgentTool, createTransferToAgentTool } from "./relationTools.js";
 import { SystemPromptBuilder } from "./SystemPromptBuilder.js";
-import { Phase1Config } from "./versions/v1/Phase1Config.js";
+import { Phase1Config, V1_BREAKDOWN_SCHEMA } from "./versions/v1/Phase1Config.js";
 import { Phase2Config } from "./versions/v1/Phase2Config.js";
 import { z } from "@hono/zod-openapi";
 import { ContextResolver, CredentialStuffer, MCPServerType, MCPTransportType, McpClient, ModelFactory, TemplateEngine, agentHasArtifactComponents, createMessage, generateId, getContextConfigById, getCredentialReference, getFullAgentDefinition, getFunction, getFunctionToolsForSubAgent, getLedgerArtifacts, getToolsForAgent, getUserScopedCredentialReference, listTaskIdsByContextId, parseEmbeddedJson } from "@inkeep/agents-core";
@@ -1316,20 +1316,10 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 				const conversationId = runtimeContext?.metadata?.conversationId;
 				if (conversationId) this.setConversationId(conversationId);
 				const { conversationHistory, contextBreakdown } = await this.buildConversationHistory(contextId, taskId, userMessage, streamRequestId, initialContextBreakdown);
-				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 breakdownAttributes = {};
+				for (const componentDef of V1_BREAKDOWN_SCHEMA) breakdownAttributes[componentDef.spanAttribute] = contextBreakdown.components[componentDef.key] ?? 0;
+				breakdownAttributes["context.breakdown.total_tokens"] = contextBreakdown.total;
+				span.setAttributes(breakdownAttributes);
 				const { primaryModelSettings, modelSettings, hasStructuredOutput, shouldStreamPhase1, timeoutMs } = this.configureModelSettings();
 				let response;
 				let textResponse;
@@ -1499,8 +1489,11 @@ ${typeof cleanResult === "string" ? cleanResult : JSON.stringify(cleanResult, nu
 		}
 		const conversationHistoryTokens = estimateTokens(conversationHistory);
 		const updatedContextBreakdown = {
-			...initialContextBreakdown,
-			conversationHistory: conversationHistoryTokens
+			components: {
+				...initialContextBreakdown.components,
+				conversationHistory: conversationHistoryTokens
+			},
+			total: initialContextBreakdown.total
 		};
 		calculateBreakdownTotal(updatedContextBreakdown);
 		return {

package/dist/agents/types.d.ts

@@ -1,10 +1,12 @@
 import { AssembleResult } from "../utils/token-estimator.js";
-import { Artifact, ArtifactComponentApiInsert, DataComponentApiInsert } from "@inkeep/agents-core";
+import { Artifact, ArtifactComponentApiInsert, BreakdownComponentDef, DataComponentApiInsert } from "@inkeep/agents-core";
 
 //#region src/agents/types.d.ts
 interface VersionConfig<TConfig> {
   loadTemplates(): Map<string, string>;
   assemble(templates: Map<string, string>, config: TConfig): AssembleResult;
+  /** Returns the breakdown schema defining which components this version tracks */
+  getBreakdownSchema(): BreakdownComponentDef[];
 }
 interface SystemPromptV1 {
   corePrompt: string;
@@ -25,4 +27,4 @@ interface ToolData {
   usageGuidelines?: string;
 }
 //#endregion
-export { SystemPromptV1, ToolData, VersionConfig };
+export { type BreakdownComponentDef, SystemPromptV1, ToolData, VersionConfig };

package/dist/agents/versions/v1/Phase1Config.d.ts

@@ -1,10 +1,11 @@
-import { AssembleResult } from "../../../utils/token-estimator.js";
+import { AssembleResult, BreakdownComponentDef } from "../../../utils/token-estimator.js";
 import { SystemPromptV1, ToolData, VersionConfig } from "../../types.js";
-import { McpTool } from "@inkeep/agents-core";
+import { McpTool, V1_BREAKDOWN_SCHEMA } from "@inkeep/agents-core";
 
 //#region src/agents/versions/v1/Phase1Config.d.ts
 declare class Phase1Config implements VersionConfig<SystemPromptV1> {
   loadTemplates(): Map<string, string>;
+  getBreakdownSchema(): BreakdownComponentDef[];
   static convertMcpToolsToToolData(mcpTools: McpTool[] | undefined): ToolData[];
   private isToolDataArray;
   private normalizeSchema;
@@ -24,4 +25,4 @@ declare class Phase1Config implements VersionConfig<SystemPromptV1> {
   private generateParametersXml;
 }
 //#endregion
-export { Phase1Config };
+export { Phase1Config, V1_BREAKDOWN_SCHEMA };

package/dist/agents/versions/v1/Phase1Config.js

@@ -5,6 +5,7 @@ import thinking_preparation_default from "../../../_virtual/_raw_/home/runner/wo
 import tool_default from "../../../_virtual/_raw_/home/runner/work/agents/agents/agents-run-api/templates/v1/phase1/tool.js";
 import artifact_default from "../../../_virtual/_raw_/home/runner/work/agents/agents/agents-run-api/templates/v1/shared/artifact.js";
 import artifact_retrieval_guidance_default from "../../../_virtual/_raw_/home/runner/work/agents/agents/agents-run-api/templates/v1/shared/artifact-retrieval-guidance.js";
+import { V1_BREAKDOWN_SCHEMA } from "@inkeep/agents-core";
 import { convertZodToJsonSchema, isZodSchema } from "@inkeep/agents-core/utils/schema-conversion";
 
 //#region src/agents/versions/v1/Phase1Config.ts
@@ -19,6 +20,9 @@ var Phase1Config = class Phase1Config {
 		templates.set("thinking-preparation", thinking_preparation_default);
 		return templates;
 	}
+	getBreakdownSchema() {
+		return V1_BREAKDOWN_SCHEMA;
+	}
 	static convertMcpToolsToToolData(mcpTools) {
 		if (!mcpTools || mcpTools.length === 0) return [];
 		const toolData = [];
@@ -45,17 +49,17 @@ var Phase1Config = class Phase1Config {
 		return inputSchema;
 	}
 	assemble(templates, config) {
-		const breakdown = createEmptyBreakdown();
+		const breakdown = createEmptyBreakdown(this.getBreakdownSchema());
 		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}}", ""));
+		breakdown.components["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);
+			breakdown.components["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);
+		breakdown.components["agentPrompt"] = estimateTokens(agentContextSection);
 		systemPrompt = systemPrompt.replace("{{AGENT_CONTEXT_SECTION}}", agentContextSection);
 		const toolData = (this.isToolDataArray(config.tools) ? config.tools : Phase1Config.convertMcpToolsToToolData(config.tools)).map((tool) => ({
 			...tool,
@@ -64,21 +68,25 @@ var Phase1Config = class Phase1Config {
 		const hasArtifactComponents = Boolean(config.artifactComponents && config.artifactComponents.length > 0);
 		const artifactsSection = this.generateArtifactsSection(templates, config.artifacts, hasArtifactComponents, config.artifactComponents, config.hasAgentArtifactComponents);
 		const artifactInstructionsTokens = this.getArtifactInstructionsTokens(templates, hasArtifactComponents, config.artifactComponents, config.hasAgentArtifactComponents, (config.artifacts?.length ?? 0) > 0);
-		breakdown.systemPromptTemplate += artifactInstructionsTokens;
-		breakdown.artifactsSection = estimateTokens(config.artifacts?.length > 0 ? config.artifacts.map((artifact) => this.generateArtifactXml(templates, artifact)).join("\n  ") : "");
-		if (hasArtifactComponents) breakdown.artifactComponents = estimateTokens(this.getArtifactCreationInstructions(hasArtifactComponents, config.artifactComponents));
+		breakdown.components["systemPromptTemplate"] += artifactInstructionsTokens;
+		const actualArtifactsXml = config.artifacts?.length > 0 ? config.artifacts.map((artifact) => this.generateArtifactXml(templates, artifact)).join("\n  ") : "";
+		breakdown.components["artifactsSection"] = estimateTokens(actualArtifactsXml);
+		if (hasArtifactComponents) {
+			const creationInstructions = this.getArtifactCreationInstructions(hasArtifactComponents, config.artifactComponents);
+			breakdown.components["artifactComponents"] = estimateTokens(creationInstructions);
+		}
 		systemPrompt = systemPrompt.replace("{{ARTIFACTS_SECTION}}", artifactsSection);
 		const toolsSection = this.generateToolsSection(templates, toolData);
-		breakdown.toolsSection = estimateTokens(toolsSection);
+		breakdown.components["toolsSection"] = estimateTokens(toolsSection);
 		systemPrompt = systemPrompt.replace("{{TOOLS_SECTION}}", toolsSection);
 		const thinkingPreparationSection = this.generateThinkingPreparationSection(templates, config.isThinkingPreparation);
-		breakdown.thinkingPreparation = estimateTokens(thinkingPreparationSection);
+		breakdown.components["thinkingPreparation"] = estimateTokens(thinkingPreparationSection);
 		systemPrompt = systemPrompt.replace("{{THINKING_PREPARATION_INSTRUCTIONS}}", thinkingPreparationSection);
 		const transferSection = this.generateTransferInstructions(config.hasTransferRelations);
-		breakdown.transferInstructions = estimateTokens(transferSection);
+		breakdown.components["transferInstructions"] = estimateTokens(transferSection);
 		systemPrompt = systemPrompt.replace("{{TRANSFER_INSTRUCTIONS}}", transferSection);
 		const delegationSection = this.generateDelegationInstructions(config.hasDelegateRelations);
-		breakdown.delegationInstructions = estimateTokens(delegationSection);
+		breakdown.components["delegationInstructions"] = estimateTokens(delegationSection);
 		systemPrompt = systemPrompt.replace("{{DELEGATION_INSTRUCTIONS}}", delegationSection);
 		calculateBreakdownTotal(breakdown);
 		return {
@@ -432,4 +440,4 @@ ${creationInstructions}
 };
 
 //#endregion
-export { Phase1Config };
+export { Phase1Config, V1_BREAKDOWN_SCHEMA };

package/dist/create-app.d.ts

@@ -1,9 +1,9 @@
 import { SandboxConfig } from "./types/execution-context.js";
 import { CredentialStoreRegistry, ServerConfig } from "@inkeep/agents-core";
 import { Hono } from "hono";
-import * as hono_types3 from "hono/types";
+import * as hono_types0 from "hono/types";
 
 //#region src/create-app.d.ts
-declare function createExecutionHono(serverConfig: ServerConfig, credentialStores: CredentialStoreRegistry, sandboxConfig?: SandboxConfig): Hono<hono_types3.BlankEnv, hono_types3.BlankSchema, "/">;
+declare function createExecutionHono(serverConfig: ServerConfig, credentialStores: CredentialStoreRegistry, sandboxConfig?: SandboxConfig): Hono<hono_types0.BlankEnv, hono_types0.BlankSchema, "/">;
 //#endregion
 export { createExecutionHono };

package/dist/index.d.ts

@@ -3,14 +3,14 @@ import { createExecutionHono } from "./create-app.js";
 import "./env.js";
 import { CredentialStore, ServerConfig } from "@inkeep/agents-core";
 import { Hono } from "hono";
-import * as hono_types0 from "hono/types";
+import * as hono_types1 from "hono/types";
 
 //#region src/index.d.ts
-declare const app: Hono<hono_types0.BlankEnv, hono_types0.BlankSchema, "/">;
+declare const app: Hono<hono_types1.BlankEnv, hono_types1.BlankSchema, "/">;
 declare function createExecutionApp(config?: {
   serverConfig?: ServerConfig;
   credentialStores?: CredentialStore[];
   sandboxConfig?: SandboxConfig;
-}): Hono<hono_types0.BlankEnv, hono_types0.BlankSchema, "/">;
+}): Hono<hono_types1.BlankEnv, hono_types1.BlankSchema, "/">;
 //#endregion
 export { Hono, type NativeSandboxConfig, type SandboxConfig, type VercelSandboxConfig, createExecutionApp, createExecutionHono, app as default };

package/dist/utils/token-estimator.d.ts

@@ -1,47 +1,8 @@
+import * as _inkeep_agents_core1 from "@inkeep/agents-core";
+import { BreakdownComponentDef, ContextBreakdown, calculateBreakdownTotal, createEmptyBreakdown } from "@inkeep/agents-core";
+
 //#region src/utils/token-estimator.d.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
- */
-/**
- * Breakdown of estimated token usage for each context component.
- * All values are approximate token counts.
- */
-interface ContextBreakdown {
-  /** Base system prompt template tokens */
-  systemPromptTemplate: number;
-  /** Core instructions (corePrompt) tokens */
-  coreInstructions: number;
-  /** Agent-level context (prompt) tokens */
-  agentPrompt: number;
-  /** Tools section (MCP, function, relation tools) tokens */
-  toolsSection: number;
-  /** Artifacts section tokens */
-  artifactsSection: number;
-  /** Data components section tokens (Phase 2) */
-  dataComponents: number;
-  /** Artifact component instructions tokens */
-  artifactComponents: number;
-  /** Transfer instructions tokens */
-  transferInstructions: number;
-  /** Delegation instructions tokens */
-  delegationInstructions: number;
-  /** Thinking preparation instructions tokens */
-  thinkingPreparation: number;
-  /** Conversation history tokens */
-  conversationHistory: number;
-  /** Total estimated tokens */
-  total: number;
-}
-/**
- * Creates an empty context breakdown with all values set to 0.
- */
-declare function createEmptyBreakdown(): ContextBreakdown;
+
 /**
  * Estimates the number of tokens in a text string using character-based approximation.
  *
@@ -49,13 +10,6 @@ declare function createEmptyBreakdown(): ContextBreakdown;
  * @returns Estimated token count (approximately text.length / 4)
  */
 declare function estimateTokens(text: string | undefined | null): number;
-/**
- * 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
- */
-declare function calculateBreakdownTotal(breakdown: ContextBreakdown): ContextBreakdown;
 /**
  * Result from prompt assembly that includes both the prompt and token breakdown.
  */
@@ -63,7 +17,7 @@ interface AssembleResult {
   /** The assembled prompt string */
   prompt: string;
   /** Token breakdown for each component */
-  breakdown: ContextBreakdown;
+  breakdown: _inkeep_agents_core1.ContextBreakdown;
 }
 //#endregion
-export { AssembleResult, ContextBreakdown, calculateBreakdownTotal, createEmptyBreakdown, estimateTokens };
+export { AssembleResult, type BreakdownComponentDef, type ContextBreakdown, calculateBreakdownTotal, createEmptyBreakdown, estimateTokens };

package/dist/utils/token-estimator.js

@@ -1,34 +1,8 @@
+import { calculateBreakdownTotal, createEmptyBreakdown } from "@inkeep/agents-core";
+
 //#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
@@ -38,16 +12,6 @@ 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
 export { calculateBreakdownTotal, createEmptyBreakdown, estimateTokens };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkeep/agents-run-api",
-  "version": "0.0.0-dev-20260113172432",
+  "version": "0.0.0-dev-20260114183157",
   "description": "Agents Run API for Inkeep Agent Framework - handles chat, agent execution, and streaming",
   "types": "dist/index.d.ts",
   "exports": {
@@ -41,7 +41,7 @@
     "hono": "^4.10.4",
     "jmespath": "^0.16.0",
     "llm-info": "^1.0.69",
-    "@inkeep/agents-core": "^0.0.0-dev-20260113172432"
+    "@inkeep/agents-core": "^0.0.0-dev-20260114183157"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.1.5",