@agentuity/cli 0.0.111 → 0.1.0

package/src/agents-docs.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
 import { generateLLMPrompt as generateCLIPrompt } from './cmd/ai/prompt/llm';
 import { generateLLMPrompt as generateAgentPrompt } from './cmd/ai/prompt/agent';
 import { generateLLMPrompt as generateWebPrompt } from './cmd/ai/prompt/web';
@@ -13,14 +14,23 @@ interface WriteAgentsDocsOptions {
 	onlyIfMissing?: boolean;
 }
 
+/**
+ * Generate the reference file content that points to .agents/
+ */
+function generateReferenceContent(name: string): string {
+	return `See [.agents/agentuity/sdk/${name}/AGENTS.md](../../.agents/agentuity/sdk/${name}/AGENTS.md) for Agentuity ${name} development guidelines.
+`;
+}
+
 /**
  * Writes AGENTS.md documentation files to the appropriate locations in a project.
  *
  * This function generates and writes AGENTS.md files to:
- * - node_modules/@agentuity/cli/AGENTS.md (CLI documentation)
- * - src/agent/AGENTS.md (Agent development documentation)
- * - src/api/AGENTS.md (API development documentation)
- * - src/web/AGENTS.md (Web development documentation)
+ * - node_modules/@agentuity/cli/AGENTS.md (CLI documentation - full content)
+ * - .agents/agentuity/sdk/[type]/AGENTS.md (Full content for agent, api, web)
+ * - src/agent/AGENTS.md (Reference file pointing to .agents/)
+ * - src/api/AGENTS.md (Reference file pointing to .agents/)
+ * - src/web/AGENTS.md (Reference file pointing to .agents/)
  *
  * @param rootDir - The root directory of the project
  * @param options - Options for controlling write behavior
@@ -38,6 +48,13 @@ export async function writeAgentsDocs(
 		await Bun.write(filePath, content);
 	};
 
+	const ensureWithCreate = async (dir: string, fileName: string, content: string) => {
+		await mkdir(dir, { recursive: true });
+		const filePath = join(dir, fileName);
+		if (onlyIfMissing && existsSync(filePath)) return;
+		await Bun.write(filePath, content);
+	};
+
 	// Generate and write AGENTS.md for the CLI (in node_modules)
 	await ensure(
 		join(rootDir, 'node_modules', '@agentuity', 'cli'),
@@ -45,8 +62,25 @@ export async function writeAgentsDocs(
 		generateCLIPrompt()
 	);
 
-	// Generate and write AGENTS.md for each of the main source folders
-	await ensure(join(rootDir, 'src', 'agent'), 'AGENTS.md', generateAgentPrompt());
-	await ensure(join(rootDir, 'src', 'api'), 'AGENTS.md', generateAPIPrompt());
-	await ensure(join(rootDir, 'src', 'web'), 'AGENTS.md', generateWebPrompt());
+	// Write full content to .agents/agentuity/sdk/[type]/AGENTS.md
+	await ensureWithCreate(
+		join(rootDir, '.agents', 'agentuity', 'sdk', 'agent'),
+		'AGENTS.md',
+		generateAgentPrompt()
+	);
+	await ensureWithCreate(
+		join(rootDir, '.agents', 'agentuity', 'sdk', 'api'),
+		'AGENTS.md',
+		generateAPIPrompt()
+	);
+	await ensureWithCreate(
+		join(rootDir, '.agents', 'agentuity', 'sdk', 'web'),
+		'AGENTS.md',
+		generateWebPrompt()
+	);
+
+	// Write reference files to src/[type]/AGENTS.md (pointing to .agents/)
+	await ensure(join(rootDir, 'src', 'agent'), 'AGENTS.md', generateReferenceContent('agent'));
+	await ensure(join(rootDir, 'src', 'api'), 'AGENTS.md', generateReferenceContent('api'));
+	await ensure(join(rootDir, 'src', 'web'), 'AGENTS.md', generateReferenceContent('web'));
 }

package/src/cli.ts

@@ -914,8 +914,18 @@ async function registerSubcommand(
 				if (opt.hasDefault) {
 					const defaultValue =
 						typeof opt.defaultValue === 'function' ? opt.defaultValue() : opt.defaultValue;
-					cmd.option(`--no-${flag}`, desc);
-					cmd.option(flagSpec, desc, defaultValue);
+					// For boolean flags with default true, only show the --no-* flag in help
+					// since that's the only actionable flag users need to know about.
+					// The positive flag is hidden but still functional.
+					const baseDesc = desc.replace(/\s*\(use\s+--no-\S+\s+to\s+skip\)/i, '').trim();
+					const negatedDesc = baseDesc.toLowerCase().startsWith('run ')
+						? `Skip ${baseDesc.slice(4)}`
+						: `Do not ${baseDesc.charAt(0).toLowerCase()}${baseDesc.slice(1)}`;
+					cmd.option(`--no-${flag}`, negatedDesc);
+					const positiveOption = cmd.createOption(flagSpec, baseDesc);
+					positiveOption.default(defaultValue);
+					positiveOption.hideHelp();
+					cmd.addOption(positiveOption);
 				} else {
 					cmd.option(flagSpec, desc);
 				}

package/src/cmd/auth/apikey.ts

@@ -0,0 +1,36 @@
+import { createSubcommand } from '../../types';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+
+const ApikeyResponseSchema = z.object({
+	apiKey: z.string().describe('The API key for the authenticated user'),
+});
+
+export const apikeyCommand = createSubcommand({
+	name: 'apikey',
+	description: 'Display the API key for the currently authenticated user',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	idempotent: true,
+	schema: {
+		response: ApikeyResponseSchema,
+	},
+	examples: [
+		{ command: getCommand('auth apikey'), description: 'Print the API key' },
+		{ command: getCommand('--json auth apikey'), description: 'Output API key in JSON format' },
+	],
+
+	async handler(ctx) {
+		const { auth, options } = ctx;
+
+		const result = {
+			apiKey: auth.apiKey,
+		};
+
+		if (!options.json) {
+			console.log(result.apiKey);
+		}
+
+		return result;
+	},
+});

package/src/cmd/auth/index.ts

@@ -1,4 +1,5 @@
 import { createCommand } from '../../types';
+import { apikeyCommand } from './apikey';
 import { loginCommand } from './login';
 import { logoutCommand } from './logout';
 import { signupCommand } from './signup';
@@ -14,5 +15,12 @@ export const command = createCommand({
 		{ command: getCommand('auth login'), description: 'Login to your account' },
 		{ command: getCommand('auth whoami'), description: 'Show current user info' },
 	],
-	subcommands: [loginCommand, logoutCommand, signupCommand, whoamiCommand, sshSubcommand],
+	subcommands: [
+		apikeyCommand,
+		loginCommand,
+		logoutCommand,
+		signupCommand,
+		whoamiCommand,
+		sshSubcommand,
+	],
 });

package/src/cmd/build/ast.ts

@@ -967,9 +967,19 @@ function hasValidatorCall(args: unknown[]): ValidatorInfo {
 			if (callExpr.callee.type === 'Identifier') {
 				const identifier = callExpr.callee as ASTNodeIdentifier;
 				if (identifier.name === 'validator') {
-					// Try to extract schema variables from validator({ input, output })
+					// Try to extract schema variables from validator({ input, output, stream })
 					const schemas = extractValidatorSchemas(callExpr);
-					return { hasValidator: true, ...schemas };
+					// Return if we found any schema variables OR a stream flag
+					if (
+						schemas.inputSchemaVariable ||
+						schemas.outputSchemaVariable ||
+						schemas.stream !== undefined
+					) {
+						return { hasValidator: true, ...schemas };
+					}
+					// Try Hono validator('json', callback) pattern
+					const honoSchemas = extractHonoValidatorSchema(callExpr);
+					return { hasValidator: true, ...honoSchemas };
 				}
 				// Check for zValidator('json', schema)
 				if (identifier.name === 'zValidator') {
@@ -1129,6 +1139,114 @@ function extractZValidatorSchema(callExpr: ASTCallExpression): {
 	return result;
 }
 
+/**
+ * Extract schema from Hono validator('json', callback) pattern
+ * Example: validator('json', (value, c) => { const result = mySchema['~standard'].validate(value); ... })
+ * Searches the callback function body for schema.validate() or schema['~standard'].validate() calls
+ */
+function extractHonoValidatorSchema(callExpr: ASTCallExpression): {
+	inputSchemaVariable?: string;
+} {
+	const result: { inputSchemaVariable?: string } = {};
+
+	// Hono validator requires at least 2 arguments: validator(target, callback)
+	if (!callExpr.arguments || callExpr.arguments.length < 2) {
+		return result;
+	}
+
+	// First argument should be 'json' literal (only extract for JSON validation)
+	const targetArg = callExpr.arguments[0] as ASTNode;
+	if (targetArg.type === 'Literal') {
+		const targetValue = (targetArg as ASTLiteral).value;
+		if (typeof targetValue === 'string' && targetValue !== 'json') {
+			return result;
+		}
+	} else {
+		return result;
+	}
+
+	// Second argument should be a function (arrow or regular)
+	const callbackArg = callExpr.arguments[1] as ASTNode;
+	if (
+		callbackArg.type !== 'ArrowFunctionExpression' &&
+		callbackArg.type !== 'FunctionExpression'
+	) {
+		return result;
+	}
+
+	// Get the function body
+	const funcExpr = callbackArg as {
+		body?: ASTNode;
+	};
+
+	if (!funcExpr.body) {
+		return result;
+	}
+
+	// Search the function body for schema.validate() or schema['~standard'].validate() calls
+	const schemaVar = findSchemaValidateCall(funcExpr.body);
+	if (schemaVar) {
+		result.inputSchemaVariable = schemaVar;
+	}
+
+	return result;
+}
+
+/**
+ * Recursively search AST for schema.validate() or schema['~standard'].validate() calls
+ * Returns the schema variable name if found
+ */
+function findSchemaValidateCall(node: ASTNode): string | undefined {
+	if (!node || typeof node !== 'object') return undefined;
+
+	// Check if this is a CallExpression with .validate()
+	if (node.type === 'CallExpression') {
+		const callExpr = node as ASTCallExpression;
+
+		// Check for schema['~standard'].validate(value) pattern
+		// AST: CallExpression -> MemberExpression(validate) -> MemberExpression(['~standard']) -> Identifier(schema)
+		if (callExpr.callee.type === 'MemberExpression') {
+			const member = callExpr.callee as ASTMemberExpression;
+			const propName =
+				member.property.type === 'Identifier'
+					? (member.property as ASTNodeIdentifier).name
+					: undefined;
+
+			if (propName === 'validate') {
+				// Check if the object is schema['~standard'] or just schema
+				if (member.object.type === 'MemberExpression') {
+					// schema['~standard'].validate() pattern
+					const innerMember = member.object as ASTMemberExpression;
+					if (innerMember.object.type === 'Identifier') {
+						return (innerMember.object as ASTNodeIdentifier).name;
+					}
+				} else if (member.object.type === 'Identifier') {
+					// schema.validate() pattern
+					return (member.object as ASTNodeIdentifier).name;
+				}
+			}
+		}
+	}
+
+	// Recursively search child nodes
+	for (const key of Object.keys(node)) {
+		const value = (node as unknown as Record<string, unknown>)[key];
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				if (item && typeof item === 'object') {
+					const found = findSchemaValidateCall(item as ASTNode);
+					if (found) return found;
+				}
+			}
+		} else if (value && typeof value === 'object') {
+			const found = findSchemaValidateCall(value as ASTNode);
+			if (found) return found;
+		}
+	}
+
+	return undefined;
+}
+
 export async function parseRoute(
 	rootDir: string,
 	filename: string,

package/src/cmd/build/entry-generator.ts

@@ -4,7 +4,7 @@
  */
 
 import { join } from 'node:path';
-import type { Logger, WorkbenchConfig } from '../../types';
+import type { Logger, WorkbenchConfig, AnalyticsConfig } from '../../types';
 import { discoverRoutes } from './vite/route-discovery';
 
 interface GenerateEntryOptions {
@@ -14,6 +14,7 @@ interface GenerateEntryOptions {
 	logger: Logger;
 	mode: 'dev' | 'prod';
 	workbench?: WorkbenchConfig;
+	analytics?: boolean | AnalyticsConfig;
 	vitePort?: number; // Port of Vite asset server (dev mode only)
 }
 
@@ -21,7 +22,8 @@ interface GenerateEntryOptions {
  * Generate entry file with clean Vite-native architecture
  */
 export async function generateEntryFile(options: GenerateEntryOptions): Promise<void> {
-	const { rootDir, projectId, deploymentId, logger, mode, workbench, vitePort } = options;
+	const { rootDir, projectId, deploymentId, logger, mode, workbench, analytics, vitePort } =
+		options;
 
 	const srcDir = join(rootDir, 'src');
 	const generatedDir = join(srcDir, 'generated');
@@ -70,7 +72,11 @@ export async function generateEntryFile(options: GenerateEntryOptions): Promise<
 		`  loadBuildMetadata,`,
 		`  createWorkbenchRouter,`,
 		`  bootstrapRuntimeEnv,`,
-		` patchBunS3ForStorageDev,`,
+		`  patchBunS3ForStorageDev,`,
+		`  getOrganizationId,`,
+		`  getProjectId,`,
+		`  isDevMode as runtimeIsDevMode,`,
+		`  createWebSessionMiddleware,`,
 	];
 
 	const imports = [
@@ -200,6 +206,126 @@ if (isDevelopment() && process.env.VITE_PORT) {
 // See: https://github.com/oven-sh/bun/issues/20183
 const getEnv = (key: string) => process.env[key];
 const isDevelopment = () => getEnv('NODE' + '_' + 'ENV') !== 'production';
+`;
+
+	// Generate analytics config and injection helper
+	const analyticsEnabled = analytics !== false;
+	const analyticsConfig: AnalyticsConfig = typeof analytics === 'object' ? analytics : {};
+
+	const analyticsHelper = analyticsEnabled
+		? `
+// Analytics configuration - edit agentuity.config.ts to configure
+const analyticsConfig = {
+	enabled: ${analyticsConfig.enabled !== false},
+	requireConsent: ${analyticsConfig.requireConsent ?? false},
+	trackClicks: ${analyticsConfig.trackClicks ?? true},
+	trackScroll: ${analyticsConfig.trackScroll ?? true},
+	trackOutboundLinks: ${analyticsConfig.trackOutboundLinks ?? true},
+	trackForms: ${analyticsConfig.trackForms ?? false},
+	trackWebVitals: ${analyticsConfig.trackWebVitals ?? true},
+	trackErrors: ${analyticsConfig.trackErrors ?? true},
+	trackSPANavigation: ${analyticsConfig.trackSPANavigation ?? true},
+	sampleRate: ${analyticsConfig.sampleRate ?? 1},
+	excludePatterns: ${JSON.stringify(analyticsConfig.excludePatterns ?? [])},
+	globalProperties: ${JSON.stringify(analyticsConfig.globalProperties ?? {})},
+};
+
+// Inject analytics config and script into HTML
+// Note: Only static config is injected (org, project, devmode, tracking options)
+// Session and thread IDs are read from cookies by the beacon script
+function injectAnalytics(html: string): string {
+	if (!analyticsConfig.enabled) return html;
+	
+	const orgId = getOrganizationId() || '';
+	const projectId = getProjectId() || '';
+	const isDevmode = runtimeIsDevMode();
+	
+	// Only include static config - session/thread come from cookies
+	const pageConfig = {
+		...analyticsConfig,
+		orgId,
+		projectId,
+		isDevmode,
+	};
+	
+	const configScript = \`<script>window.__AGENTUITY_ANALYTICS__=\${JSON.stringify(pageConfig)};</script>\`;
+	// Session script sets cookies and window.__AGENTUITY_SESSION__ (dynamic, not cached)
+	const sessionScript = '<script src="/_agentuity/webanalytics/session.js" async></script>';
+	// Beacon script reads from __AGENTUITY_SESSION__ and sends events (static, cached)
+	const beaconScript = '<script src="/_agentuity/webanalytics/analytics.js" async></script>';
+	const injection = configScript + sessionScript + beaconScript;
+	
+	// Inject before </head> or at start of <body>
+	if (html.includes('</head>')) {
+		return html.replace('</head>', injection + '</head>');
+	}
+	if (html.includes('<body')) {
+		return html.replace(/<body([^>]*)>/, \`<body$1>\${injection}\`);
+	}
+	return injection + html;
+}
+
+// Serve analytics routes
+function registerAnalyticsRoutes(app: ReturnType<typeof createRouter>): void {
+	// Dynamic session config script - sets cookies and returns session/thread IDs
+	// This endpoint is NOT cached - it generates unique session data per request
+	app.get('/_agentuity/webanalytics/session.js', createWebSessionMiddleware(), async (c: Context) => {
+		const sessionId = c.get('sessionId') || '';
+		const thread = c.get('thread');
+		const threadId = thread?.id || '';
+		
+		const sessionScript = \`window.__AGENTUITY_SESSION__={sessionId:"\${sessionId}",threadId:"\${threadId}"};\`;
+		
+		return new Response(sessionScript, {
+			headers: {
+				'Content-Type': 'application/javascript; charset=utf-8',
+				'Cache-Control': 'no-store, no-cache, must-revalidate',
+			},
+		});
+	});
+
+	// Static beacon script - can be cached
+	app.get('/_agentuity/webanalytics/analytics.js', async (c: Context) => {
+		// Beacon waits for window.__AGENTUITY_SESSION__ before sending events
+		const beaconScript = \`(function(){
+var w=window,d=document,c=w.__AGENTUITY_ANALYTICS__;
+if(!c||!c.enabled)return;
+var q=[],t=null,sr=false,E='/_agentuity/webanalytics/collect',geo=null;
+function id(){return crypto.randomUUID?crypto.randomUUID():Date.now()+'-'+Math.random().toString(36).substr(2,9)}
+function base(type){var e={id:id(),timestamp:Date.now(),timezone_offset:new Date().getTimezoneOffset(),event_type:type,url:location.href,path:location.pathname,referrer:d.referrer||'',title:d.title||'',screen_width:screen.width||0,screen_height:screen.height||0,viewport_width:innerWidth||0,viewport_height:innerHeight||0,device_pixel_ratio:devicePixelRatio||1,user_agent:navigator.userAgent||'',language:navigator.language||''};if(geo){e.country=geo.country||'';e.region=geo.region||'';e.city=geo.city||'';e.timezone=geo.timezone||''}return e}
+fetch('https://agentuity.sh/location').then(function(r){return r.json()}).then(function(g){geo=g;try{sessionStorage.setItem('agentuity_geo',JSON.stringify(g))}catch(e){}}).catch(function(){try{var cached=sessionStorage.getItem('agentuity_geo');if(cached)geo=JSON.parse(cached)}catch(e){}});try{var cached=sessionStorage.getItem('agentuity_geo');if(cached)geo=JSON.parse(cached)}catch(e){}
+function getSession(){return w.__AGENTUITY_SESSION__}
+function waitForSession(cb){var s=getSession();if(s){cb(s);return}var attempts=0,maxAttempts=50;var iv=setInterval(function(){s=getSession();if(s||++attempts>=maxAttempts){clearInterval(iv);cb(s)}},100)}
+function doFlush(s){if(!q.length)return;var events=q.splice(0);if(c.isDevmode){console.debug('[Agentuity Analytics]',events);return}var sid=s?s.sessionId:'',tid=s?s.threadId:'';var p={org_id:c.orgId,project_id:c.projectId,session_id:sid,thread_id:tid,visitor_id:localStorage.getItem('agentuity_vid')||'vid_'+id(),events:events};try{localStorage.setItem('agentuity_vid',p.visitor_id)}catch(e){}navigator.sendBeacon?navigator.sendBeacon(E,JSON.stringify(p)):fetch(E,{method:'POST',body:JSON.stringify(p),keepalive:true}).catch(function(){})}
+function flush(){if(sr){doFlush(getSession())}else{waitForSession(function(s){sr=true;doFlush(s)})}}
+function queue(e){if(c.sampleRate<1&&Math.random()>c.sampleRate)return;q.push(e);q.length>=10?flush():t||(t=setTimeout(function(){t=null;flush()},5000))}
+function pv(){var e=base('pageview');if(performance.getEntriesByType){var n=performance.getEntriesByType('navigation')[0];if(n){e.load_time=Math.round(n.loadEventEnd-n.startTime);e.dom_ready=Math.round(n.domContentLoadedEventEnd-n.startTime);e.ttfb=Math.round(n.responseStart-n.requestStart)}}queue(e)}
+w.addEventListener('visibilitychange',function(){d.visibilityState==='hidden'&&flush()});
+w.addEventListener('pagehide',flush);
+if(c.trackSPANavigation){var op=history.pushState,or=history.replaceState,cp=location.pathname;function ch(){var np=location.pathname;np!==cp&&(cp=np,pv())}history.pushState=function(){op.apply(this,arguments);ch()};history.replaceState=function(){or.apply(this,arguments);ch()};w.addEventListener('popstate',ch)}
+if(c.trackErrors){w.addEventListener('error',function(e){var ev=base('error');ev.event_name='js_error';ev.event_data={message:e.message||'Unknown',filename:e.filename||'',lineno:e.lineno||0};queue(ev)});w.addEventListener('unhandledrejection',function(e){var ev=base('error');ev.event_name='unhandled_rejection';ev.event_data={message:e.reason instanceof Error?e.reason.message:String(e.reason)};queue(ev)})}
+if(c.trackClicks){d.addEventListener('click',function(e){var t=e.target;if(!t)return;var a=t.closest('[data-analytics]');if(!a)return;var ev=base('click');ev.event_name=a.getAttribute('data-analytics');queue(ev)},true)}
+if(c.trackScroll){var ms=new Set(),mx=0;function gs(){var st=w.scrollY||d.documentElement.scrollTop,sh=d.documentElement.scrollHeight-d.documentElement.clientHeight;return sh<=0?100:Math.min(100,Math.round(st/sh*100))}w.addEventListener('scroll',function(){var dp=gs();if(dp>mx)mx=dp;[25,50,75,100].forEach(function(m){if(dp>=m&&!ms.has(m)){ms.add(m);var ev=base('scroll');ev.event_name='scroll_'+m;ev.scroll_depth=m;queue(ev)}})},{passive:true})}
+if(c.trackWebVitals!==false&&typeof PerformanceObserver!=='undefined'){var wvLcp=0,wvCls=0,wvInp=0,wvPath=location.pathname,wvSent={};function wvReset(){wvLcp=0;wvCls=0;wvInp=0;wvSent={}}function wvSend(){var p=wvPath;if(wvLcp>0&&!wvSent.lcp){wvSent.lcp=1;var ev=base('web_vital');ev.event_name='lcp';ev.lcp=Math.round(wvLcp);ev.path=p;queue(ev)}if(!wvSent.cls){wvSent.cls=1;var ev=base('web_vital');ev.event_name='cls';ev.cls=Math.round(wvCls*1000)/1000;ev.path=p;queue(ev)}if(wvInp>0&&!wvSent.inp){wvSent.inp=1;var ev=base('web_vital');ev.event_name='inp';ev.inp=Math.round(wvInp);ev.path=p;queue(ev)}flush()}try{var fcpObs=new PerformanceObserver(function(l){l.getEntries().forEach(function(e){if(e.name==='first-contentful-paint'){var ev=base('web_vital');ev.event_name='fcp';ev.fcp=Math.round(e.startTime);queue(ev);flush();fcpObs.disconnect()}})});fcpObs.observe({type:'paint',buffered:true})}catch(e){}try{new PerformanceObserver(function(l){var entries=l.getEntries();if(entries.length)wvLcp=entries[entries.length-1].startTime}).observe({type:'largest-contentful-paint',buffered:true})}catch(e){}try{new PerformanceObserver(function(l){l.getEntries().forEach(function(e){if(!e.hadRecentInput&&e.value)wvCls+=e.value})}).observe({type:'layout-shift',buffered:true})}catch(e){}try{new PerformanceObserver(function(l){l.getEntries().forEach(function(e){if(e.duration&&e.duration>wvInp)wvInp=e.duration})}).observe({type:'event',buffered:true})}catch(e){}d.addEventListener('visibilitychange',function(){if(d.visibilityState==='hidden')wvSend()});w.addEventListener('pagehide',wvSend);if(c.trackSPANavigation){var wvOp=history.pushState,wvOr=history.replaceState;function wvNav(){var np=location.pathname;if(np!==wvPath){wvSend();wvPath=np;wvReset()}}history.pushState=function(){wvOp.apply(this,arguments);wvNav()};history.replaceState=function(){wvOr.apply(this,arguments);wvNav()};w.addEventListener('popstate',wvNav)}}
+d.readyState==='complete'?pv():w.addEventListener('load',pv);
+w.agentuityAnalytics={track:function(n,p){var e=base('custom');e.event_name=n;if(p)e.event_data=p;queue(e)},flush:flush};
+})();\`;
+		
+		return new Response(beaconScript, {
+			headers: {
+				'Content-Type': 'application/javascript; charset=utf-8',
+				'Cache-Control': 'public, max-age=3600',
+			},
+		});
+	});
+}
+`
+		: `
+// Analytics disabled
+function injectAnalytics(html: string): string {
+	return html;
+}
+function registerAnalyticsRoutes(_app: ReturnType<typeof createRouter>): void {}
 `;
 
 	// Web routes (runtime mode detection)
@@ -207,6 +333,9 @@ const isDevelopment = () => getEnv('NODE' + '_' + 'ENV') !== 'production';
 	if (hasWebFrontend) {
 		webRoutes = `
 // Web routes - Runtime mode detection (dev proxies to Vite, prod serves static)
+// Note: Session/thread cookies are set by /_agentuity/webanalytics/session.js (loaded via script tag)
+// This keeps the HTML response static and cacheable
+
 if (isDevelopment()) {
 	// Development mode: Proxy HTML from Vite to enable React Fast Refresh
 	const VITE_ASSET_PORT = parseInt(process.env.VITE_PORT || '${vitePort || 5173}', 10);
@@ -219,12 +348,15 @@ if (isDevelopment()) {
 			const res = await fetch(viteUrl, { signal: AbortSignal.timeout(10000) });
 
 			// Get HTML text and transform relative paths to absolute
-			const html = await res.text();
-			const transformedHtml = html
+			let html = await res.text();
+			html = html
 				.replace(/src="\\.\\//g, 'src="/src/web/')
 				.replace(/href="\\.\\//g, 'href="/src/web/');
 
-			return new Response(transformedHtml, {
+			// Inject analytics config and script (session/thread read from cookies by beacon)
+			html = injectAnalytics(html);
+
+			return new Response(html, {
 				status: res.status,
 				headers: res.headers,
 			});
@@ -255,15 +387,24 @@ if (isDevelopment()) {
 } else {
 	// Production mode: Serve static files from bundled output
 	const indexHtmlPath = import.meta.dir + '/client/index.html';
-	const indexHtml = existsSync(indexHtmlPath)
+	const baseIndexHtml = existsSync(indexHtmlPath)
 		? readFileSync(indexHtmlPath, 'utf-8')
 		: '';
 	
-	if (!indexHtml) {
+	if (!baseIndexHtml) {
 		otel.logger.warn('Production HTML not found at %s', indexHtmlPath);
 	}
+
+	const prodHtmlHandler = (c: Context) => {
+		if (!baseIndexHtml) {
+			return c.text('Production build incomplete', 500);
+		}
+		// Inject analytics config and script (session/thread loaded via session.js)
+		const html = injectAnalytics(baseIndexHtml);
+		return c.html(html);
+	};
 	
-	app.get('/', (c: Context) => indexHtml ? c.html(indexHtml) : c.text('Production build incomplete', 500));
+	app.get('/', prodHtmlHandler);
 
 	// Serve static assets from /assets/* (Vite bundled output)
 	app.use('/assets/*', serveStatic({ root: import.meta.dir + '/client' }));
@@ -285,7 +426,7 @@ if (isDevelopment()) {
 		if (/\\.[a-zA-Z0-9]+$/.test(path)) {
 			return c.notFound();
 		}
-		return c.html(indexHtml);
+		return prodHtmlHandler(c);
 	});
 }
 `;
@@ -412,6 +553,8 @@ ${imports.join('\n')}
 
 ${modeDetection}
 
+${analyticsHelper}
+
 // Step 0: Bootstrap runtime environment (load profile-specific .env files)
 // Only in development - production env vars are injected by platform
 // This must happen BEFORE any imports that depend on environment variables
@@ -482,6 +625,10 @@ await sessionProvider.initialize(appState);
 // Step 6: Mount routes (AFTER middleware is applied)
 
 ${healthRoutes}
+
+// Register analytics routes (if enabled)
+registerAnalyticsRoutes(app);
+
 ${assetProxyRoutes}
 ${apiMount}
 ${workbenchApiMount}

package/src/cmd/build/vite/agent-discovery.ts

@@ -311,6 +311,7 @@ function extractAgentMetadata(
  */
 async function extractEvalMetadata(
 	evalsPath: string,
+	relativeEvalsPath: string,
 	agentId: string,
 	projectId: string,
 	deploymentId: string,
@@ -325,7 +326,7 @@ async function extractEvalMetadata(
 		const evalsSource = await evalsFile.text();
 		return extractEvalsFromSource(
 			evalsSource,
-			evalsPath,
+			relativeEvalsPath,
 			agentId,
 			projectId,
 			deploymentId,
@@ -569,8 +570,10 @@ export async function discoverAgents(
 				// 2. Check for evals in separate eval.ts file in same directory
 				const agentDir = dirname(filePath);
 				const evalsPath = join(agentDir, 'eval.ts');
+				const relativeEvalsPath = relative(rootDir, evalsPath);
 				const evalsInSeparateFile = await extractEvalMetadata(
 					evalsPath,
+					relativeEvalsPath,
 					agentMetadata.agentId,
 					projectId,
 					deploymentId,

package/src/cmd/build/vite/index.ts

@@ -96,7 +96,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 			const lifecycleResult = await generateLifecycleTypes(rootDir, srcDir, logger);
 			logger.debug(`[vite-plugin] generateLifecycleTypes returned: ${lifecycleResult}`);
 
-			// Generate entry file (pass workbench config for route mounting)
+			// Generate entry file (pass workbench and analytics config)
 			await generateEntryFile({
 				rootDir,
 				projectId,
@@ -104,6 +104,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 				logger,
 				mode: dev ? 'dev' : 'prod',
 				workbench: workbenchConfig.enabled ? workbenchConfig : undefined,
+				analytics: config?.analytics,
 			});
 
 			logger.trace('buildStart: Discovery complete');

package/src/cmd/build/vite/registry-generator.ts

@@ -84,6 +84,43 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 		});
 	}
 
+	// Collect eval files that need to be imported for createEval calls to run
+	// These are eval.ts files in the same directory as agents that have evals
+	const evalImports: string[] = [];
+	const seenEvalPaths = new Set<string>();
+
+	for (const agent of sortedAgents) {
+		if (agent.evals && agent.evals.length > 0) {
+			// Check if any eval comes from a separate eval.ts file (not the agent file itself)
+			for (const evalMeta of agent.evals) {
+				// Skip if eval is defined in the agent file itself
+				if (evalMeta.filename === agent.filename) continue;
+
+				// Build the relative path for the eval file
+				let evalRelativePath = evalMeta.filename;
+				if (evalRelativePath.startsWith('./agent/')) {
+					evalRelativePath = evalRelativePath
+						.replace(/^\.\/agent\//, '../agent/')
+						.replace(/\.tsx?$/, '.js');
+				} else if (evalRelativePath.startsWith('src/agent/')) {
+					evalRelativePath = evalRelativePath
+						.replace(/^src\/agent\//, '../agent/')
+						.replace(/\.tsx?$/, '.js');
+				} else if (evalRelativePath.includes('/src/agent/')) {
+					// Handle absolute paths by extracting the relative part
+					evalRelativePath = evalRelativePath
+						.replace(/^.*\/src\/agent\//, '../agent/')
+						.replace(/\.tsx?$/, '.js');
+				}
+				// Avoid duplicate imports
+				if (!seenEvalPaths.has(evalRelativePath)) {
+					seenEvalPaths.add(evalRelativePath);
+					evalImports.push(`import '${evalRelativePath}';`);
+				}
+			}
+		}
+	}
+
 	// Generate imports for all agents
 	const imports = sortedAgents
 		.map(({ name, filename }) => {
@@ -172,11 +209,21 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 		})
 		.join('\n');
 
+	// Build eval imports section (side-effect imports for createEval registration)
+	const evalImportsSection =
+		evalImports.length > 0
+			? `
+// Eval file imports (side-effect imports to register evals via createEval)
+${evalImports.join('\n')}
+`
+			: '';
+
 	const generatedContent = `// @generated
 // Auto-generated by Agentuity - DO NOT EDIT
 ${imports}
 import type { AgentRunner } from '@agentuity/runtime';
 import type { InferInput, InferOutput } from '@agentuity/core';
+${evalImportsSection}
 
 // ============================================================================
 // Schema Type Exports