@inkeep/agents-cli 0.58.10 → 0.58.12

package/dist/commands/pull-v4/introspect-generator.js

@@ -1,23 +1,27 @@
-import { buildComponentFileName, collectTemplateVariableNames, createInMemoryProject, isPlainObject, toCamelCase } from "./utils.js";
+import { buildComponentFileName, collectTemplateVariableNames, createInMemoryProject, isHumanReadableId, isPlainObject, toCamelCase, toCredentialReferenceName, toKebabCase, toToolReferenceName } from "./utils.js";
 import { buildComponentRegistryFromParsing } from "./component-parser.js";
 import { generateAgentDefinition } from "./generators/agent-generator.js";
 import { generateArtifactComponentDefinition } from "./generators/artifact-component-generator.js";
 import { generateContextConfigDefinition } from "./generators/context-config-generator.js";
 import { generateCredentialDefinition } from "./generators/credential-generator.js";
 import { generateDataComponentDefinition } from "./generators/data-component-generator.js";
+import { generateEnvironmentIndexDefinition, generateEnvironmentSettingsDefinition } from "./generators/environment-generator.js";
+import { generateExternalAgentDefinition } from "./generators/external-agent-generator.js";
+import { generateFunctionToolDefinition } from "./generators/function-tool-generator.js";
 import { generateMcpToolDefinition } from "./generators/mcp-tool-generator.js";
 import { generateProjectDefinition } from "./generators/project-generator.js";
 import { generateStatusComponentDefinition } from "./generators/status-component-generator.js";
+import { resolveSubAgentVariableName } from "./generators/sub-agent-generator.helpers.js";
 import { generateSubAgentDefinition } from "./generators/sub-agent-generator.js";
 import { generateTriggerDefinition } from "./generators/trigger-generator.js";
 import { mergeGeneratedModule } from "./module-merge.js";
 import { generateScheduledTriggerDefinition } from "./scheduled-trigger-generator.js";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { Node, SyntaxKind } from "ts-morph";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 
 //#region src/commands/pull-v4/introspect-generator.ts
