@agentuity/cli 0.0.60 → 0.0.62

package/src/cmd/build/plugin.ts

@@ -8,8 +8,10 @@ import {
 	parseEvalMetadata,
 	analyzeWorkbench,
 	checkRouteConflicts,
+	generateLifecycleTypes,
+	findCreateAppEndPosition,
 } from './ast';
-import type { WorkbenchConfig } from '@agentuity/core';
+import { StructuredError, type WorkbenchConfig } from '@agentuity/core';
 import { applyPatch, generatePatches } from './patch';
 import { detectSubagent } from '../../utils/detectSubagent';
 import { createLogger } from '@agentuity/server';
@@ -26,6 +28,37 @@ function toPascalCase(str: string): string {
 	return camel.charAt(0).toUpperCase() + camel.slice(1);
 }
 
+/**
+ * Setup lifecycle types by analyzing app.ts for setup() function
+ */
+async function setupLifecycleTypes(
+	rootDir: string,
+	outDir: string,
+	srcDir: string,
+	logger: ReturnType<typeof createLogger>
+): Promise<boolean> {
+	// Look for app.ts in both root and src directories
+	const rootAppFile = join(dirname(srcDir), 'app.ts');
+	const srcAppFile = join(srcDir, 'app.ts');
+
+	let appFile = '';
+	if (await Bun.file(rootAppFile).exists()) {
+		appFile = rootAppFile;
+	} else if (await Bun.file(srcAppFile).exists()) {
+		appFile = srcAppFile;
+	}
+
+	if (!appFile || !(await Bun.file(appFile).exists())) {
+		return false;
+	}
+
+	try {
+		return await generateLifecycleTypes(rootDir, outDir, appFile);
+	} catch (error) {
+		logger.fatal('Failed to generate lifecycle types:', error);
+	}
+}
+
 /**
  * Setup workbench configuration by analyzing app.ts file
  */
@@ -70,6 +103,9 @@ async function setupWorkbench(srcDir: string): Promise<WorkbenchConfig | null> {
 	return workbenchConfig;
 }
 
+const AgentIdentifierCollisionError = StructuredError('AgentIdentifierCollisionError');
+const SubAgentNameCollisionError = StructuredError('SubAgentNameCollisionError');
+
 function generateAgentRegistry(srcDir: string, agentInfo: Array<Record<string, string>>) {
 	// Separate parent agents and subagents
 	const parentAgents = agentInfo.filter((a) => !a.parent);
@@ -103,11 +139,12 @@ function generateAgentRegistry(srcDir: string, agentInfo: Array<Record<string, s
 	}
 
 	if (collisions.length > 0) {
-		throw new Error(
-			`Agent identifier naming collisions detected:\n${collisions.join('\n')}\n\n` +
+		throw new AgentIdentifierCollisionError({
+			message:
+				`Agent identifier naming collisions detected:\n${collisions.join('\n')}\n\n` +
 				`This occurs when different agent names produce the same camelCase identifier.\n` +
-				`Please rename your agents to avoid this collision.`
-		);
+				`Please rename your agents to avoid this collision.`,
+		});
 	}
 
 	// Generate imports for all agents
@@ -133,11 +170,12 @@ function generateAgentRegistry(srcDir: string, agentInfo: Array<Record<string, s
 
 			// Check for collision with reserved agent properties
 			if (reservedAgentProperties.includes(childPropertyName)) {
-				throw new Error(
-					`Subagent property name collision detected: "${childPropertyName}" in parent "${parentAgent.name}"\n` +
+				throw new SubAgentNameCollisionError({
+					message:
+						`Subagent property name collision detected: "${childPropertyName}" in parent "${parentAgent.name}"\n` +
 						`The child name "${child.name}" conflicts with a reserved agent property (${reservedAgentProperties.join(', ')}).\n` +
-						`Please rename the subagent to avoid this collision.`
-				);
+						`Please rename the subagent to avoid this collision.`,
+				});
 			}
 		}
 	}
