@inkeep/agents-cli 0.51.0 → 0.53.0

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

@@ -0,0 +1,706 @@
+import { collectTemplateVariableNames, createInMemoryProject, isPlainObject, toCamelCase } 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 { generateMcpToolDefinition } from "./generators/mcp-tool-generator.js";
+import { generateProjectDefinition } from "./generators/project-generator.js";
+import { generateStatusComponentDefinition } from "./generators/status-component-generator.js";
+import { generateSubAgentDefinition } from "./generators/sub-agent-generator.js";
+import { generateTriggerDefinition } from "./generators/trigger-generator.js";
+import { mergeGeneratedModule } from "./module-merge.js";
+import { 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 }) {
+	validateProject(project);
+	const skippedAgents = [];
+	const context = {
+		project,
+		paths,
+		completeAgentIds: collectCompleteAgentIds(project, skippedAgents),
+		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);
+		for (const record of records) {
+			const sourceFile = task.generate(record.payload);
+			writeTypeScriptFile(record.filePath, sourceFile.getFullText(), writeMode);
+			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));
+	}
+}
+function createGenerationTasks() {
+	return [
+		{
+			type: "credential",
+			collect: collectCredentialRecords,
+			generate: generateCredentialDefinition
+		},
+		{
+			type: "artifact-component",
+			collect: collectArtifactComponentRecords,
+			generate: generateArtifactComponentDefinition
+		},
+		{
+			type: "data-component",
+			collect: collectDataComponentRecords,
+			generate: generateDataComponentDefinition
+		},
+		{
+			type: "tool",
+			collect: collectToolRecords,
+			generate: generateMcpToolDefinition
+		},
+		{
+			type: "context-config",
+			collect: collectContextConfigRecords,
+			generate: generateContextConfigDefinition
+		},
+		{
+			type: "trigger",
+			collect: collectTriggerRecords,
+			generate: generateTriggerDefinition
+		},
+		{
+			type: "sub-agent",
+			collect: collectSubAgentRecords,
+			generate: generateSubAgentDefinition
+		},
+		{
+			type: "status-component",
+			collect: collectStatusComponentRecords,
+			generate: generateStatusComponentDefinition
+		},
+		{
+			type: "agent",
+			collect: collectAgentRecords,
+			generate: generateAgentDefinition
+		},
+		{
+			type: "project",
+			collect: collectProjectRecord,
+			generate: generateProjectDefinition
+		}
+	];
+}
+function collectCredentialRecords(context) {
+	if (!context.project.credentialReferences) return [];
+	return Object.entries(context.project.credentialReferences).map(([credentialId, credentialData]) => ({
+		id: credentialId,
+		filePath: resolveRecordFilePath(context, "credentials", credentialId, join(context.paths.credentialsDir, `${credentialId}.ts`)),
+		payload: {
+			credentialId,
+			...credentialData
+		}
+	}));
+}
+function collectArtifactComponentRecords(context) {
+	if (!context.project.artifactComponents) return [];
+	return Object.entries(context.project.artifactComponents).map(([artifactComponentId, artifactComponentData]) => ({
+		id: artifactComponentId,
+		filePath: resolveRecordFilePath(context, "artifactComponents", artifactComponentId, join(context.paths.artifactComponentsDir, `${artifactComponentId}.ts`)),
+		payload: {
+			artifactComponentId,
+			...artifactComponentData
+		}
+	}));
+}
+function collectDataComponentRecords(context) {
+	if (!context.project.dataComponents) return [];
+	return Object.entries(context.project.dataComponents).map(([dataComponentId, dataComponent]) => ({
+		id: dataComponentId,
+		filePath: resolveRecordFilePath(context, "dataComponents", dataComponentId, join(context.paths.dataComponentsDir, `${dataComponentId}.ts`)),
+		payload: {
+			dataComponentId,
+			...dataComponent
+		}
+	}));
+}
+function collectContextConfigRecords(context) {
+	if (!context.project.agents) return [];
+	const contextConfigRecordsById = /* @__PURE__ */ new Map();
+	for (const agentId of context.completeAgentIds) {
+		const agentData = context.project.agents[agentId];
+		const contextConfig = agentData ? asRecord(agentData.contextConfig) : void 0;
+		if (!agentData || !contextConfig) continue;
+		const normalizedContextConfig = applyPromptHeaderTemplateSchema(contextConfig, collectHeaderTemplateVariablesFromAgentPrompts(agentData));
+		const contextConfigId = typeof normalizedContextConfig.id === "string" ? normalizedContextConfig.id : "";
+		if (!contextConfigId) continue;
+		if (!contextConfigRecordsById.has(contextConfigId)) {
+			const contextConfigFilePath = resolveRecordFilePath(context, "contextConfigs", contextConfigId, join(context.paths.contextConfigsDir, `${contextConfigId}.ts`));
+			const credentialReferenceOverrides = collectContextConfigCredentialReferenceOverrides(context, normalizedContextConfig);
+			const headersReferenceOverride = collectContextConfigHeadersReferenceOverride(context, contextConfigId, contextConfigFilePath);
+			contextConfigRecordsById.set(contextConfigId, {
+				id: contextConfigId,
+				filePath: contextConfigFilePath,
+				payload: {
+					contextConfigId,
+					...normalizedContextConfig,
+					...headersReferenceOverride && { headers: headersReferenceOverride },
+					...credentialReferenceOverrides && { referenceOverrides: { credentialReferences: credentialReferenceOverrides } }
+				}
+			});
+		}
+	}
+	return [...contextConfigRecordsById.values()];
+}
+function collectToolRecords(context) {
+	return Object.entries(context.project.tools ?? {}).map(([toolId, toolData]) => ({
+		id: toolId,
+		filePath: resolveRecordFilePath(context, "tools", toolId, join(context.paths.toolsDir, `${toolId}.ts`)),
+		payload: {
+			mcpToolId: toolId,
+			...toolData
+		}
+	}));
+}
+function collectContextConfigCredentialReferenceOverrides(context, contextConfigData) {
+	const registry = context.existingComponentRegistry;
+	if (!registry) return;
+	const contextVariables = asRecord(contextConfigData.contextVariables);
+	if (!contextVariables) return;
+	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");
+		if (existingCredential?.name) overrides[credentialReferenceId] = existingCredential.name;
+	}
+	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 });
+	for (const declaration of sourceFile.getVariableDeclarations()) {
+		const initializer = declaration.getInitializer();
+		if (!initializer || !Node.isCallExpression(initializer)) continue;
+		const expression = initializer.getExpression();
+		if (!Node.isIdentifier(expression) || expression.getText() !== "contextConfig") continue;
+		const [configArg] = initializer.getArguments();
+		if (!configArg || !Node.isObjectLiteralExpression(configArg)) continue;
+		const idProperty = configArg.getProperty("id");
+		if (!idProperty || !Node.isPropertyAssignment(idProperty)) continue;
+		const idInitializer = idProperty.getInitializer();
+		if (!idInitializer || !Node.isStringLiteral(idInitializer)) continue;
+		if (idInitializer.getLiteralValue() !== contextConfigId) continue;
+		const headersProperty = configArg.getProperty("headers");
+		if (!headersProperty) return;
+		if (Node.isShorthandPropertyAssignment(headersProperty)) return headersProperty.getName();
+		if (!Node.isPropertyAssignment(headersProperty)) return;
+		const headersInitializer = headersProperty.getInitializer();
+		if (!headersInitializer) return;
+		if (Node.isIdentifier(headersInitializer)) return headersInitializer.getText();
+		if (Node.isAsExpression(headersInitializer)) {
+			const valueExpression = headersInitializer.getExpression();
+			if (Node.isIdentifier(valueExpression)) return valueExpression.getText();
+		}
+		return;
+	}
+}
+function collectTriggerRecords(context) {
+	if (!context.project.agents) return [];
+	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", `${triggerId}.ts`)),
+			payload: {
+				triggerId,
+				...triggerData
+			}
+		});
+	}
+	return records;
+}
+function collectAgentRecords(context) {
+	if (!context.project.agents) return [];
+	const records = [];
+	for (const agentId of context.completeAgentIds) {
+		const agentData = context.project.agents[agentId];
+		if (!agentData) continue;
+		const agentFilePath = resolveRecordFilePath(context, "agents", agentId, join(context.paths.agentsDir, `${agentId}.ts`));
+		const existingAgent = context.existingComponentRegistry?.get(agentId, "agents");
+		const subAgentReferences = collectSubAgentReferenceOverrides(context, agentData, agentFilePath);
+		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({
+			id: agentId,
+			filePath: agentFilePath,
+			payload: {
+				agentId,
+				...agentData,
+				...existingAgent?.name?.length && { agentVariableName: existingAgent.name },
+				...Object.keys(subAgentReferences).length > 0 ? { subAgentReferences } : {},
+				...contextTemplateReferences && { contextConfigReference: contextTemplateReferences.contextConfigReference },
+				...contextTemplateReferences?.contextConfigHeadersReference && { contextConfigHeadersReference: contextTemplateReferences.contextConfigHeadersReference }
+			}
+		});
+	}
+	return records;
+}
+function collectSubAgentRecords(context) {
+	if (!context.project.agents) return [];
+	const records = [];
+	for (const agentId of context.completeAgentIds) {
+		const agentData = context.project.agents[agentId];
+		const subAgents = asRecord(agentData?.subAgents);
+		if (!subAgents) continue;
+		for (const [subAgentId, subAgentData] of Object.entries(subAgents)) {
+			const payload = asRecord(subAgentData);
+			if (!payload) continue;
+			const referenceOverrides = collectSubAgentDependencyReferenceOverrides(context, payload);
+			const subAgentFilePath = resolveRecordFilePath(context, "subAgents", subAgentId, join(context.paths.agentsDir, "sub-agents", `${subAgentId}.ts`));
+			const contextTemplateReferences = collectContextTemplateReferences(context, agentData, subAgentFilePath, [typeof payload.prompt === "string" ? payload.prompt : void 0]);
+			records.push({
+				id: subAgentId,
+				filePath: subAgentFilePath,
+				payload: {
+					subAgentId,
+					...payload,
+					...referenceOverrides && { referenceOverrides },
+					...contextTemplateReferences && {
+						contextConfigId: contextTemplateReferences.contextConfigId,
+						contextConfigReference: contextTemplateReferences.contextConfigReference
+					},
+					...contextTemplateReferences?.contextConfigHeadersReference && { contextConfigHeadersReference: contextTemplateReferences.contextConfigHeadersReference }
+				}
+			});
+		}
+	}
+	return records;
+}
+function collectStatusComponentRecords(context) {
+	if (!context.project.agents) return [];
+	const statusComponentRecordsById = /* @__PURE__ */ new Map();
+	for (const agentId of context.completeAgentIds) {
+		const agentData = context.project.agents[agentId];
+		const statusUpdates = asRecord(agentData?.statusUpdates);
+		const statusComponents = Array.isArray(statusUpdates?.statusComponents) ? statusUpdates.statusComponents : [];
+		for (const statusComponentData of statusComponents) {
+			const payload = asRecord(statusComponentData);
+			if (!payload) continue;
+			const statusComponentId = resolveStatusComponentId(payload);
+			if (!statusComponentId || statusComponentRecordsById.has(statusComponentId)) continue;
+			statusComponentRecordsById.set(statusComponentId, {
+				id: statusComponentId,
+				filePath: resolveRecordFilePath(context, "statusComponents", statusComponentId, join(context.paths.statusComponentsDir, `${statusComponentId}.ts`)),
+				payload: {
+					statusComponentId,
+					...payload
+				}
+			});
+		}
+	}
+	return [...statusComponentRecordsById.values()];
+}
+function collectProjectRecord(context) {
+	const referenceOverrides = collectProjectReferenceOverrides(context);
+	return [{
+		id: context.project.id,
+		filePath: resolveRecordFilePath(context, "project", context.project.id, join(context.paths.projectRoot, "index.ts")),
+		payload: {
+			projectId: context.project.id,
+			name: context.project.name,
+			description: context.project.description,
+			models: context.project.models,
+			stopWhen: context.project.stopWhen,
+			skills: getObjectKeys(context.project.skills),
+			agents: [...context.completeAgentIds],
+			tools: getObjectKeys(context.project.tools),
+			externalAgents: getObjectKeys(context.project.externalAgents),
+			dataComponents: getObjectKeys(context.project.dataComponents),
+			artifactComponents: getObjectKeys(context.project.artifactComponents),
+			credentialReferences: getObjectKeys(context.project.credentialReferences),
+			...referenceOverrides && { referenceOverrides }
+		}
+	}];
+}
+function validateProject(project) {
+	if (!project || typeof project !== "object") throw new Error("Project data is required");
+	if (!project.id) throw new Error("Project id is required");
+	if (!project.name) throw new Error("Project name is required");
+}
+function collectCompleteAgentIds(project, skippedAgents) {
+	const completeAgentIds = /* @__PURE__ */ new Set();
+	for (const [agentId, agentData] of Object.entries(project.agents ?? {})) {
+		const completeness = isAgentComplete(agentData);
+		if (!completeness.complete) {
+			skippedAgents.push({
+				id: agentId,
+				reason: completeness.reason ?? "incomplete"
+			});
+			continue;
+		}
+		completeAgentIds.add(agentId);
+	}
+	return completeAgentIds;
+}
+function isAgentComplete(agentData) {
+	const data = asRecord(agentData);
+	if (!data) return {
+		complete: false,
+		reason: "invalid agent object"
+	};
+	if (!data.name || typeof data.name !== "string") return {
+		complete: false,
+		reason: "missing name"
+	};
+	if (!data.defaultSubAgentId || typeof data.defaultSubAgentId !== "string") return {
+		complete: false,
+		reason: "missing defaultSubAgentId"
+	};
+	if (!asRecord(data.subAgents) || !Object.keys(data.subAgents).length) return {
+		complete: false,
+		reason: "no sub-agents defined"
+	};
+	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 getObjectKeys(value) {
+	const record = asRecord(value);
+	if (!record) return [];
+	return Object.keys(record);
+}
+function resolveStatusComponentId(statusComponentData) {
+	if (typeof statusComponentData.id === "string") return statusComponentData.id;
+	if (typeof statusComponentData.type === "string") return statusComponentData.type;
+	if (typeof statusComponentData.name === "string") return statusComponentData.name;
+}
+function asRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	return value;
+}
+function collectSubAgentReferenceOverrides(context, agentData, agentFilePath) {
+	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 overrides = {};
+	for (const subAgentId of subAgentIds) {
+		const existingSubAgent = context.existingComponentRegistry?.get(subAgentId, "subAgents");
+		if (!existingSubAgent?.name) continue;
+		overrides[subAgentId] = normalizeFilePath(resolveProjectFilePath(context.paths.projectRoot, existingSubAgent.filePath)) === normalizeFilePath(agentFilePath) ? {
+			name: existingSubAgent.name,
+			local: true
+		} : { name: existingSubAgent.name };
+	}
+	return overrides;
+}
+function collectAgentContextConfigReferenceOverride(context, agentData, agentFilePath) {
+	const contextConfigId = extractContextConfigData(agentData)?.id;
+	if (!contextConfigId) return;
+	const existingContextConfig = context.existingComponentRegistry?.get(contextConfigId, "contextConfigs");
+	if (!existingContextConfig?.name) return;
+	return normalizeFilePath(resolveProjectFilePath(context.paths.projectRoot, existingContextConfig.filePath)) === normalizeFilePath(agentFilePath) ? {
+		name: existingContextConfig.name,
+		local: true
+	} : { name: existingContextConfig.name };
+}
+function collectContextTemplateReferences(context, agentData, targetFilePath, promptValues) {
+	const contextConfig = extractContextConfigData(agentData);
+	const contextConfigId = contextConfig?.id;
+	if (!contextConfigId) return;
+	const contextConfigFilePath = resolveRecordFilePath(context, "contextConfigs", contextConfigId, join(context.paths.contextConfigsDir, `${contextConfigId}.ts`));
+	const isLocal = normalizeFilePath(contextConfigFilePath) === normalizeFilePath(targetFilePath);
+	const contextConfigReference = collectAgentContextConfigReferenceOverride(context, agentData, targetFilePath) ?? (isLocal ? {
+		name: toCamelCase(contextConfigId),
+		local: true
+	} : { name: toCamelCase(contextConfigId) });
+	const hasHeadersTemplateVariables = collectTemplateVariablesFromValues(promptValues).some((variableName) => variableName.startsWith("headers."));
+	let headersReferenceName = collectContextConfigHeadersReferenceOverride(context, contextConfigId, contextConfigFilePath) ?? inferHeadersReferenceFromContextConfig(contextConfig, contextConfigId);
+	if (!headersReferenceName && hasHeadersTemplateVariables) headersReferenceName = `${toCamelCase(contextConfigId)}Headers`;
+	return {
+		contextConfigId,
+		contextConfigReference,
+		...headersReferenceName && { contextConfigHeadersReference: isLocal ? {
+			name: headersReferenceName,
+			local: true
+		} : { name: headersReferenceName } }
+	};
+}
+function extractContextConfigData(agentData) {
+	const contextConfig = typeof agentData.contextConfig === "string" ? { id: agentData.contextConfig } : asRecord(agentData.contextConfig);
+	const contextConfigId = contextConfig && typeof contextConfig.id === "string" ? contextConfig.id : void 0;
+	if (!contextConfigId || !contextConfig) return;
+	return {
+		id: contextConfigId,
+		value: contextConfig
+	};
+}
+function inferHeadersReferenceFromContextConfig(contextConfig, contextConfigId) {
+	const headers = contextConfig.value.headers;
+	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 (isPlainObject(contextConfig.value.headersSchema)) return `${toCamelCase(contextConfigId)}Headers`;
+}
+function collectTemplateVariablesFromValues(values) {
+	const variables = [];
+	for (const value of values) {
+		if (typeof value !== "string") continue;
+		variables.push(...collectTemplateVariableNames(value));
+	}
+	return variables;
+}
+function collectHeaderTemplateVariablesFromAgentPrompts(agentData) {
+	const variables = /* @__PURE__ */ new Set();
+	addHeaderTemplateVariablesFromString(typeof agentData.prompt === "string" ? agentData.prompt : void 0, variables);
+	const statusUpdates = asRecord(agentData.statusUpdates);
+	addHeaderTemplateVariablesFromString(typeof statusUpdates?.prompt === "string" ? statusUpdates.prompt : void 0, variables);
+	const subAgents = asRecord(agentData.subAgents);
+	if (!subAgents) return variables;
+	for (const subAgentData of Object.values(subAgents)) {
+		const subAgent = asRecord(subAgentData);
+		addHeaderTemplateVariablesFromString(typeof subAgent?.prompt === "string" ? subAgent.prompt : void 0, variables);
+	}
+	return variables;
+}
+function addHeaderTemplateVariablesFromString(value, variables) {
+	if (typeof value !== "string") return;
+	for (const variableName of collectTemplateVariableNames(value)) {
+		if (!variableName.startsWith("headers.")) continue;
+		const headerPath = variableName.slice(8);
+		if (headerPath) variables.add(headerPath);
+	}
+}
+function applyPromptHeaderTemplateSchema(contextConfig, headerTemplateVariables) {
+	if (!headerTemplateVariables.size) return contextConfig;
+	if (typeof contextConfig.headers === "string" || isPlainObject(contextConfig.headers) || isPlainObject(contextConfig.headersSchema)) return contextConfig;
+	const variableNames = [...headerTemplateVariables].sort();
+	const properties = Object.fromEntries(variableNames.map((variableName) => [variableName, { type: "string" }]));
+	return {
+		...contextConfig,
+		headersSchema: {
+			type: "object",
+			properties,
+			required: variableNames,
+			additionalProperties: false
+		}
+	};
+}
+function collectSubAgentDependencyReferenceOverrides(context, subAgentData) {
+	const registry = context.existingComponentRegistry;
+	if (!registry) return;
+	const overrides = {};
+	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 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"]
+			]);
+			continue;
+		}
+		const canDelegateRecord = asRecord(item);
+		if (!canDelegateRecord) continue;
+		if (typeof canDelegateRecord.subAgentId === "string") {
+			assignComponentReferenceOverride(registry, overrides, "subAgents", canDelegateRecord.subAgentId, "subAgents");
+			continue;
+		}
+		if (typeof canDelegateRecord.agentId === "string") {
+			assignComponentReferenceOverride(registry, overrides, "agents", canDelegateRecord.agentId, "agents");
+			continue;
+		}
+		if (typeof canDelegateRecord.externalAgentId === "string") assignComponentReferenceOverride(registry, overrides, "externalAgents", canDelegateRecord.externalAgentId, "externalAgents");
+	}
+	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;
+}
+function assignFirstMatchingComponentReferenceOverride(registry, overrides, componentId, candidates) {
+	for (const [overrideType, componentType] of candidates) {
+		const component = registry.get(componentId, componentType);
+		if (!component?.name) continue;
+		assignReferenceOverride(overrides, overrideType, componentId, component.name);
+		return;
+	}
+}
+function assignComponentReferenceOverride(registry, overrides, overrideType, componentId, componentType) {
+	const component = registry.get(componentId, componentType);
+	if (!component?.name) return;
+	assignReferenceOverride(overrides, overrideType, componentId, component.name);
+}
+function assignReferenceOverride(overrides, overrideType, componentId, referenceName) {
+	const overrideMap = overrides[overrideType] ?? {};
+	overrideMap[componentId] = referenceName;
+	overrides[overrideType] = overrideMap;
+}
+function collectProjectReferenceOverrides(context) {
+	const registry = context.existingComponentRegistry;
+	if (!registry) return;
+	const overrides = {};
+	for (const agentId of context.completeAgentIds) assignComponentReferenceOverrideForProject(registry, overrides, "agents", agentId, "agents");
+	const toolIds = getObjectKeys(context.project.tools);
+	for (const toolId of toolIds) {
+		if (assignComponentReferenceOverrideForProject(registry, overrides, "tools", toolId, "functionTools")) continue;
+		assignComponentReferenceOverrideForProject(registry, overrides, "tools", toolId, "tools");
+	}
+	const externalAgentIds = getObjectKeys(context.project.externalAgents);
+	for (const externalAgentId of externalAgentIds) assignComponentReferenceOverrideForProject(registry, overrides, "externalAgents", externalAgentId, "externalAgents");
+	const dataComponentIds = getObjectKeys(context.project.dataComponents);
+	for (const dataComponentId of dataComponentIds) assignComponentReferenceOverrideForProject(registry, overrides, "dataComponents", dataComponentId, "dataComponents");
+	const artifactComponentIds = getObjectKeys(context.project.artifactComponents);
+	for (const artifactComponentId of artifactComponentIds) assignComponentReferenceOverrideForProject(registry, overrides, "artifactComponents", artifactComponentId, "artifactComponents");
+	const credentialIds = getObjectKeys(context.project.credentialReferences);
+	for (const credentialId of credentialIds) assignComponentReferenceOverrideForProject(registry, overrides, "credentialReferences", credentialId, "credentials");
+	return Object.keys(overrides).length > 0 ? overrides : void 0;
+}
+function assignComponentReferenceOverrideForProject(registry, overrides, overrideType, componentId, componentType) {
+	const component = registry.get(componentId, componentType);
+	if (!component?.name) return false;
+	const overrideMap = overrides[overrideType] ?? {};
+	overrideMap[componentId] = component.name;
+	overrides[overrideType] = overrideMap;
+	return true;
+}
+function extractReferenceIds(value) {
+	if (Array.isArray(value)) return value.map((item) => {
+		if (typeof item === "string") return item;
+		const record$1 = asRecord(item);
+		if (record$1 && typeof record$1.id === "string") return record$1.id;
+	}).filter((id) => !!id);
+	const record = asRecord(value);
+	if (!record) return [];
+	return Object.keys(record);
+}
+function resolveRecordFilePath(context, componentType, componentId, fallbackFilePath) {
+	const existingComponent = context.existingComponentRegistry?.get(componentId, componentType);
+	if (!existingComponent?.filePath) return fallbackFilePath;
+	return resolveProjectFilePath(context.paths.projectRoot, existingComponent.filePath);
+}
+function resolveProjectFilePath(projectRoot, filePath) {
+	if (filePath.startsWith("/")) return filePath;
+	return join(projectRoot, filePath);
+}
+function normalizeFilePath(filePath) {
+	return filePath.replaceAll("\\", "/");
+}
+function writeTypeScriptFile(filePath, content, writeMode) {
+	mkdirSync(dirname(filePath), { recursive: true });
+	const processedContent = writeMode === "merge" && existsSync(filePath) ? mergeSafely(readFileSync(filePath, "utf8"), content) : content;
+	const sourceFile = createInMemoryProject().createSourceFile("generated.ts", processedContent, { overwrite: true });
+	const normalizedSourceFile = moveVariableDeclarationsBeforeUsage(applyObjectShorthand(sourceFile));
+	sourceFile.formatText();
+	writeFileSync(filePath, `${normalizedSourceFile.getFullText().trimEnd()}\n`);
+}
+function mergeSafely(existingContent, generatedContent) {
+	try {
+		return mergeGeneratedModule(existingContent, generatedContent);
+	} catch (error) {
+		console.warn(`Warning: Failed to merge file, using generated content. Manual changes may be lost. Reason: ${error instanceof Error ? error.message : String(error)}`);
+		return generatedContent;
+	}
+}
+function applyObjectShorthand(sourceFile) {
+	for (const objectLiteral of sourceFile.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) for (const property of objectLiteral.getProperties()) {
+		if (!Node.isPropertyAssignment(property)) continue;
+		const nameNode = property.getNameNode();
+		const initializer = property.getInitializer();
+		if (!Node.isIdentifier(nameNode) || !initializer || !Node.isIdentifier(initializer)) continue;
+		if (nameNode.getText() !== initializer.getText()) continue;
+		property.replaceWithText(nameNode.getText());
+	}
+	return sourceFile;
+}
+function moveVariableDeclarationsBeforeUsage(sourceFile) {
+	let moved = true;
+	while (moved) {
+		moved = false;
+		const variableStatements = sourceFile.getVariableStatements();
+		for (const variableStatement of variableStatements) {
+			const statementStart = variableStatement.getStart();
+			const sourceStatements = sourceFile.getStatements();
+			const statementIndex = sourceStatements.indexOf(variableStatement);
+			if (statementIndex <= 0) continue;
+			let targetIndex;
+			for (const declaration of variableStatement.getDeclarations()) for (const referenceNode of declaration.findReferencesAsNodes()) {
+				if (referenceNode.getSourceFile() !== sourceFile) continue;
+				if (referenceNode.getParent() === declaration) continue;
+				if (referenceNode.getStart() >= statementStart) continue;
+				if (isReferenceInsideFunctionLike(referenceNode)) continue;
+				const topLevelStatement = referenceNode.getFirstAncestor((ancestor) => {
+					return Node.isStatement(ancestor) && ancestor.getParentIfKind(SyntaxKind.SourceFile);
+				});
+				if (!topLevelStatement) continue;
+				const topLevelStatementIndex = sourceStatements.indexOf(topLevelStatement);
+				if (topLevelStatementIndex === -1 || topLevelStatementIndex >= statementIndex) continue;
+				targetIndex = targetIndex === void 0 ? topLevelStatementIndex : Math.min(targetIndex, topLevelStatementIndex);
+			}
+			if (targetIndex === void 0) continue;
+			const statementText = variableStatement.getText();
+			variableStatement.remove();
+			sourceFile.insertStatements(targetIndex, [statementText]);
+			moved = true;
+			break;
+		}
+	}
+	return sourceFile;
+}
+function isReferenceInsideFunctionLike(referenceNode) {
+	return Boolean(referenceNode.getFirstAncestor((ancestor) => {
+		return Node.isArrowFunction(ancestor) || Node.isFunctionDeclaration(ancestor) || Node.isFunctionExpression(ancestor) || Node.isMethodDeclaration(ancestor) || Node.isGetAccessorDeclaration(ancestor) || Node.isSetAccessorDeclaration(ancestor);
+	}));
+}
+
+//#endregion
+export { introspectGenerate };