-async function introspectGenerate({ project, paths, writeMode = "merge", failOnUnsupportedComponents = false, debug = false }) {
+async function introspectGenerate({ project, paths, writeMode = "merge", debug = false }) {
 	validateProject(project);
 	const skippedAgents = [];
 	const context = {
@@ -27,7 +31,6 @@ async function introspectGenerate({ project, paths, writeMode = "merge", failOnU
 		existingComponentRegistry: writeMode === "merge" ? buildComponentRegistryFromParsing(paths.projectRoot, debug) : void 0
 	};
 	const tasks = createGenerationTasks();
-	const failures = [];
 	const generatedFiles = [];
 	for (const task of tasks) {
 		const records = task.collect(context);
@@ -37,13 +40,9 @@ async function introspectGenerate({ project, paths, writeMode = "merge", failOnU
 			generatedFiles.push(record.filePath);
 		}
 	}
-	const unsupportedCounts = collectUnsupportedComponentCounts(project);
-	if (failOnUnsupportedComponents && hasUnsupportedComponents(unsupportedCounts)) failures.push(formatUnsupportedComponentsError(unsupportedCounts));
-	if (failures.length > 0) throw new Error(`Inkeep Pull failed:\n${failures.join("\n")}`);
 	if (debug) {
 		console.log(`Generated ${generatedFiles.length} files`);
-		if (skippedAgents.length > 0) console.log(`Skipped ${skippedAgents.length} agent(s): ${skippedAgents.map((agent) => `${agent.id} (${agent.reason})`).join(", ")}`);
-		if (hasUnsupportedComponents(unsupportedCounts)) console.log(formatUnsupportedComponentsWarning(unsupportedCounts));
+		if (skippedAgents.length) console.log(`Skipped ${skippedAgents.length} agent(s): ${skippedAgents.map((agent) => `${agent.id} (${agent.reason})`).join(", ")}`);
 	}
 }
 function createGenerationTasks() {
@@ -53,6 +52,16 @@ function createGenerationTasks() {
 			collect: collectCredentialRecords,
 			generate: generateCredentialDefinition
 		},
+		{
+			type: "environment-settings",
+			collect: collectEnvironmentSettingsRecords,
+			generate: generateEnvironmentSettingsRecord
+		},
+		{
+			type: "environment-index",
+			collect: collectEnvironmentIndexRecords,
+			generate: generateEnvironmentIndexDefinition
+		},
 		{
 			type: "artifact-component",
 			collect: collectArtifactComponentRecords,
@@ -63,11 +72,21 @@ function createGenerationTasks() {
 			collect: collectDataComponentRecords,
 			generate: generateDataComponentDefinition
 		},
+		{
+			type: "function-tool",
+			collect: collectFunctionToolRecords,
+			generate: generateFunctionToolDefinition
+		},
 		{
 			type: "tool",
 			collect: collectToolRecords,
 			generate: generateMcpToolDefinition
 		},
+		{
+			type: "external-agent",
+			collect: collectExternalAgentRecords,
+			generate: generateExternalAgentDefinition
+		},
 		{
 			type: "context-config",
 			collect: collectContextConfigRecords,
@@ -107,15 +126,49 @@ function createGenerationTasks() {
 }
 function collectCredentialRecords(context) {
 	if (!context.project.credentialReferences) return [];
-	return Object.entries(context.project.credentialReferences).map(([credentialId, credentialData]) => ({
+	const credentialEntries = Object.entries(context.project.credentialReferences);
+	const fileNamesByCredentialId = buildSequentialNameFileNames(credentialEntries);
+	return credentialEntries.map(([credentialId, credentialData]) => ({
 		id: credentialId,
-		filePath: resolveRecordFilePath(context, "credentials", credentialId, join(context.paths.credentialsDir, buildComponentFileName(credentialId, credentialData.name ?? void 0))),
+		filePath: resolveRecordFilePath(context, "credentials", credentialId, join(context.paths.credentialsDir, fileNamesByCredentialId[credentialId])),
 		payload: {
 			credentialId,
 			...credentialData
 		}
 	}));
 }
+function collectEnvironmentSettingsRecords(context) {
+	const credentialReferenceIds = collectEnvironmentCredentialReferenceIds(context.project);
+	if (credentialReferenceIds.length === 0) return [];
+	const credentialsById = {};
+	for (const credentialReferenceId of credentialReferenceIds) {
+		const credentialData = context.project.credentialReferences?.[credentialReferenceId];
+		if (isPlainObject(credentialData)) {
+			credentialsById[credentialReferenceId] = {
+				...credentialData,
+				id: credentialReferenceId
+			};
+			continue;
+		}
+		credentialsById[credentialReferenceId] = { id: credentialReferenceId };
+	}
+	return [{
+		id: "development",
+		filePath: resolveRecordFilePath(context, "environments", "development", join(context.paths.environmentsDir, "development.env.ts")),
+		payload: { credentials: credentialsById }
+	}];
+}
+function collectEnvironmentIndexRecords(context) {
+	if (collectEnvironmentCredentialReferenceIds(context.project).length === 0) return [];
+	return [{
+		id: "index",
+		filePath: resolveRecordFilePath(context, "environments", "index", join(context.paths.environmentsDir, "index.ts")),
+		payload: ["development"]
+	}];
+}
+function generateEnvironmentSettingsRecord(payload) {
+	return generateEnvironmentSettingsDefinition("development", payload);
+}
 function collectArtifactComponentRecords(context) {
 	if (!context.project.artifactComponents) return [];
 	return Object.entries(context.project.artifactComponents).map(([artifactComponentId, artifactComponentData]) => ({
@@ -128,15 +181,45 @@ function collectArtifactComponentRecords(context) {
 	}));
 }
 function collectDataComponentRecords(context) {
-	if (!context.project.dataComponents) return [];
-	return Object.entries(context.project.dataComponents).map(([dataComponentId, dataComponent]) => ({
+	const recordsByDataComponentId = /* @__PURE__ */ new Map();
+	for (const [dataComponentId, dataComponent] of Object.entries(context.project.dataComponents ?? {})) recordsByDataComponentId.set(dataComponentId, {
 		id: dataComponentId,
 		filePath: resolveRecordFilePath(context, "dataComponents", dataComponentId, join(context.paths.dataComponentsDir, buildComponentFileName(dataComponentId, dataComponent.name ?? void 0))),
 		payload: {
 			dataComponentId,
 			...dataComponent
 		}
-	}));
+	});
+	for (const dataComponentId of collectReferencedSubAgentComponentIds(context, "dataComponents")) {
+		if (recordsByDataComponentId.has(dataComponentId)) continue;
+		recordsByDataComponentId.set(dataComponentId, {
+			id: dataComponentId,
+			filePath: resolveRecordFilePath(context, "dataComponents", dataComponentId, join(context.paths.dataComponentsDir, `${dataComponentId}.ts`)),
+			payload: {
+				dataComponentId,
+				name: dataComponentId,
+				props: {
+					type: "object",
+					properties: {}
+				}
+			}
+		});
+	}
+	return [...recordsByDataComponentId.values()];
+}
+function collectReferencedSubAgentComponentIds(context, componentProperty) {
+	const componentIds = /* @__PURE__ */ new Set();
+	for (const agentId of context.completeAgentIds) {
+		const agentData = context.project.agents?.[agentId];
+		const subAgents = asRecord(agentData?.subAgents);
+		if (!subAgents) continue;
+		for (const subAgentData of Object.values(subAgents)) {
+			const subAgentRecord = asRecord(subAgentData);
+			if (!subAgentRecord) continue;
+			for (const componentId of extractReferenceIds(subAgentRecord[componentProperty])) componentIds.add(componentId);
+		}
+	}
+	return [...componentIds];
 }
 function collectContextConfigRecords(context) {
 	if (!context.project.agents) return [];
@@ -151,6 +234,7 @@ function collectContextConfigRecords(context) {
 		if (!contextConfigRecordsById.has(contextConfigId)) {
 			const contextConfigFilePath = resolveRecordFilePath(context, "contextConfigs", contextConfigId, join(context.paths.contextConfigsDir, `${contextConfigId}.ts`));
 			const credentialReferenceOverrides = collectContextConfigCredentialReferenceOverrides(context, normalizedContextConfig);
+			const credentialReferencePathOverrides = collectContextConfigCredentialReferencePathOverrides(context, normalizedContextConfig);
 			const headersReferenceOverride = collectContextConfigHeadersReferenceOverride(context, contextConfigId, contextConfigFilePath);
 			contextConfigRecordsById.set(contextConfigId, {
 				id: contextConfigId,
@@ -158,39 +242,166 @@ function collectContextConfigRecords(context) {
 				payload: {
 					contextConfigId,
 					...normalizedContextConfig,
-					...headersReferenceOverride && { headers: headersReferenceOverride },
-					...credentialReferenceOverrides && { referenceOverrides: { credentialReferences: credentialReferenceOverrides } }
+					...headersReferenceOverride && { headersReference: headersReferenceOverride },
+					...credentialReferenceOverrides && { referenceOverrides: { credentialReferences: credentialReferenceOverrides } },
+					...credentialReferencePathOverrides && { referencePathOverrides: { credentialReferences: credentialReferencePathOverrides } }
 				}
 			});
 		}
 	}
 	return [...contextConfigRecordsById.values()];
 }
+function collectFunctionToolRecords(context) {
+	const functionToolEntries = collectFunctionToolEntries(context.project);
+	if (!functionToolEntries.length) return [];
+	const fileNamesByFunctionToolId = buildSequentialNameFileNames(functionToolEntries.map(({ functionToolId, fileName }) => [functionToolId, { name: fileName }]));
+	return functionToolEntries.map(({ functionToolId, functionToolData, functionData }) => {
+		const modulePath = stripExtension(fileNamesByFunctionToolId[functionToolId]);
+		const functionToolName = typeof functionToolData.name === "string" && functionToolData.name.length > 0 ? functionToolData.name : typeof functionData.name === "string" && functionData.name.length > 0 ? functionData.name : void 0;
+		const functionToolDescription = typeof functionToolData.description === "string" ? functionToolData.description : typeof functionData.description === "string" ? functionData.description : void 0;
+		return {
+			id: functionToolId,
+			filePath: resolveRecordFilePath(context, "functionTools", functionToolId, join(context.paths.toolsDir, `${modulePath}.ts`)),
+			payload: {
+				functionToolId,
+				...functionToolName && { name: functionToolName },
+				...functionToolDescription !== void 0 && { description: functionToolDescription },
+				...functionData.inputSchema !== void 0 && { inputSchema: functionData.inputSchema },
+				...functionData.schema !== void 0 && { schema: functionData.schema },
+				...functionData.executeCode !== void 0 && { executeCode: functionData.executeCode },
+				...functionData.dependencies !== void 0 && { dependencies: functionData.dependencies }
+			}
+		};
+	});
+}
+function collectFunctionToolEntries(project) {
+	const functionToolsById = collectFunctionToolsById(project);
+	const functionsById = collectFunctionsById(project);
+	const entries = [];
+	for (const [functionToolId, functionToolData] of Object.entries(functionToolsById)) {
+		const functionId = typeof functionToolData.functionId === "string" && functionToolData.functionId.length > 0 ? functionToolData.functionId : functionToolId;
+		const functionData = functionsById[functionId] ?? {};
+		const functionToolName = typeof functionToolData.name === "string" && functionToolData.name.length > 0 ? functionToolData.name : void 0;
+		const functionName = typeof functionData.name === "string" && functionData.name.length > 0 ? functionData.name : void 0;
+		const fallbackName = functionToolName ?? functionName ?? functionToolId;
+		entries.push({
+			functionToolId,
+			functionId,
+			functionToolData,
+			functionData,
+			exportName: fallbackName,
+			fileName: fallbackName
+		});
+	}
+	return entries;
+}
+function collectFunctionToolsById(project) {
+	const functionToolsById = {};
+	for (const [functionToolId, functionToolData] of Object.entries(project.functionTools ?? {})) {
+		const functionToolRecord = asRecord(functionToolData);
+		if (!functionToolRecord) continue;
+		functionToolsById[functionToolId] = { ...functionToolRecord };
+	}
+	for (const agentData of Object.values(project.agents ?? {})) {
+		const agentFunctionTools = asRecord(asRecord(agentData)?.functionTools);
+		if (!agentFunctionTools) continue;
+		for (const [functionToolId, functionToolData] of Object.entries(agentFunctionTools)) {
+			const functionToolRecord = asRecord(functionToolData);
+			if (!functionToolRecord) continue;
+			const existingFunctionTool = functionToolsById[functionToolId] ?? {};
+			functionToolsById[functionToolId] = {
+				...functionToolRecord,
+				...existingFunctionTool
+			};
+		}
+	}
+	return functionToolsById;
+}
+function collectFunctionsById(project) {
+	const functionsById = {};
+	for (const [functionId, functionData] of Object.entries(project.functions ?? {})) {
+		const functionRecord = asRecord(functionData);
+		if (!functionRecord) continue;
+		functionsById[functionId] = { ...functionRecord };
+	}
+	for (const agentData of Object.values(project.agents ?? {})) {
+		const agentFunctions = asRecord(asRecord(agentData)?.functions);
+		if (!agentFunctions) continue;
+		for (const [functionId, functionData] of Object.entries(agentFunctions)) {
+			const functionRecord = asRecord(functionData);
+			if (!functionRecord) continue;
+			const existingFunction = functionsById[functionId] ?? {};
+			functionsById[functionId] = {
+				...functionRecord,
+				...existingFunction
+			};
+		}
+	}
+	return functionsById;
+}
 function collectToolRecords(context) {
-	return Object.entries(context.project.tools ?? {}).map(([toolId, toolData]) => ({
+	const toolEntries = Object.entries(context.project.tools ?? {});
+	const fileNamesByToolId = buildSequentialNameFileNames(toolEntries);
+	return toolEntries.map(([toolId, toolData]) => ({
 		id: toolId,
-		filePath: resolveRecordFilePath(context, "tools", toolId, join(context.paths.toolsDir, buildComponentFileName(toolId, toolData.name ?? void 0))),
+		filePath: resolveRecordFilePath(context, "tools", toolId, join(context.paths.toolsDir, fileNamesByToolId[toolId])),
 		payload: {
 			mcpToolId: toolId,
 			...toolData
 		}
 	}));
 }
+function collectExternalAgentRecords(context) {
+	const externalAgentEntries = Object.entries(context.project.externalAgents ?? {});
+	const fileNamesByExternalAgentId = buildSequentialNameFileNames(externalAgentEntries.map(([externalAgentId, externalAgentData]) => [externalAgentId, { name: resolveExternalAgentNamingSeed(externalAgentId, externalAgentData) }]));
+	const referenceNamesByExternalAgentId = buildExternalAgentReferenceNamesById(context.project);
+	return externalAgentEntries.map(([externalAgentId, externalAgentData]) => {
+		const externalAgentRecord = asRecord(externalAgentData) ?? {};
+		return {
+			id: externalAgentId,
+			filePath: resolveRecordFilePath(context, "externalAgents", externalAgentId, join(context.paths.externalAgentsDir, fileNamesByExternalAgentId[externalAgentId])),
+			payload: {
+				externalAgentId,
+				externalAgentReferenceName: referenceNamesByExternalAgentId[externalAgentId],
+				...externalAgentRecord
+			}
+		};
+	});
+}
 function collectContextConfigCredentialReferenceOverrides(context, contextConfigData) {
-	const registry = context.existingComponentRegistry;
-	if (!registry) return;
 	const contextVariables = asRecord(contextConfigData.contextVariables);
 	if (!contextVariables) return;
+	const credentialReferenceNamesById = buildCredentialReferenceNamesById(context.project);
+	const registry = context.existingComponentRegistry;
 	const overrides = {};
 	for (const contextVariable of Object.values(contextVariables)) {
 		const contextVariableRecord = asRecord(contextVariable);
 		const credentialReferenceId = contextVariableRecord && typeof contextVariableRecord.credentialReferenceId === "string" ? contextVariableRecord.credentialReferenceId : void 0;
 		if (!credentialReferenceId) continue;
-		const existingCredential = registry.get(credentialReferenceId, "credentials");
+		const credentialReferenceName = credentialReferenceNamesById[credentialReferenceId];
+		if (credentialReferenceName) overrides[credentialReferenceId] = credentialReferenceName;
+		const existingCredential = registry?.get(credentialReferenceId, "credentials");
 		if (existingCredential?.name) overrides[credentialReferenceId] = existingCredential.name;
 	}
 	return Object.keys(overrides).length ? overrides : void 0;
 }
+function collectContextConfigCredentialReferencePathOverrides(context, contextConfigData) {
+	const contextVariables = asRecord(contextConfigData.contextVariables);
+	if (!contextVariables) return;
+	const credentialReferencePathById = buildCredentialReferencePathById(context.project);
+	const registry = context.existingComponentRegistry;
+	const overrides = {};
+	for (const contextVariable of Object.values(contextVariables)) {
+		const contextVariableRecord = asRecord(contextVariable);
+		const credentialReferenceId = contextVariableRecord && typeof contextVariableRecord.credentialReferenceId === "string" ? contextVariableRecord.credentialReferenceId : void 0;
+		if (!credentialReferenceId) continue;
+		const credentialReferencePath = credentialReferencePathById[credentialReferenceId];
+		if (credentialReferencePath) overrides[credentialReferenceId] = credentialReferencePath;
+		const existingCredential = registry?.get(credentialReferenceId, "credentials");
+		if (existingCredential?.filePath) overrides[credentialReferenceId] = stripExtension(basename(existingCredential.filePath));
+	}
+	return Object.keys(overrides).length ? overrides : void 0;
+}
 function collectContextConfigHeadersReferenceOverride(context, contextConfigId, filePath) {
 	if (!context.existingComponentRegistry || !existsSync(filePath)) return;
 	const sourceFile = createInMemoryProject().createSourceFile("existing-context-config.ts", readFileSync(filePath, "utf8"), { overwrite: true });
@@ -222,18 +433,35 @@ function collectContextConfigHeadersReferenceOverride(context, contextConfigId,
 }
 function collectTriggerRecords(context) {
 	if (!context.project.agents) return [];
+	const credentialReferenceNamesById = buildCredentialReferenceNamesById(context.project);
+	const credentialReferencePathsById = buildCredentialReferencePathById(context.project);
 	const records = [];
 	for (const agentId of context.completeAgentIds) {
 		const agentData = context.project.agents[agentId];
 		if (!agentData?.triggers) continue;
-		for (const [triggerId, triggerData] of Object.entries(agentData.triggers)) records.push({
-			id: triggerId,
-			filePath: resolveRecordFilePath(context, "triggers", triggerId, join(context.paths.agentsDir, "triggers", buildComponentFileName(triggerId, triggerData.name ?? void 0))),
-			payload: {
-				triggerId,
-				...triggerData
+		const triggerEntries = Object.entries(agentData.triggers);
+		const fileNamesByTriggerId = buildSequentialNameFileNames(triggerEntries);
+		for (const [triggerId, triggerData] of triggerEntries) {
+			const triggerRecord = asRecord(triggerData);
+			const signingSecretCredentialReferenceId = typeof triggerRecord?.signingSecretCredentialReferenceId === "string" ? triggerRecord.signingSecretCredentialReferenceId : void 0;
+			let signingSecretCredentialReferenceName = signingSecretCredentialReferenceId ? credentialReferenceNamesById[signingSecretCredentialReferenceId] : void 0;
+			let signingSecretCredentialReferencePath = signingSecretCredentialReferenceId ? credentialReferencePathsById[signingSecretCredentialReferenceId] : void 0;
+			if (signingSecretCredentialReferenceId && context.existingComponentRegistry) {
+				const existingCredential = context.existingComponentRegistry.get(signingSecretCredentialReferenceId, "credentials");
+				if (existingCredential?.name) signingSecretCredentialReferenceName = existingCredential.name;
+				if (existingCredential?.filePath) signingSecretCredentialReferencePath = stripExtension(basename(existingCredential.filePath));
 			}
-		});
+			records.push({
+				id: triggerId,
+				filePath: resolveRecordFilePath(context, "triggers", triggerId, join(context.paths.agentsDir, "triggers", fileNamesByTriggerId[triggerId])),
+				payload: {
+					triggerId,
+					...triggerData,
+					...signingSecretCredentialReferenceName && { signingSecretCredentialReferenceName },
+					...signingSecretCredentialReferencePath && { signingSecretCredentialReferencePath }
+				}
+			});
+		}
 	}
 	return records;
 }
@@ -243,9 +471,10 @@ function collectScheduledTriggerRecords(context) {
 	for (const agentId of context.completeAgentIds) {
 		const agentData = context.project.agents[agentId];
 		if (!agentData?.scheduledTriggers) continue;
+		const fileNamesByScheduledTriggerId = buildSequentialNameFileNames(Object.entries(agentData.scheduledTriggers));
 		for (const [scheduledTriggerId, scheduledTriggerData] of Object.entries(agentData.scheduledTriggers)) records.push({
 			id: scheduledTriggerId,
-			filePath: resolveRecordFilePath(context, "scheduledTriggers", scheduledTriggerId, join(context.paths.agentsDir, "scheduled-triggers", buildComponentFileName(scheduledTriggerId, scheduledTriggerData.name ?? void 0))),
+			filePath: resolveRecordFilePath(context, "scheduledTriggers", scheduledTriggerId, join(context.paths.agentsDir, "scheduled-triggers", fileNamesByScheduledTriggerId[scheduledTriggerId])),
 			payload: {
 				scheduledTriggerId,
 				...scheduledTriggerData
@@ -264,6 +493,7 @@ function collectAgentRecords(context) {
 		const agentFilePath = resolveRecordFilePath(context, "agents", agentId, join(context.paths.agentsDir, buildComponentFileName(agentId, agentName)));
 		const existingAgent = context.existingComponentRegistry?.get(agentId, "agents");
 		const subAgentReferences = collectSubAgentReferenceOverrides(context, agentData, agentFilePath);
+		const subAgentReferencePathOverrides = collectSubAgentReferencePathOverrides(context, agentData);
 		const statusUpdates = asRecord(agentData.statusUpdates);
 		const contextTemplateReferences = collectContextTemplateReferences(context, agentData, agentFilePath, [typeof agentData.prompt === "string" ? agentData.prompt : void 0, typeof statusUpdates?.prompt === "string" ? statusUpdates.prompt : void 0]);
 		records.push({
@@ -273,7 +503,8 @@ function collectAgentRecords(context) {
 				agentId,
 				...agentData,
 				...existingAgent?.name?.length && { agentVariableName: existingAgent.name },
-				...Object.keys(subAgentReferences).length > 0 ? { subAgentReferences } : {},
+				...Object.keys(subAgentReferences).length && { subAgentReferences },
+				...Object.keys(subAgentReferencePathOverrides).length && { subAgentReferencePathOverrides },
 				...contextTemplateReferences && { contextConfigReference: contextTemplateReferences.contextConfigReference },
 				...contextTemplateReferences?.contextConfigHeadersReference && { contextConfigHeadersReference: contextTemplateReferences.contextConfigHeadersReference }
 			}
@@ -281,9 +512,24 @@ function collectAgentRecords(context) {
 	}
 	return records;
 }
+function collectSubAgentReferencePathOverrides(context, agentData) {
+	const generatedSubAgentReferencePathById = buildSubAgentReferencePathById(context.project, context.completeAgentIds);
+	const subAgentIds = new Set(extractReferenceIds(agentData.subAgents));
+	if (typeof agentData.defaultSubAgentId === "string" && agentData.defaultSubAgentId.length > 0) subAgentIds.add(agentData.defaultSubAgentId);
+	if (!subAgentIds.size) return {};
+	const subAgents = asRecord(agentData.subAgents);
+	const overrides = {};
+	for (const subAgentId of subAgentIds) {
+		const fallbackReferencePath = generatedSubAgentReferencePathById[subAgentId];
+		const subAgentData = asRecord(subAgents?.[subAgentId]);
+		const subAgentName = typeof subAgentData?.name === "string" ? subAgentData.name : void 0;
+		overrides[subAgentId] = stripExtension(basename(resolveRecordFilePath(context, "subAgents", subAgentId, join(context.paths.agentsDir, "sub-agents", fallbackReferencePath ? `${fallbackReferencePath}.ts` : buildComponentFileName(subAgentId, subAgentName)))));
+	}
+	return overrides;
+}
 function collectSubAgentRecords(context) {
 	if (!context.project.agents) return [];
-	const records = [];
+	const recordsBySubAgentId = /* @__PURE__ */ new Map();
 	for (const agentId of context.completeAgentIds) {
 		const agentData = context.project.agents[agentId];
 		const subAgents = asRecord(agentData?.subAgents);
@@ -291,17 +537,18 @@ function collectSubAgentRecords(context) {
 		for (const [subAgentId, subAgentData] of Object.entries(subAgents)) {
 			const payload = asRecord(subAgentData);
 			if (!payload) continue;
-			const referenceOverrides = collectSubAgentDependencyReferenceOverrides(context, payload);
+			const dependencyReferences = collectSubAgentDependencyReferenceOverrides(context, payload);
 			const subAgentName = typeof payload.name === "string" ? payload.name : void 0;
 			const subAgentFilePath = resolveRecordFilePath(context, "subAgents", subAgentId, join(context.paths.agentsDir, "sub-agents", buildComponentFileName(subAgentId, subAgentName)));
 			const contextTemplateReferences = collectContextTemplateReferences(context, agentData, subAgentFilePath, [typeof payload.prompt === "string" ? payload.prompt : void 0]);
-			records.push({
+			recordsBySubAgentId.set(subAgentId, {
 				id: subAgentId,
 				filePath: subAgentFilePath,
 				payload: {
 					subAgentId,
 					...payload,
-					...referenceOverrides && { referenceOverrides },
+					...dependencyReferences?.referenceOverrides && { referenceOverrides: dependencyReferences.referenceOverrides },
+					...dependencyReferences?.referencePathOverrides && { referencePathOverrides: dependencyReferences.referencePathOverrides },
 					...contextTemplateReferences && {
 						contextConfigId: contextTemplateReferences.contextConfigId,
 						contextConfigReference: contextTemplateReferences.contextConfigReference
@@ -311,7 +558,7 @@ function collectSubAgentRecords(context) {
 			});
 		}
 	}
-	return records;
+	return [...recordsBySubAgentId.values()];
 }
 function collectStatusComponentRecords(context) {
 	if (!context.project.agents) return [];
@@ -340,6 +587,7 @@ function collectStatusComponentRecords(context) {
 }
 function collectProjectRecord(context) {
 	const referenceOverrides = collectProjectReferenceOverrides(context);
+	const referencePathOverrides = collectProjectReferencePathOverrides(context);
 	return [{
 		id: context.project.id,
 		filePath: resolveRecordFilePath(context, "project", context.project.id, join(context.paths.projectRoot, "index.ts")),
@@ -356,7 +604,8 @@ function collectProjectRecord(context) {
 			dataComponents: getObjectKeys(context.project.dataComponents),
 			artifactComponents: getObjectKeys(context.project.artifactComponents),
 			credentialReferences: getObjectKeys(context.project.credentialReferences),
-			...referenceOverrides && { referenceOverrides }
+			...referenceOverrides && { referenceOverrides },
+			...referencePathOverrides && { referencePathOverrides }
 		}
 	}];
 }
@@ -400,24 +649,15 @@ function isAgentComplete(agentData) {
 	};
 	return { complete: true };
 }
-function collectUnsupportedComponentCounts(project) {
-	return {
-		functionTools: getObjectKeys(project.functionTools).length,
-		functions: getObjectKeys(project.functions).length,
-		externalAgents: getObjectKeys(project.externalAgents).length
-	};
-}
-function hasUnsupportedComponents(counts) {
-	return Object.values(counts).some((value) => value > 0);
-}
-function formatUnsupportedComponentsError(counts) {
-	return `Unsupported components for v4 introspect: ${formatUnsupportedCounts(counts)}`;
-}
-function formatUnsupportedComponentsWarning(counts) {
-	return `Skipped unsupported components for v4 introspect: ${formatUnsupportedCounts(counts)}`;
-}
-function formatUnsupportedCounts(counts) {
-	return Object.entries(counts).filter(([, value]) => value > 0).map(([name, value]) => `${name}=${value}`).join(", ");
+function collectEnvironmentCredentialReferenceIds(project) {
+	const credentialReferenceIds = /* @__PURE__ */ new Set();
+	for (const toolData of Object.values(project.tools ?? {})) {
+		const toolRecord = asRecord(toolData);
+		const credentialReferenceId = toolRecord && typeof toolRecord.credentialReferenceId === "string" ? toolRecord.credentialReferenceId : void 0;
+		const hasInlineCredential = toolRecord?.credential !== void 0 && toolRecord?.credential !== null;
+		if (credentialReferenceId && !hasInlineCredential) credentialReferenceIds.add(credentialReferenceId);
+	}
+	return [...credentialReferenceIds];
 }
 function getObjectKeys(value) {
 	const record = asRecord(value);
@@ -434,11 +674,16 @@ function asRecord(value) {
 	return value;
 }
 function collectSubAgentReferenceOverrides(context, agentData, agentFilePath) {
+	const generatedSubAgentReferenceNamesById = buildSubAgentReferenceNamesById(context.project, context.completeAgentIds);
 	const subAgentIds = new Set(extractReferenceIds(agentData.subAgents));
 	if (typeof agentData.defaultSubAgentId === "string" && agentData.defaultSubAgentId.length > 0) subAgentIds.add(agentData.defaultSubAgentId);
 	if (!subAgentIds.size) return {};
+	const subAgents = asRecord(agentData.subAgents);
 	const overrides = {};
 	for (const subAgentId of subAgentIds) {
+		const subAgentData = asRecord(subAgents?.[subAgentId]);
+		const subAgentName = typeof subAgentData?.name === "string" ? subAgentData.name : void 0;
+		overrides[subAgentId] = { name: generatedSubAgentReferenceNamesById[subAgentId] ?? resolveSubAgentVariableName(subAgentId, subAgentName) };
 		const existingSubAgent = context.existingComponentRegistry?.get(subAgentId, "subAgents");
 		if (!existingSubAgent?.name) continue;
 		overrides[subAgentId] = normalizeFilePath(resolveProjectFilePath(context.paths.projectRoot, existingSubAgent.filePath)) === normalizeFilePath(agentFilePath) ? {
@@ -494,8 +739,8 @@ function inferHeadersReferenceFromContextConfig(contextConfig, contextConfigId)
 	if (typeof headers === "string" && headers.length > 0) return toCamelCase(headers);
 	const headersRecord = asRecord(headers);
 	if (headersRecord) {
-		if (typeof headersRecord.id === "string" && headersRecord.id.length > 0) return toCamelCase(headersRecord.id);
-		if (typeof headersRecord.name === "string" && headersRecord.name.length > 0) return toCamelCase(headersRecord.name);
+		if (typeof headersRecord.id === "string" && headersRecord.id) return toCamelCase(headersRecord.id);
+		if (typeof headersRecord.name === "string" && headersRecord.name) return toCamelCase(headersRecord.name);
 	}
 	if (isPlainObject(contextConfig.value.headersSchema)) return `${toCamelCase(contextConfigId)}Headers`;
 }
@@ -545,53 +790,116 @@ function applyPromptHeaderTemplateSchema(contextConfig, headerTemplateVariables)
 }
 function collectSubAgentDependencyReferenceOverrides(context, subAgentData) {
 	const registry = context.existingComponentRegistry;
-	if (!registry) return;
-	const overrides = {};
+	const referenceOverrides = {};
+	const referencePathOverrides = {};
+	const toolReferenceNamesById = buildToolReferenceNamesById(context.project);
+	const toolReferencePathsById = buildToolReferencePathById(context.project);
+	const subAgentReferenceNamesById = buildSubAgentReferenceNamesById(context.project, context.completeAgentIds);
+	const subAgentReferencePathsById = buildSubAgentReferencePathById(context.project, context.completeAgentIds);
+	const agentReferenceNamesById = buildAgentReferenceNamesById(context.project);
+	const agentReferencePathsById = buildAgentReferencePathById(context.project);
+	const externalAgentReferenceNamesById = buildExternalAgentReferenceNamesById(context.project);
+	const externalAgentReferencePathsById = buildExternalAgentReferencePathById(context.project);
+	const assignSubAgentReferenceOverrides = (subAgentId) => {
+		const subAgentReferenceName = subAgentReferenceNamesById[subAgentId];
+		if (subAgentReferenceName) assignReferenceOverride(referenceOverrides, "subAgents", subAgentId, subAgentReferenceName);
+		const subAgentReferencePath = subAgentReferencePathsById[subAgentId];
+		if (subAgentReferencePath) assignReferencePathOverride(referencePathOverrides, "subAgents", subAgentId, subAgentReferencePath);
+	};
+	const assignAgentReferenceOverrides = (agentId) => {
+		const agentReferenceName = agentReferenceNamesById[agentId];
+		if (agentReferenceName) assignReferenceOverride(referenceOverrides, "agents", agentId, agentReferenceName);
+		const agentReferencePath = agentReferencePathsById[agentId];
+		if (agentReferencePath) assignReferencePathOverride(referencePathOverrides, "agents", agentId, agentReferencePath);
+	};
+	const assignExternalAgentReferenceOverrides = (externalAgentId) => {
+		const externalAgentReferenceName = externalAgentReferenceNamesById[externalAgentId];
+		if (externalAgentReferenceName) assignReferenceOverride(referenceOverrides, "externalAgents", externalAgentId, externalAgentReferenceName);
+		const externalAgentReferencePath = externalAgentReferencePathsById[externalAgentId];
+		if (externalAgentReferencePath) assignReferencePathOverride(referencePathOverrides, "externalAgents", externalAgentId, externalAgentReferencePath);
+	};
 	const canUse = Array.isArray(subAgentData.canUse) ? subAgentData.canUse : [];
 	for (const item of canUse) {
-		if (typeof item === "string") {
-			assignComponentReferenceOverride(registry, overrides, "tools", item, "tools");
-			assignComponentReferenceOverride(registry, overrides, "tools", item, "functionTools");
-			continue;
-		}
 		const canUseRecord = asRecord(item);
-		if (!canUseRecord || typeof canUseRecord.toolId !== "string") continue;
-		assignComponentReferenceOverride(registry, overrides, "tools", canUseRecord.toolId, "tools");
-		assignComponentReferenceOverride(registry, overrides, "tools", canUseRecord.toolId, "functionTools");
+		const toolId = typeof item === "string" ? item : canUseRecord && typeof canUseRecord.toolId === "string" ? canUseRecord.toolId : void 0;
+		if (!toolId) continue;
+		assignReferenceOverride(referenceOverrides, "tools", toolId, toolReferenceNamesById[toolId] ?? toToolReferenceName(toolId));
+		assignReferencePathOverride(referencePathOverrides, "tools", toolId, toolReferencePathsById[toolId] ?? toKebabCase(toolId));
+		if (registry) {
+			assignComponentReferenceOverride(registry, referenceOverrides, "tools", toolId, "tools");
+			assignComponentReferenceOverride(registry, referenceOverrides, "tools", toolId, "functionTools");
+			const toolComponent = registry.get(toolId, "functionTools") ?? registry.get(toolId, "tools");
+			if (toolComponent?.filePath) assignReferencePathOverride(referencePathOverrides, "tools", toolId, resolveToolModulePath(toolComponent.filePath));
+		}
 	}
 	const canDelegateTo = Array.isArray(subAgentData.canDelegateTo) ? subAgentData.canDelegateTo : [];
 	for (const item of canDelegateTo) {
 		if (typeof item === "string") {
-			assignFirstMatchingComponentReferenceOverride(registry, overrides, item, [
-				["subAgents", "subAgents"],
-				["agents", "agents"],
-				["externalAgents", "externalAgents"]
-			]);
+			assignSubAgentReferenceOverrides(item);
+			assignAgentReferenceOverrides(item);
+			assignExternalAgentReferenceOverrides(item);
 			continue;
 		}
 		const canDelegateRecord = asRecord(item);
-		if (!canDelegateRecord) continue;
-		if (typeof canDelegateRecord.subAgentId === "string") {
-			assignComponentReferenceOverride(registry, overrides, "subAgents", canDelegateRecord.subAgentId, "subAgents");
-			continue;
+		if (typeof canDelegateRecord?.subAgentId === "string") assignSubAgentReferenceOverrides(canDelegateRecord.subAgentId);
+		if (typeof canDelegateRecord?.agentId === "string") assignAgentReferenceOverrides(canDelegateRecord.agentId);
+		if (typeof canDelegateRecord?.externalAgentId === "string") assignExternalAgentReferenceOverrides(canDelegateRecord.externalAgentId);
+	}
+	const canTransferTo = extractReferenceIds(subAgentData.canTransferTo);
+	for (const transferTargetId of canTransferTo) {
+		assignSubAgentReferenceOverrides(transferTargetId);
+		assignAgentReferenceOverrides(transferTargetId);
+		assignExternalAgentReferenceOverrides(transferTargetId);
+	}
+	if (registry) {
+		for (const item of canDelegateTo) {
+			if (typeof item === "string") {
+				assignFirstMatchingComponentReferenceOverride(registry, referenceOverrides, item, [
+					["subAgents", "subAgents"],
+					["agents", "agents"],
+					["externalAgents", "externalAgents"]
+				]);
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "subAgents", item, "subAgents");
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "agents", item, "agents");
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "externalAgents", item, "externalAgents");
+				continue;
+			}
+			const canDelegateRecord = asRecord(item);
+			if (!canDelegateRecord) continue;
+			if (typeof canDelegateRecord.subAgentId === "string") {
+				assignComponentReferenceOverride(registry, referenceOverrides, "subAgents", canDelegateRecord.subAgentId, "subAgents");
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "subAgents", canDelegateRecord.subAgentId, "subAgents");
+				continue;
+			}
+			if (typeof canDelegateRecord.agentId === "string") {
+				assignComponentReferenceOverride(registry, referenceOverrides, "agents", canDelegateRecord.agentId, "agents");
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "agents", canDelegateRecord.agentId, "agents");
+				continue;
+			}
+			if (typeof canDelegateRecord.externalAgentId === "string") {
+				assignComponentReferenceOverride(registry, referenceOverrides, "externalAgents", canDelegateRecord.externalAgentId, "externalAgents");
+				assignComponentReferencePathOverride(registry, referencePathOverrides, "externalAgents", canDelegateRecord.externalAgentId, "externalAgents");
+			}
 		}
-		if (typeof canDelegateRecord.agentId === "string") {
-			assignComponentReferenceOverride(registry, overrides, "agents", canDelegateRecord.agentId, "agents");
-			continue;
+		for (const transferTargetId of canTransferTo) {
+			assignFirstMatchingComponentReferenceOverride(registry, referenceOverrides, transferTargetId, [
+				["subAgents", "subAgents"],
+				["agents", "agents"],
+				["externalAgents", "externalAgents"]
+			]);
+			assignComponentReferencePathOverride(registry, referencePathOverrides, "subAgents", transferTargetId, "subAgents");
+			assignComponentReferencePathOverride(registry, referencePathOverrides, "agents", transferTargetId, "agents");
+			assignComponentReferencePathOverride(registry, referencePathOverrides, "externalAgents", transferTargetId, "externalAgents");
 		}
-		if (typeof canDelegateRecord.externalAgentId === "string") assignComponentReferenceOverride(registry, overrides, "externalAgents", canDelegateRecord.externalAgentId, "externalAgents");
+		const dataComponentIds = extractReferenceIds(subAgentData.dataComponents);
+		for (const dataComponentId of dataComponentIds) assignComponentReferenceOverride(registry, referenceOverrides, "dataComponents", dataComponentId, "dataComponents");
+		const artifactComponentIds = extractReferenceIds(subAgentData.artifactComponents);
+		for (const artifactComponentId of artifactComponentIds) assignComponentReferenceOverride(registry, referenceOverrides, "artifactComponents", artifactComponentId, "artifactComponents");
 	}
-	const canTransferTo = extractReferenceIds(subAgentData.canTransferTo);
-	for (const transferTargetId of canTransferTo) assignFirstMatchingComponentReferenceOverride(registry, overrides, transferTargetId, [
-		["subAgents", "subAgents"],
-		["agents", "agents"],
-		["externalAgents", "externalAgents"]
-	]);
-	const dataComponentIds = extractReferenceIds(subAgentData.dataComponents);
-	for (const dataComponentId of dataComponentIds) assignComponentReferenceOverride(registry, overrides, "dataComponents", dataComponentId, "dataComponents");
-	const artifactComponentIds = extractReferenceIds(subAgentData.artifactComponents);
-	for (const artifactComponentId of artifactComponentIds) assignComponentReferenceOverride(registry, overrides, "artifactComponents", artifactComponentId, "artifactComponents");
-	return Object.keys(overrides).length > 0 ? overrides : void 0;
+	return Object.keys(referenceOverrides).length > 0 || Object.keys(referencePathOverrides).length > 0 ? {
+		...Object.keys(referenceOverrides).length > 0 && { referenceOverrides },
+		...Object.keys(referencePathOverrides).length > 0 && { referencePathOverrides }
+	} : void 0;
 }
 function assignFirstMatchingComponentReferenceOverride(registry, overrides, componentId, candidates) {
 	for (const [overrideType, componentType] of candidates) {
@@ -606,15 +914,123 @@ function assignComponentReferenceOverride(registry, overrides, overrideType, com
 	if (!component?.name) return;
 	assignReferenceOverride(overrides, overrideType, componentId, component.name);
 }
+function assignComponentReferencePathOverride(registry, overrides, overrideType, componentId, componentType) {
+	const component = registry.get(componentId, componentType);
+	if (!component?.filePath) return;
+	assignReferencePathOverride(overrides, overrideType, componentId, componentType === "tools" || componentType === "functionTools" ? resolveToolModulePath(component.filePath) : stripExtension(basename(component.filePath)));
+}
 function assignReferenceOverride(overrides, overrideType, componentId, referenceName) {
 	const overrideMap = overrides[overrideType] ?? {};
 	overrideMap[componentId] = referenceName;
 	overrides[overrideType] = overrideMap;
 }
+function assignReferencePathOverride(overrides, overrideType, componentId, referencePath) {
+	const overrideMap = overrides[overrideType] ?? {};
+	overrideMap[componentId] = referencePath;
+	overrides[overrideType] = overrideMap;
+}
+function buildToolReferenceNamesById(project) {
+	const toolReferenceNamesById = {};
+	for (const [toolId, toolData] of Object.entries(project.tools ?? {})) {
+		const toolName = asRecord(toolData)?.name;
+		toolReferenceNamesById[toolId] = typeof toolName === "string" && toolName.length > 0 ? toToolReferenceName(toolName) : toToolReferenceName(toolId);
+	}
+	for (const functionToolEntry of collectFunctionToolEntries(project)) toolReferenceNamesById[functionToolEntry.functionToolId] = toToolReferenceName(functionToolEntry.exportName);
+	return toolReferenceNamesById;
+}
+function buildToolReferencePathById(project) {
+	const toolEntries = Object.entries(project.tools ?? {});
+	const toolFileNamesById = buildSequentialNameFileNames(toolEntries);
+	const toolReferencePathById = {};
+	for (const [toolId] of toolEntries) toolReferencePathById[toolId] = stripExtension(toolFileNamesById[toolId]);
+	const functionToolEntries = collectFunctionToolEntries(project);
+	const functionToolFileNamesById = buildSequentialNameFileNames(functionToolEntries.map(({ functionToolId, fileName }) => [functionToolId, { name: fileName }]));
+	for (const { functionToolId } of functionToolEntries) toolReferencePathById[functionToolId] = stripExtension(functionToolFileNamesById[functionToolId]);
+	return toolReferencePathById;
+}
+function buildCredentialReferenceNamesById(project) {
+	const credentialReferenceNamesById = {};
+	const countsByReferenceName = /* @__PURE__ */ new Map();
+	for (const [credentialId, credentialData] of Object.entries(project.credentialReferences ?? {})) {
+		const credentialName = asRecord(credentialData)?.name;
+		const baseReferenceName = typeof credentialName === "string" && credentialName.length > 0 ? toCredentialReferenceName(credentialName) : toCredentialReferenceName(credentialId);
+		const occurrence = countsByReferenceName.get(baseReferenceName) ?? 0;
+		countsByReferenceName.set(baseReferenceName, occurrence + 1);
+		credentialReferenceNamesById[credentialId] = occurrence === 0 ? baseReferenceName : `${baseReferenceName}${occurrence}`;
+	}
+	return credentialReferenceNamesById;
+}
+function buildCredentialReferencePathById(project) {
+	const credentialEntries = Object.entries(project.credentialReferences ?? {});
+	const credentialFileNamesById = buildSequentialNameFileNames(credentialEntries);
+	const credentialReferencePathById = {};
+	for (const [credentialId] of credentialEntries) credentialReferencePathById[credentialId] = stripExtension(credentialFileNamesById[credentialId]);
+	return credentialReferencePathById;
+}
+function buildExternalAgentReferenceNamesById(project) {
+	const externalAgentReferenceNamesById = {};
+	const countsByReferenceName = /* @__PURE__ */ new Map();
+	for (const [externalAgentId, externalAgentData] of Object.entries(project.externalAgents ?? {})) {
+		const baseReferenceName = toExternalAgentReferenceName(resolveExternalAgentNamingSeed(externalAgentId, externalAgentData));
+		const occurrence = countsByReferenceName.get(baseReferenceName) ?? 0;
+		countsByReferenceName.set(baseReferenceName, occurrence + 1);
+		externalAgentReferenceNamesById[externalAgentId] = occurrence === 0 ? baseReferenceName : `${baseReferenceName}${occurrence}`;
+	}
+	return externalAgentReferenceNamesById;
+}
+function buildExternalAgentReferencePathById(project) {
+	const externalAgentEntries = Object.entries(project.externalAgents ?? {}).map(([externalAgentId, externalAgentData]) => [externalAgentId, { name: resolveExternalAgentNamingSeed(externalAgentId, externalAgentData) }]);
+	const externalAgentFileNamesById = buildSequentialNameFileNames(externalAgentEntries);
+	const externalAgentReferencePathById = {};
+	for (const [externalAgentId] of externalAgentEntries) externalAgentReferencePathById[externalAgentId] = stripExtension(externalAgentFileNamesById[externalAgentId]);
+	return externalAgentReferencePathById;
+}
+function buildSubAgentReferenceNamesById(project, agentIds) {
+	const subAgentReferenceNamesById = {};
+	const candidateAgentIds = agentIds !== void 0 ? [...agentIds] : Object.keys(project.agents ?? {});
+	for (const agentId of candidateAgentIds) {
+		const agentData = project.agents?.[agentId];
+		const subAgents = asRecord(agentData?.subAgents);
+		if (!subAgents) continue;
+		for (const [subAgentId, subAgentData] of Object.entries(subAgents)) {
+			const subAgentName = asRecord(subAgentData)?.name;
+			subAgentReferenceNamesById[subAgentId] = resolveSubAgentVariableName(subAgentId, typeof subAgentName === "string" ? subAgentName : void 0);
+		}
+	}
+	return subAgentReferenceNamesById;
+}
+function buildSubAgentReferencePathById(project, agentIds) {
+	const subAgentReferencePathById = {};
+	const candidateAgentIds = agentIds !== void 0 ? [...agentIds] : Object.keys(project.agents ?? {});
+	for (const agentId of candidateAgentIds) {
+		const agentData = project.agents?.[agentId];
+		const subAgents = asRecord(agentData?.subAgents);
+		if (!subAgents) continue;
+		for (const [subAgentId, subAgentData] of Object.entries(subAgents)) {
+			const subAgentName = asRecord(subAgentData)?.name;
+			subAgentReferencePathById[subAgentId] = stripExtension(buildComponentFileName(subAgentId, typeof subAgentName === "string" ? subAgentName : void 0));
+		}
+	}
+	return subAgentReferencePathById;
+}
+function buildAgentReferenceNamesById(project) {
+	const agentReferenceNamesById = {};
+	for (const agentId of Object.keys(project.agents ?? {})) agentReferenceNamesById[agentId] = toCamelCase(agentId);
+	return agentReferenceNamesById;
+}
+function buildAgentReferencePathById(project) {
+	const agentReferencePathById = {};
+	for (const [agentId, agentData] of Object.entries(project.agents ?? {})) {
+		const agentName = asRecord(agentData)?.name;
+		agentReferencePathById[agentId] = stripExtension(buildComponentFileName(agentId, typeof agentName === "string" ? agentName : void 0));
+	}
+	return agentReferencePathById;
+}
 function collectProjectReferenceOverrides(context) {
-	const registry = context.existingComponentRegistry;
-	if (!registry) return;
 	const overrides = {};
+	addProjectNameBasedReferenceOverrides(context.project, overrides);
+	const registry = context.existingComponentRegistry;
+	if (!registry) return Object.keys(overrides).length > 0 ? overrides : void 0;
 	for (const agentId of context.completeAgentIds) assignComponentReferenceOverrideForProject(registry, overrides, "agents", agentId, "agents");
 	const toolIds = getObjectKeys(context.project.tools);
 	for (const toolId of toolIds) {
@@ -631,6 +1047,102 @@ function collectProjectReferenceOverrides(context) {
 	for (const credentialId of credentialIds) assignComponentReferenceOverrideForProject(registry, overrides, "credentialReferences", credentialId, "credentials");
 	return Object.keys(overrides).length > 0 ? overrides : void 0;
 }
+function addProjectNameBasedReferenceOverrides(project, overrides) {
+	for (const [toolId, toolData] of Object.entries(project.tools ?? {})) {
+		const toolName = asRecord(toolData)?.name;
+		assignProjectReferenceOverride(overrides, "tools", toolId, typeof toolName === "string" && toolName.length > 0 ? toToolReferenceName(toolName) : toToolReferenceName(toolId));
+	}
+	for (const [credentialId, credentialData] of Object.entries(project.credentialReferences ?? {})) {
+		const credentialName = asRecord(credentialData)?.name;
+		assignProjectReferenceOverride(overrides, "credentialReferences", credentialId, typeof credentialName === "string" && credentialName.length > 0 ? toCredentialReferenceName(credentialName) : toCredentialReferenceName(credentialId));
+	}
+	const externalAgentReferenceNamesById = buildExternalAgentReferenceNamesById(project);
+	for (const [externalAgentId, referenceName] of Object.entries(externalAgentReferenceNamesById)) assignProjectReferenceOverride(overrides, "externalAgents", externalAgentId, referenceName);
+}
+function collectProjectReferencePathOverrides(context) {
+	const overrides = {};
+	if (context.project.agents) for (const agentId of context.completeAgentIds) {
+		const agentData = asRecord(context.project.agents[agentId]);
+		assignProjectReferenceOverride(overrides, "agents", agentId, stripExtension(buildComponentFileName(agentId, typeof agentData?.name === "string" ? agentData.name : void 0)));
+	}
+	const toolEntries = Object.entries(context.project.tools ?? {});
+	const toolFileNamesById = buildSequentialNameFileNames(toolEntries);
+	for (const [toolId] of toolEntries) assignProjectReferenceOverride(overrides, "tools", toolId, stripExtension(toolFileNamesById[toolId]));
+	const credentialEntries = Object.entries(context.project.credentialReferences ?? {});
+	const credentialFileNamesById = buildSequentialNameFileNames(credentialEntries);
+	for (const [credentialId] of credentialEntries) assignProjectReferenceOverride(overrides, "credentialReferences", credentialId, stripExtension(credentialFileNamesById[credentialId]));
+	const externalAgentReferencePathsById = buildExternalAgentReferencePathById(context.project);
+	for (const [externalAgentId, referencePath] of Object.entries(externalAgentReferencePathsById)) assignProjectReferenceOverride(overrides, "externalAgents", externalAgentId, referencePath);
+	const registry = context.existingComponentRegistry;
+	if (registry) {
+		for (const agentId of context.completeAgentIds) {
+			const agentComponent = registry.get(agentId, "agents");
+			if (agentComponent?.filePath) assignProjectReferenceOverride(overrides, "agents", agentId, stripExtension(basename(agentComponent.filePath)));
+		}
+		for (const toolId of getObjectKeys(context.project.tools)) {
+			const toolComponent = registry.get(toolId, "functionTools") ?? registry.get(toolId, "tools");
+			if (toolComponent?.filePath) assignProjectReferenceOverride(overrides, "tools", toolId, resolveToolModulePath(toolComponent.filePath));
+		}
+		for (const credentialId of getObjectKeys(context.project.credentialReferences)) {
+			const credentialComponent = registry.get(credentialId, "credentials");
+			if (credentialComponent?.filePath) assignProjectReferenceOverride(overrides, "credentialReferences", credentialId, stripExtension(basename(credentialComponent.filePath)));
+		}
+		for (const externalAgentId of getObjectKeys(context.project.externalAgents)) {
+			const externalAgentComponent = registry.get(externalAgentId, "externalAgents");
+			if (externalAgentComponent?.filePath) assignProjectReferenceOverride(overrides, "externalAgents", externalAgentId, stripExtension(basename(externalAgentComponent.filePath)));
+		}
+	}
+	return Object.keys(overrides).length > 0 ? overrides : void 0;
+}
+function assignProjectReferenceOverride(overrides, overrideType, componentId, referenceName) {
+	const overrideMap = overrides[overrideType] ?? {};
+	overrideMap[componentId] = referenceName;
+	overrides[overrideType] = overrideMap;
+}
+function stripExtension(fileName) {
+	return fileName.replace(/\.[^.]+$/, "");
+}
+function resolveToolModulePath(filePath) {
+	const normalizedFilePath = normalizeFilePath(filePath);
+	const toolsIndex = normalizedFilePath.lastIndexOf("/tools/");
+	if (toolsIndex >= 0) {
+		let modulePath = stripExtension(normalizedFilePath.slice(toolsIndex + 7));
+		if (modulePath.endsWith("/index")) modulePath = modulePath.slice(0, -6);
+		if (modulePath.length > 0) return modulePath;
+	}
+	const baseModulePath = stripExtension(basename(normalizedFilePath));
+	if (baseModulePath === "index") return stripExtension(basename(dirname(normalizedFilePath)));
+	return baseModulePath;
+}
+function resolveExternalAgentNamingSeed(externalAgentId, externalAgentData) {
+	if (isHumanReadableId(externalAgentId)) return externalAgentId;
+	const externalAgentName = asRecord(externalAgentData)?.name;
+	if (typeof externalAgentName === "string" && externalAgentName.length > 0) return externalAgentName;
+	return externalAgentId;
+}
+function toExternalAgentReferenceName(input) {
+	const base = toCamelCase(input);
+	return base.endsWith("Agent") ? base : `${base}Agent`;
+}
+function buildSequentialNameFileNames(entries) {
+	const countsByStem = /* @__PURE__ */ new Map();
+	const fileNamesById = {};
+	for (const [componentId, componentData] of entries) {
+		const name = asRecord(componentData)?.name;
+		const baseStem = resolveNameFileStem(componentId, typeof name === "string" ? name : void 0);
+		const occurrence = countsByStem.get(baseStem) ?? 0;
+		countsByStem.set(baseStem, occurrence + 1);
+		fileNamesById[componentId] = `${occurrence === 0 ? baseStem : `${baseStem}-${occurrence}`}.ts`;
+	}
+	return fileNamesById;
+}
+function resolveNameFileStem(componentId, name) {
+	const nameStem = name ? toKebabCase(name) : "";
+	if (nameStem.length > 0) return nameStem;
+	const idStem = toKebabCase(componentId);
+	if (idStem.length > 0) return idStem;
+	return componentId;
+}
 function assignComponentReferenceOverrideForProject(registry, overrides, overrideType, componentId, componentType) {
 	const component = registry.get(componentId, componentType);
 	if (!component?.name) return false;
@@ -729,4 +1241,5 @@ function isReferenceInsideFunctionLike(referenceNode) {
 }
 
 //#endregion
-export { introspectGenerate };
+export { introspectGenerate };
+//# sourceMappingURL=introspect-generator.js.map