@agentuity/cli 2.0.11 → 3.0.0-alpha.0

package/src/cmd/ai/prompt/agent.md

@@ -1,305 +0,0 @@
-# Agents Folder Guide
-
-This folder contains AI agents for your Agentuity application. Each agent is organized in its own subdirectory.
-
-## Generated Types
-
-The `src/generated/` folder contains auto-generated TypeScript files:
-
-- `registry.ts` - Agent registry with strongly-typed agent definitions and schema types
-- `app.ts` - Application entry point (regenerated on every build)
-
-**Important:** Never edit files in `src/generated/` - they are overwritten on every build.
-
-Import generated types in your agents:
-
-```typescript
-import type { HelloInput, HelloOutput } from '../generated/registry';
-```
-
-## Directory Structure
-
-Each agent folder must contain:
-
-- **agent.ts** (required) - Agent definition with schema and handler
-
-Example structure:
-
-```
-src/agent/
-├── hello/
-│   └── agent.ts
-├── process-data/
-│   └── agent.ts
-└── (generated files in src/generated/)
-```
-
-**Note:** HTTP routes are defined separately in `src/api/` - see the API folder guide for details.
-
-## Creating an Agent
-
-### Basic Agent (agent.ts)
-
-```typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent('my-agent', {
-	description: 'What this agent does',
-	schema: {
-		input: s.object({
-			name: s.string(),
-			age: s.number(),
-		}),
-		output: s.string(),
-	},
-	handler: async (ctx, input) => {
-		// Access context: ctx.app, ctx.config, ctx.logger, ctx.kv, ctx.vector, ctx.stream
-		return `Hello, ${input.name}! You are ${input.age} years old.`;
-	},
-});
-
-export default agent;
-```
-
-### Agent with Lifecycle (setup/shutdown)
-
-```typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent('lifecycle-agent', {
-	description: 'Agent with setup and shutdown',
-	schema: {
-		input: s.object({ message: s.string() }),
-		output: s.object({ result: s.string() }),
-	},
-	setup: async (app) => {
-		// Initialize resources (runs once on startup)
-		// app contains: appName, version, startedAt, config
-		return {
-			agentId: `agent-${Math.random().toString(36).substr(2, 9)}`,
-			connectionPool: ['conn-1', 'conn-2'],
-		};
-	},
-	handler: async (ctx, input) => {
-		// Access setup config via ctx.config (fully typed)
-		ctx.logger.info('Agent ID:', ctx.config.agentId);
-		ctx.logger.info('Connections:', ctx.config.connectionPool);
-		return { result: `Processed: ${input.message}` };
-	},
-	shutdown: async (app, config) => {
-		// Cleanup resources (runs on shutdown)
-		console.log('Shutting down agent:', config.agentId);
-	},
-});
-
-export default agent;
-```
-
-### Agent with Event Listeners
-
-```typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent('event-agent', {
-	schema: {
-		input: s.object({ data: s.string() }),
-		output: s.string(),
-	},
-	handler: async (ctx, input) => {
-		return `Processed: ${input.data}`;
-	},
-});
-
-agent.addEventListener('started', (eventName, agent, ctx) => {
-	ctx.logger.info('Agent started');
-});
-
-agent.addEventListener('completed', (eventName, agent, ctx) => {
-	ctx.logger.info('Agent completed');
-});
-
-agent.addEventListener('errored', (eventName, agent, ctx, error) => {
-	ctx.logger.error('Agent errored:', error);
-});
-
-export default agent;
-```
-
-## Agent Context (ctx)
-
-The handler receives a context object with:
-
-- **ctx.app** - Application state (appName, version, startedAt, config from createApp)
-- **ctx.config** - Agent-specific config (from setup return value, fully typed)
-- **ctx.logger** - Structured logger (info, warn, error, debug, trace)
-- **ctx.tracer** - OpenTelemetry tracer for custom spans
-- **ctx.sessionId** - Unique session identifier
-- **ctx.kv** - Key-value storage
-- **ctx.vector** - Vector storage for embeddings
-- **ctx.stream** - Stream storage for real-time data
-- **ctx.state** - In-memory request-scoped state (Map)
-- **ctx.thread** - Thread information for multi-turn conversations
-- **ctx.session** - Session information
-- **ctx.waitUntil** - Schedule background tasks
-
-## Examples
-
-### Using Key-Value Storage
-
-```typescript
-handler: async (ctx, input) => {
-	await ctx.kv.set('users', 'user:123', { name: 'Alice', age: 30 });
-	const result = await ctx.kv.get('users', 'user:123');
-	await ctx.kv.delete('users', 'user:123');
-	const keys = await ctx.kv.getKeys('users');
-	return result.exists ? result.data : null;
-};
-```
-
-### Using Vector Storage
-
-```typescript
-handler: async (ctx, input) => {
-	await ctx.vector.upsert('docs', [
-		{ id: '1', values: [0.1, 0.2, 0.3], metadata: { text: 'Hello' } },
-	]);
-	const results = await ctx.vector.query('docs', [0.1, 0.2, 0.3], { topK: 5 });
-	return results;
-};
-```
-
-### Using Streams
-
-```typescript
-handler: async (ctx, input) => {
-	const stream = await ctx.stream.create('agent-logs');
-	await ctx.stream.write(stream.id, 'Processing step 1');
-	await ctx.stream.write(stream.id, 'Processing step 2');
-	return { streamId: stream.id };
-};
-```
-
-### Background Tasks with waitUntil
-
-```typescript
-handler: async (ctx, input) => {
-	// Schedule background work that continues after response
-	ctx.waitUntil(async () => {
-		await ctx.kv.set('state', 'processed', Date.now());
-		ctx.logger.info('Background task complete');
-	});
-
-	return { status: 'processing' };
-};
-```
-
-### Calling Another Agent
-
-```typescript
-// Import the agent directly
-import otherAgent from '../other-agent/agent';
-
-handler: async (ctx, input) => {
-	const result = await otherAgent.run({ data: input.value });
-	return `Other agent returned: ${result}`;
-};
-```
-
-## Subagents (Nested Agents)
-
-Agents can have subagents organized one level deep. This is useful for grouping related functionality.
-
-### Directory Structure for Subagents
-
-```
-src/agent/
-└── team/              # Parent agent
-    ├── agent.ts       # Parent agent
-    ├── members/       # Subagent
-    │   └── agent.ts
-    └── tasks/         # Subagent
-        └── agent.ts
-```
-
-### Parent Agent
-
-```typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent('team', {
-	description: 'Team Manager',
-	schema: {
-		input: s.object({ action: s.union([s.literal('info'), s.literal('count')]) }),
-		output: s.object({
-			message: s.string(),
-			timestamp: s.string(),
-		}),
-	},
-	handler: async (ctx, { action }) => {
-		return {
-			message: 'Team parent agent - manages members and tasks',
-			timestamp: new Date().toISOString(),
-		};
-	},
-});
-
-export default agent;
-```
-
-### Subagent (Accessing Parent)
-
-```typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-import parentAgent from '../agent';
-
-const agent = createAgent('team.members', {
-	description: 'Members Subagent',
-	schema: {
-		input: s.object({
-			action: s.union([s.literal('list'), s.literal('add'), s.literal('remove')]),
-			name: s.optional(s.string()),
-		}),
-		output: s.object({
-			members: s.array(s.string()),
-			parentInfo: s.optional(s.string()),
-		}),
-	},
-	handler: async (ctx, { action, name }) => {
-		// Call parent agent directly
-		const parentResult = await parentAgent.run({ action: 'info' });
-		const parentInfo = `Parent says: ${parentResult.message}`;
-
-		let members = ['Alice', 'Bob'];
-		if (action === 'add' && name) {
-			members.push(name);
-		}
-
-		return { members, parentInfo };
-	},
-});
-
-export default agent;
-```
-
-### Key Points About Subagents
-
-- **One level deep**: Only one level of nesting is supported (no nested subagents)
-- **Access parent**: Import and call parent agents directly
-- **Agent names**: Subagents have dotted names like `"team.members"`
-- **Shared context**: Subagents share the same app context (kv, logger, etc.)
-
-## Rules
-
-- Each agent folder name becomes the agent's route name (e.g., `hello/` → `/agent/hello`)
-- **agent.ts** must export default the agent instance
-- The first argument to `createAgent()` is the agent name (must match folder structure)
-- Input/output schemas are enforced with @agentuity/schema validation
-- Setup return value type automatically flows to ctx.config (fully typed)
-- Use ctx.logger for logging, not console.log
-- Import agents directly to call them (recommended approach)
-- Subagents are one level deep only (team/members/, not team/members/subagent/)