@@ -263,6 +301,11 @@ import type { AgentRunner, Logger } from '@agentuity/runtime';
 import type { KeyValueStorage, ObjectStorage, StreamStorage, VectorStorage } from '@agentuity/core';
 import type { Agent } from '@agentuity/react';
 
+/**
+ * Registry of all agents in this application.
+ * Provides strongly-typed access to agent metadata and runner functions.
+ * Auto-generated from your agent files during build.
+ */
 export const agentRegistry = {
 ${registry}
 } as const;
@@ -330,11 +373,22 @@ export function getBuildMetadata(): Partial<BuildMetadata> {
 	return metadata;
 }
 
+const AgentNameDuplicateError = StructuredError('AgentNameDuplicateError');
+const MetadataMissingError = StructuredError('MetadataMissingError');
+const MetadataPropertyMissingError = StructuredError('MetadataPropertyMissingError')<{
+	name: string;
+}>();
+const SubAgentMissingError = StructuredError('SubAgentMissingError');
+
 const AgentuityBundler: BunPlugin = {
 	name: 'Agentuity Bundler',
 	setup(build) {
 		const rootDir = resolve(build.config.root ?? '.');
 		const srcDir = join(rootDir, 'src');
+		const outDir = build.config.outdir;
+		if (!outDir) {
+			throw new Error('missing outdir must be set');
+		}
 		const projectId = build.config.define?.['process.env.AGENTUITY_CLOUD_PROJECT_ID']
 			? JSON.parse(build.config.define['process.env.AGENTUITY_CLOUD_PROJECT_ID'])
 			: '';
@@ -401,9 +455,9 @@ const AgentuityBundler: BunPlugin = {
 				for (const [, kv] of agentMetadata) {
 					const found = kv.get('name');
 					if (newAgentName === found) {
-						throw new Error(
-							`The agent in ${kv.get('filename')} and the agent in ${md.get('filename')} have the same name (${found}). Agent Names must be unique within a project.`
-						);
+						throw new AgentNameDuplicateError({
+							message: `The agent in ${kv.get('filename')} and the agent in ${md.get('filename')} have the same name (${found}). Agent Names must be unique within a project.`,
+						});
 					}
 				}
 
@@ -499,7 +553,9 @@ const AgentuityBundler: BunPlugin = {
 					if (hasAgent) {
 						const md = agentMetadata.get(name);
 						if (!md) {
-							throw new Error(`Couldn't find agent metadata for ${route}`);
+							throw new MetadataMissingError({
+								message: `Couldn't find agent metadata for ${route}`,
+							});
 						}
 						agentDetail = {
 							name,
@@ -550,13 +606,47 @@ const AgentuityBundler: BunPlugin = {
 					}
 				}
 
+				// Register standalone agents (agents without routes)
+				const routeAgentNames = new Set(
+					agentInfo
+						.filter((a) => {
+							// Check if this agent was added via a route (has a corresponding route file)
+							const agentPath = a.path.replace(/^\./, '').replace(/\/agent$/, '/route');
+							return routes.has(agentPath.replace(/^\/src\//, './'));
+						})
+						.map((a) => a.name)
+				);
+
+				for (const agentDetail of agentInfo) {
+					if (!routeAgentNames.has(agentDetail.name)) {
+						// This is a standalone agent - register it without a route
+						const agentPath = agentDetail.path;
+						const agentDirPath = agentPath.replace(/\/agent$/, '');
+						const evalsPath = join(srcDir, agentDirPath.replace(/^\./, ''), 'eval.ts');
+						const evalsImport = existsSync(evalsPath)
+							? `\n    require('./src/${agentDirPath.replace(/^\.\//, '')}/eval');`
+							: '';
+						const isSubagent = !!agentDetail.parent;
+						const agentRegistrationName = isSubagent
+							? `${agentDetail.parent}.${agentDetail.name}`
+							: agentDetail.name;
+
+						const buffer = `await (async() => {
+    const { registerAgent } = await import('@agentuity/runtime');
+    const agent = require('./src${agentPath}').default;
+    registerAgent("${agentRegistrationName}", agent);${evalsImport}
+})();`;
+						inserts.push(buffer);
+					}
+				}
+
 				const indexFile = join(srcDir, 'web', 'index.html');
 
-				if (existsSync(indexFile)) {
-					// Setup workbench configuration - evaluate fresh each time during builds
-					const workbenchConfig = await setupWorkbench(srcDir);
+				// Setup workbench configuration - evaluate fresh each time during builds
+				const workbenchConfig = await setupWorkbench(srcDir);
 
-					inserts.unshift(`await (async () => {
+				if (existsSync(indexFile)) {
+					inserts.push(`await (async () => {
     const { serveStatic } = require('hono/bun');
     const { getRouter, registerDevModeRoutes } = await import('@agentuity/runtime');
     const router = getRouter()!;
@@ -600,6 +690,42 @@ const AgentuityBundler: BunPlugin = {
 })();`);
 				}
 
+				// Add standalone agents (agents without routes) to agentInfo
+				// These agents can still be called by other agents or routes via ctx.agent
+				const registeredIdentifiers = new Set(agentInfo.map((a) => a.identifier));
+				for (const [identifier, md] of agentMetadata) {
+					if (!registeredIdentifiers.has(identifier)) {
+						// md.get('filename') can be either absolute or relative to rootDir
+						const filename = md.get('filename')!;
+						const absolutePath = filename.startsWith('/')
+							? filename
+							: join(rootDir, filename);
+
+						// Convert to path relative to srcDir like route-based agents
+						// e.g., /path/to/src/agents/lifecycle/agent.ts -> ./agents/lifecycle/agent
+						const agentPath = absolutePath.replace(srcDir, '.').replace('.ts', '');
+
+						// Extract folder name as agent name (same as route-based logic)
+						const folderName = basename(dirname(absolutePath));
+
+						const { isSubagent, parentName } = detectSubagent(absolutePath, srcDir);
+
+						const agentDetail: Record<string, string> = {
+							name: folderName,
+							id: md.get('id')!,
+							path: agentPath,
+							filename: absolutePath,
+							identifier: md.get('identifier')!,
+							description: md.get('description') ?? '',
+							agentId: md.get('agentId')!,
+						};
+						if (isSubagent && parentName) {
+							agentDetail.parent = parentName;
+						}
+						agentInfo.push(agentDetail);
+					}
+				}
+
 				// Only generate registry if there are agents
 				// Note: We don't import the registry here because:
 				// 1. Evals are already imported when agents are registered (see line 421-422)
@@ -607,34 +733,53 @@ const AgentuityBundler: BunPlugin = {
 				// 3. Importing it causes bundler resolution issues since it's generated during build
 				generateAgentRegistry(srcDir, agentInfo);
 
-				// create the workbench routes
-				inserts.push(`await (async() => {
+				// Generate lifecycle types if setup() is present in app.ts
+				await setupLifecycleTypes(rootDir, outDir, srcDir, logger);
+
+				// Only create the workbench metadata route if workbench is actually configured
+				if (workbenchConfig) {
+					inserts.push(`await (async() => {
     const { createWorkbenchMetadataRoute, getRouter } = await import('@agentuity/runtime');
     const router = getRouter()!;
 	router.get('/_agentuity/workbench/metadata.json', createWorkbenchMetadataRoute());
 })();`);
+				}
 
 				const file = Bun.file(args.path);
 				let contents = await file.text();
-				let inserted = false;
-				let index = contents.indexOf(' createApp(');
-				if (index < 0) {
-					index = contents.indexOf(' createApp (');
-				}
-				if (index < 0) {
-					throw new Error(`couldn't find the required createApp function in ${args.path}`);
-				}
-				const endSemi = contents.indexOf(');', index);
-				if (endSemi > 0) {
+				// Use AST-based parsing to reliably find createApp statement end
+				const insertPos = findCreateAppEndPosition(contents);
+
+				// Add initialization call after all agent registrations
+				const setupCall = `
+// Initialize providers and run agent setup callbacks after all agents are registered
+await (async() => {
+    const { runAgentSetups, getThreadProvider, getSessionProvider, getAppState } = await import('@agentuity/runtime');
+
+	const threadProvider = getThreadProvider();
+    const sessionProvider = getSessionProvider();
+
+	const state = getAppState();
+
+    // Initialize providers first
+    await threadProvider.initialize(state);
+	await sessionProvider.initialize(state);
+    
+    // Then run agent setups
+    await runAgentSetups(state);
+})();`;
+
+				if (insertPos > 0) {
 					contents =
-						contents.slice(0, endSemi + 2) +
+						contents.slice(0, insertPos) +
 						'\n\n' +
 						inserts.join('\n') +
-						contents.slice(endSemi + 2);
-					inserted = true;
-				}
-				if (!inserted) {
-					contents += `\n${inserts.join('\n')}`;
+						setupCall +
+						contents.slice(insertPos);
+				} else {
+					// Fallback: append to end if AST parsing fails
+					logger.warn('Could not find createApp in AST, appending code to end of file');
+					contents += `\n${inserts.join('\n')}${setupCall}`;
 				}
 
 				// generate the build metadata
@@ -649,22 +794,40 @@ const AgentuityBundler: BunPlugin = {
 
 				for (const [, v] of agentMetadata) {
 					if (!v.has('filename')) {
-						throw new Error('agent metadata is missing expected filename property');
+						throw new MetadataPropertyMissingError({
+							name: 'filename',
+							message: 'agent metadata is missing expected filename property',
+						});
 					}
 					if (!v.has('id')) {
-						throw new Error('agent metadata is missing expected id property');
+						throw new MetadataPropertyMissingError({
+							name: 'id',
+							message: 'agent metadata is missing expected id property',
+						});
 					}
 					if (!v.has('identifier')) {
-						throw new Error('agent metadata is missing expected identifier property');
+						throw new MetadataPropertyMissingError({
+							name: 'identifier',
+							message: 'agent metadata is missing expected identifier property',
+						});
 					}
 					if (!v.has('version')) {
-						throw new Error('agent metadata is missing expected version property');
+						throw new MetadataPropertyMissingError({
+							name: 'version',
+							message: 'agent metadata is missing expected version property',
+						});
 					}
 					if (!v.has('name')) {
-						throw new Error('agent metadata is missing expected name property');
+						throw new MetadataPropertyMissingError({
+							name: 'name',
+							message: 'agent metadata is missing expected name property',
+						});
 					}
 					if (!v.has('agentId')) {
-						throw new Error('agent metadata is missing expected agentId property');
+						throw new MetadataPropertyMissingError({
+							name: 'agentId',
+							message: 'agent metadata is missing expected agentId property',
+						});
 					}
 
 					const parentName = v.get('parent');
@@ -687,10 +850,11 @@ const AgentuityBundler: BunPlugin = {
 					);
 					if (!parentExists) {
 						const subagentPaths = subagents.map((s) => s.get('filename')).join(', ');
-						throw new Error(
-							`Subagent(s) [${subagentPaths}] reference parent "${parentName}" which does not exist. ` +
-								`Ensure the parent agent is defined.`
-						);
+						throw new SubAgentMissingError({
+							message:
+								`Subagent(s) [${subagentPaths}] reference parent "${parentName}" which does not exist. ` +
+								`Ensure the parent agent is defined.`,
+						});
 					}
 				}
 
@@ -794,7 +958,7 @@ const AgentuityBundler: BunPlugin = {
 					metadata.agents!.push(agentData);
 				}
 
-				const routeMappingJSFile = Bun.file(join(build.config.outdir!, '.routemapping.json'));
+				const routeMappingJSFile = Bun.file(join(outDir, '.routemapping.json'));
 				await routeMappingJSFile.write(JSON.stringify(routeMapping));
 
 				return {

package/src/cmd/cloud/agent/get.ts

@@ -11,8 +11,11 @@ export const getSubcommand = createSubcommand({
 	description: 'Get details about a specific agent',
 	requires: { auth: true, apiClient: true, project: true },
 	examples: [
-		getCommand('cloud agent get agent_abc123'),
-		getCommand('--json cloud agent get agent_abc123'),
+		{ command: getCommand('cloud agent get agent_abc123'), description: 'Get item details' },
+		{
+			command: getCommand('--json cloud agent get agent_abc123'),
+			description: 'Show output in JSON format',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/agent/index.ts

@@ -1,11 +1,16 @@
 import { createCommand } from '../../../types';
 import { listSubcommand } from './list';
 import { getSubcommand } from './get';
+import { getCommand } from '../../../command-prefix';
 
 export const agentCommand = createCommand({
 	name: 'agent',
 	description: 'Manage agents',
 	aliases: ['agents'],
 	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('cloud agent list'), description: 'List all agents' },
+		{ command: getCommand('cloud agent get <id>'), description: 'Get agent details' },
+	],
 	subcommands: [listSubcommand, getSubcommand],
 });

package/src/cmd/cloud/agent/list.ts

@@ -13,9 +13,9 @@ export const listSubcommand = createSubcommand({
 	aliases: ['ls'],
 	requires: { auth: true, apiClient: true, project: true },
 	examples: [
-		getCommand('cloud agent list'),
-		getCommand('cloud agent list --verbose'),
-		getCommand('--json cloud agent list'),
+		{ command: getCommand('cloud agent list'), description: 'List items' },
+		{ command: getCommand('cloud agent list --verbose'), description: 'Use verbose option' },
+		{ command: getCommand('--json cloud agent list'), description: 'Show output in JSON format' },
 	],
 	schema: {
 		options: z.object({

package/src/cmd/cloud/apikey/create.ts

@@ -16,11 +16,20 @@ export const createSubcommand = createSubcommandHelper({
 	description: 'Create a new API key',
 	tags: ['destructive', 'creates-resource', 'slow', 'requires-auth'],
 	examples: [
-		getCommand('cloud apikey create --name "My API Key" --expires-at 1y'),
-		getCommand('cloud apikey create --name "Short-lived Key" --expires-at 30d'),
-		getCommand(
-			'cloud apikey create --name "Production Key" --expires-at 2026-01-01T00:00:00Z --confirm'
-		),
+		{
+			command: getCommand('cloud apikey create --name "My API Key" --expires-at 1y'),
+			description: 'Create API key with 1 year expiration',
+		},
+		{
+			command: getCommand('cloud apikey create --name "Short-lived Key" --expires-at 30d'),
+			description: 'Create API key with 30 day expiration',
+		},
+		{
+			command: getCommand(
+				'cloud apikey create --name "Production Key" --expires-at 2026-01-01T00:00:00Z --confirm'
+			),
+			description: 'Create API key with specific date and skip confirmation',
+		},
 	],
 	requires: { auth: true, apiClient: true, org: true },
 	optional: { project: true },

package/src/cmd/cloud/apikey/delete.ts

@@ -17,9 +17,9 @@ export const deleteSubcommand = createSubcommand({
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	idempotent: true,
 	examples: [
-		getCommand('cloud apikey delete <id>'),
-		getCommand('cloud apikey del <id>'),
-		getCommand('cloud apikey rm <id>'),
+		{ command: getCommand('cloud apikey delete <id>'), description: 'Delete item' },
+		{ command: getCommand('cloud apikey del <id>'), description: 'Run <id> command' },
+		{ command: getCommand('cloud apikey rm <id>'), description: 'Delete item' },
 	],
 	requires: { auth: true, apiClient: true },
 	schema: {

package/src/cmd/cloud/apikey/get.ts

@@ -9,7 +9,7 @@ export const getSubcommand = createSubcommand({
 	name: 'get',
 	description: 'Get a specific API key by id',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	examples: [getCommand('cloud apikey get <id>')],
+	examples: [{ command: getCommand('cloud apikey get <id>'), description: 'Get item details' }],
 	requires: { auth: true, apiClient: true },
 	idempotent: true,
 	schema: {

package/src/cmd/cloud/apikey/index.ts

@@ -3,11 +3,19 @@ import { createSubcommand } from './create';
 import { listSubcommand } from './list';
 import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
+import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
 	name: 'apikey',
 	description: 'Manage API keys',
 	tags: ['fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('cloud apikey list'), description: 'List all API keys' },
+		{
+			command: getCommand('cloud apikey create --name "My Key" --expires-at 1y'),
+			description: 'Create new API key',
+		},
+	],
 	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand],
 });
 export default command;

package/src/cmd/cloud/apikey/list.ts

@@ -9,7 +9,10 @@ export const listSubcommand = createSubcommand({
 	aliases: ['ls'],
 	description: 'List all API keys',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	examples: [getCommand('cloud apikey list'), getCommand('cloud apikey ls')],
+	examples: [
+		{ command: getCommand('cloud apikey list'), description: 'List items' },
+		{ command: getCommand('cloud apikey ls'), description: 'List items' },
+	],
 	requires: { auth: true, apiClient: true },
 	idempotent: true,
 	schema: {

package/src/cmd/cloud/db/create.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod';
-import { createResources } from '@agentuity/server';
+import { createResources, APIError } from '@agentuity/server';
 import { createSubcommand as defineSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCatalystAPIClient } from '../../../config';
 import { getCommand } from '../../../command-prefix';
 import { isDryRunMode, outputDryRun } from '../../../explain';
+import { ErrorCode } from '../../../errors';
 
 export const createSubcommand = defineSubcommand({
 	name: 'create',
@@ -14,9 +15,10 @@ export const createSubcommand = defineSubcommand({
 	idempotent: false,
 	requires: { auth: true, org: true, region: true },
 	examples: [
-		getCommand('cloud db create'),
-		getCommand('cloud db new'),
-		getCommand('--dry-run cloud db create'),
+		{ command: getCommand('cloud db create'), description: 'Create new item' },
+		{ command: getCommand('cloud db new'), description: 'Run new command' },
+		{ command: getCommand('cloud db create --name my-db'), description: 'Create new item' },
+		{ command: getCommand('--dry-run cloud db create'), description: 'Create new item' },
 	],
 	schema: {
 		options: z.object({
@@ -49,24 +51,37 @@ export const createSubcommand = defineSubcommand({
 
 		const catalystClient = getCatalystAPIClient(config, logger, auth);
 
-		const created = await tui.spinner({
-			message: `Creating database in ${region}`,
-			clearOnSuccess: true,
-			callback: async () => {
-				return createResources(catalystClient, orgId, region!, [
-					{ type: 'db', name: opts.name },
-				]);
-			},
-		});
-
-		if (created.length > 0) {
-			tui.success(`Created database: ${tui.bold(created[0].name)}`);
-			return {
-				success: true,
-				name: created[0].name,
-			};
-		} else {
-			tui.fatal('Failed to create database');
+		try {
+			const created = await tui.spinner({
+				message: `Creating database in ${region}`,
+				clearOnSuccess: true,
+				callback: async () => {
+					return await createResources(catalystClient, orgId, region!, [
+						{ type: 'db', name: opts.name },
+					]);
+				},
+			});
+			if (created.length > 0) {
+				if (!options.json) {
+					tui.success(`Created database: ${tui.bold(created[0].name)}`);
+				}
+				return {
+					success: true,
+					name: created[0].name,
+				};
+			} else {
+				tui.fatal('Failed to create database');
+			}
+		} catch (ex) {
+			if (ex instanceof APIError) {
+				if (ex.status === 409) {
+					tui.fatal(
+						`database with the name "${opts.name}" already exists. Use another name or don't specify --name for a unique name to be generated automatically.`,
+						ErrorCode.INVALID_ARGUMENT
+					);
+				}
+			}
+			throw ex;
 		}
 	},
 });