package/src/cmd/ai/prompt/agent.ts

@@ -1,31 +0,0 @@
-import { createSubcommand } from '../../../types';
-import type { CommandContext } from '../../../types';
-import { getCommand } from '../../../command-prefix';
-import { appendHashComment } from './version';
-import agentPromptContent from './agent.md' with { type: 'text' };
-
-export const agentSubcommand = createSubcommand({
-	name: 'agent',
-	description: 'Generate a comprehensive prompt for LLM agents for the agents folder',
-	tags: ['read-only', 'fast'],
-	idempotent: true,
-	examples: [{ command: getCommand('prompt agent'), description: 'Run agent command' }],
-	async handler(_ctx: CommandContext) {
-		const prompt = generateLLMPrompt();
-		console.log(prompt);
-	},
-});
-
-/**
- * Get the raw prompt content without hash.
- */
-export function getPromptContent(): string {
-	return agentPromptContent;
-}
-
-/**
- * Generate the agent prompt with hash comment.
- */
-export function generateLLMPrompt(): string {
-	return appendHashComment(agentPromptContent);
-}

package/src/cmd/build/app-router-detector.ts

@@ -1,320 +0,0 @@
-/**
- * App Router Detector
- *
- * Parses the user's `src/app.ts` to detect whether they pass a `router` property
- * to `createApp()`. If detected, resolves the router variable(s) to their import
- * sources and mount paths.
- *
- * Uses TypeScript's compiler API to reliably detect the pattern, consistent with
- * the lifecycle generator approach.
- */
-
-import ts from 'typescript';
-import { join, dirname, resolve } from 'node:path';
-import { statSync } from 'node:fs';
-import type { Logger } from '../../types';
-
-/**
- * A resolved mount point from `createApp({ router })`.
- */
-export interface DetectedRouteMount {
-	/** Mount path (e.g., '/api', '/api/v1') */
-	path: string;
-	/** Absolute file path of the router module */
-	routerFile: string;
-}
-
-/**
- * Result of detecting explicit router usage in app.ts.
- */
-export interface AppRouterDetection {
-	/** Whether `createApp({ router })` was found */
-	detected: boolean;
-	/** Resolved mount points with their router files */
-	mounts: DetectedRouteMount[];
-}
-
-/**
- * Resolve an import path to an actual file on disk.
- * Tries the path as-is, then with common extensions.
- */
-async function resolveImportFile(fromDir: string, importPath: string): Promise<string | null> {
-	if (!importPath.startsWith('.') && !importPath.startsWith('/')) {
-		return null; // Package import — can't resolve
-	}
-
-	const basePath = resolve(fromDir, importPath);
-	const extensions = ['.ts', '.tsx', '/index.ts', '/index.tsx'];
-
-	const baseFile = Bun.file(basePath);
-	if (await baseFile.exists()) {
-		try {
-			if (statSync(basePath).isFile()) return basePath;
-		} catch {
-			// ignore
-		}
-	}
-
-	for (const ext of extensions) {
-		const candidate = basePath + ext;
-		if (await Bun.file(candidate).exists()) {
-			return candidate;
-		}
-	}
-
-	return null;
-}
-
-/**
- * A router mount extracted from the AST before file resolution.
- */
-interface RawMount {
-	path: string;
-	varName: string;
-}
-
-/**
- * Extract router mounts from a createApp() call using TypeScript's AST.
- * Returns null if no router property found.
- */
-function extractRouterMounts(sourceFile: ts.SourceFile): RawMount[] | null {
-	let result: RawMount[] | null = null;
-
-	function getStringLiteral(node: ts.Expression): string | null {
-		if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
-			return node.text;
-		}
-		return null;
-	}
-
-	function extractMountFromObject(obj: ts.ObjectLiteralExpression): RawMount | null {
-		let path: string | undefined;
-		let varName: string | undefined;
-
-		for (const prop of obj.properties) {
-			if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
-
-			if (prop.name.text === 'path') {
-				path = getStringLiteral(prop.initializer) ?? undefined;
-			}
-			if (prop.name.text === 'router') {
-				if (ts.isIdentifier(prop.initializer)) {
-					varName = prop.initializer.text;
-				}
-			}
-		}
-
-		// Also handle shorthand: { path: '/v1', router } where router is shorthand
-		for (const prop of obj.properties) {
-			if (ts.isShorthandPropertyAssignment(prop) && prop.name.text === 'router') {
-				varName = prop.name.text;
-			}
-		}
-
-		return path && varName ? { path, varName } : null;
-	}
-
-	function processRouterValue(value: ts.Expression): RawMount[] | null {
-		// Form 1: Identifier → createApp({ router: myRouter })
-		if (ts.isIdentifier(value)) {
-			return [{ path: '/api', varName: value.text }];
-		}
-
-		// Form 2: Object → createApp({ router: { path: '/v1', router: myRouter } })
-		if (ts.isObjectLiteralExpression(value)) {
-			const mount = extractMountFromObject(value);
-			return mount ? [mount] : null;
-		}
-
-		// Form 3: Array → createApp({ router: [...] })
-		if (ts.isArrayLiteralExpression(value)) {
-			const mounts: RawMount[] = [];
-			for (const element of value.elements) {
-				if (ts.isObjectLiteralExpression(element)) {
-					const mount = extractMountFromObject(element);
-					if (mount) mounts.push(mount);
-				}
-			}
-			return mounts.length > 0 ? mounts : null;
-		}
-
-		return null;
-	}
-
-	function visit(node: ts.Node): void {
-		if (result) return;
-
-		// Find createApp(...) — with or without await
-		let callExpr: ts.CallExpression | undefined;
-
-		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
-			if (node.expression.text === 'createApp') callExpr = node;
-		} else if (ts.isAwaitExpression(node) && ts.isCallExpression(node.expression)) {
-			const call = node.expression;
-			if (ts.isIdentifier(call.expression) && call.expression.text === 'createApp') {
-				callExpr = call;
-			}
-		}
-
-		if (callExpr && callExpr.arguments.length > 0) {
-			const configArg = callExpr.arguments[0];
-			if (configArg && ts.isObjectLiteralExpression(configArg)) {
-				for (const prop of configArg.properties) {
-					// Handle: router: value
-					if (
-						ts.isPropertyAssignment(prop) &&
-						ts.isIdentifier(prop.name) &&
-						prop.name.text === 'router'
-					) {
-						result = processRouterValue(prop.initializer);
-						return;
-					}
-
-					// Handle shorthand: createApp({ router })
-					if (ts.isShorthandPropertyAssignment(prop) && prop.name.text === 'router') {
-						result = [{ path: '/api', varName: 'router' }];
-						return;
-					}
-				}
-			}
-		}
-
-		ts.forEachChild(node, visit);
-	}
-
-	visit(sourceFile);
-	return result;
-}
-
-/**
- * Build import map from the source file: variable name → import path
- */
-function buildImportMap(sourceFile: ts.SourceFile): Map<string, string> {
-	const importMap = new Map<string, string>();
-
-	for (const stmt of sourceFile.statements) {
-		if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
-
-		const importPath = stmt.moduleSpecifier.text;
-		const clause = stmt.importClause;
-		if (!clause) continue;
-
-		// Default import: import router from './api'
-		if (clause.name) {
-			importMap.set(clause.name.text, importPath);
-		}
-
-		// Named imports: import { v1, v2 } from './routers'
-		if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
-			for (const spec of clause.namedBindings.elements) {
-				importMap.set(spec.name.text, importPath);
-			}
-		}
-	}
-
-	return importMap;
-}
-
-/**
- * Detect whether `src/app.ts` uses `createApp({ router })`.
- *
- * Returns `{ detected: false, mounts: [] }` when:
- * - `src/app.ts` doesn't exist
- * - `createApp()` is called without a `router` property
- * - Router variables can't be resolved to files
- */
-export async function detectExplicitRouter(
-	rootDir: string,
-	logger: Logger
-): Promise<AppRouterDetection> {
-	const noDetection: AppRouterDetection = { detected: false, mounts: [] };
-
-	// Look for app.ts in src/ (standard location), then root
-	let appFile = join(rootDir, 'src', 'app.ts');
-	if (!(await Bun.file(appFile).exists())) {
-		appFile = join(rootDir, 'app.ts');
-		if (!(await Bun.file(appFile).exists())) {
-			logger.trace('[router-detect] No app.ts found');
-			return noDetection;
-		}
-	}
-
-	try {
-		const source = await Bun.file(appFile).text();
-		const appDir = dirname(appFile);
-
-		// Quick bail-out before parsing
-		if (!source.includes('createApp') || !source.includes('router')) {
-			logger.trace('[router-detect] No createApp + router pattern found in %s', appFile);
-			return noDetection;
-		}
-
-		// Parse with TypeScript
-		const sourceFile = ts.createSourceFile(
-			appFile,
-			source,
-			ts.ScriptTarget.Latest,
-			true,
-			ts.ScriptKind.TS
-		);
-
-		const rawMounts = extractRouterMounts(sourceFile);
-		if (!rawMounts || rawMounts.length === 0) {
-			logger.trace('[router-detect] createApp() found but no router property');
-			return noDetection;
-		}
-
-		// Build import map to resolve variable names to file paths
-		const importMap = buildImportMap(sourceFile);
-
-		// Resolve each router variable to its file
-		const mounts: DetectedRouteMount[] = [];
-		for (const { path, varName } of rawMounts) {
-			const importPath = importMap.get(varName);
-			if (!importPath) {
-				logger.debug(
-					'[router-detect] Router variable %s is not imported — may be defined locally',
-					varName
-				);
-				continue;
-			}
-
-			const resolvedFile = await resolveImportFile(appDir, importPath);
-			if (!resolvedFile) {
-				logger.warn(
-					'[router-detect] Could not resolve import %s for router variable %s',
-					importPath,
-					varName
-				);
-				continue;
-			}
-
-			logger.trace(
-				'[router-detect] Found router mount: %s → %s (%s)',
-				path,
-				varName,
-				resolvedFile
-			);
-			mounts.push({ path, routerFile: resolvedFile });
-		}
-
-		if (mounts.length === 0) {
-			logger.debug('[router-detect] Router variables found but none could be resolved to files');
-			return noDetection;
-		}
-
-		logger.debug(
-			'[router-detect] Detected %d explicit router mount(s) in %s',
-			mounts.length,
-			appFile
-		);
-		return { detected: true, mounts };
-	} catch (error) {
-		logger.warn(
-			'[router-detect] Failed to parse %s: %s',
-			appFile,
-			error instanceof Error ? error.message : String(error)
-		);
-		return noDetection;
-	}
-}