@agentuity/cli 0.0.101 → 0.0.103

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

@@ -1,6 +1,8 @@
 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',
@@ -14,328 +16,16 @@ export const agentSubcommand = createSubcommand({
 	},
 });
 
-export function generateLLMPrompt(): string {
-	return `# Agents Folder Guide
-
-This folder contains AI agents for your Agentuity application. Each agent is organized in its own subdirectory.
-
-## Directory Structure
-
-Each agent folder must contain:
-- **agent.ts** (required) - Agent definition with metadata, schema, and handler
-- **route.ts** (optional) - HTTP routes for the agent endpoint
-
-Example structure:
-\`\`\`
-src/agent/
-├── hello/
-│   ├── agent.ts
-│   └── route.ts
-├── process-data/
-│   ├── agent.ts
-│   └── route.ts
-└── registry.generated.ts (auto-generated)
-\`\`\`
-
-## Creating an Agent
-
-### Basic Agent (agent.ts)
-
-\`\`\`typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent({
-	metadata: {
-		name: 'My Agent',
-		description: 'What this agent does',
-	},
-	schema: {
-		input: s.object({ 
-			name: s.string(),
-			age: s.number() 
-		}),
-		output: s.string(),
-	},
-	handler: async (c, input) => {
-		// Access context: c.app, c.config, c.logger, c.kv, c.vector, c.stream
-		return \`Hello, \${input.name}! You are \${input.age} years old.\`;
-	},
-});
-
-export default agent;
-\`\`\`
-
-### Agent with Lifecycle (setup/shutdown)
-
-\`\`\`typescript
-import { createAgent, type AppState } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent({
-	metadata: {
-		name: 'Lifecycle Agent',
-		description: 'Agent with setup and shutdown',
-	},
-	schema: {
-		input: s.object({ message: s.string() }),
-		output: s.object({ result: s.string() }),
-	},
-	setup: async (app: AppState) => {
-		// Initialize resources (runs once on startup)
-		console.log('Setting up agent for app:', app.appName);
-		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)
-		console.log('Agent ID:', ctx.config.agentId);
-		console.log('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
-const agent = createAgent({
-	// ... configuration
-});
-
-agent.addEventListener('started', (eventName, agent, ctx) => {
-	console.log('Agent started:', ctx.config.agentId);
-});
-
-agent.addEventListener('completed', (eventName, agent, ctx) => {
-	console.log('Agent completed');
-});
-
-export default agent;
-\`\`\`
-
-## Creating Routes (route.ts)
-
-Routes expose HTTP endpoints for your agent:
-
-\`\`\`typescript
-import { createRouter } from '@agentuity/runtime';
-import agent from './agent';
-
-const router = createRouter();
-
-// GET /agent/hello
-router.get('/', async (c) => {
-	const result = await c.agent.hello.run({ name: 'World', age: 25 });
-	return c.text(result);
-});
-
-// POST /agent/hello with validation
-router.post('/', agent.validator(), async (c) => {
-	const data = c.req.valid('json');
-	const result = await c.agent.hello.run(data);
-	return c.text(result);
-});
-
-export default router;
-\`\`\`
-
-## Agent Context (c)
-
-The handler receives a context object with:
-
-- **c.app** - Application state (appName, version, startedAt, config)
-- **c.config** - Agent-specific config (from setup return value, fully typed)
-- **c.logger** - Structured logger (info, warn, error, debug, trace)
-- **c.kv** - Key-value storage
-- **c.vector** - Vector storage
-- **c.stream** - Stream management (create, list, delete)
-- **c.agent** - Access to other agents (c.agent.otherAgent.run())
-
-## Context in Routes (c)
-
-Route handlers have additional context:
-
-- **c.req** - Hono request object
-- **c.var.logger** - Logger instance
-- **Import agents directly** - Import and call agents directly instead of using c.var.agent
-
-## Examples
-
-### Using Key-Value Storage
-
-\`\`\`typescript
-handler: async (c, input) => {
-	await c.kv.set('user:123', { name: 'Alice', age: 30 });
-	const user = await c.kv.get('user:123');
-	return user;
-}
-\`\`\`
-
-### Using Streams
-
-\`\`\`typescript
-handler: async (c, input) => {
-	const stream = await c.stream.create('output', {
-		metadata: { createdBy: 'my-agent' },
-		contentType: 'text/plain',
-	});
-	await stream.write('Hello from stream');
-	await stream.close();
-	return { streamId: stream.id, url: stream.url };
-}
-\`\`\`
-
-### Calling Another Agent
-
-\`\`\`typescript
-handler: async (c, input) => {
-	const result = await c.agent.otherAgent.run({ data: input.value });
-	return \`Other agent returned: \${result}\`;
+/**
+ * Get the raw prompt content without hash.
+ */
+export function getPromptContent(): string {
+	return agentPromptContent;
 }
-\`\`\`
-
-## 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
-    ├── route.ts       # Parent routes
-    ├── members/       # Subagent
-    │   ├── agent.ts
-    │   └── route.ts
-    └── tasks/         # Subagent
-        ├── agent.ts
-        └── route.ts
-\`\`\`
-
-### Parent Agent
-
-\`\`\`typescript
-import { createAgent } from '@agentuity/runtime';
-import { s } from '@agentuity/schema';
-
-const agent = createAgent({
-	metadata: {
-		name: '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';
-
-const agent = createAgent({
-	metadata: {
-		name: '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 }) => {
-		// Access parent agent
-		const parentResult = await ctx.agent.team.run({ action: 'info' });
-		const parentInfo = \`Parent says: \${parentResult.message}\`;
-		
-		// Subagent logic here
-		let members = ['Alice', 'Bob'];
-		if (action === 'add' && name) {
-			members.push(name);
-		}
-		
-		return { members, parentInfo };
-	},
-});
-
-export default agent;
-\`\`\`
-
-### Accessing Subagents from Routes
-
-\`\`\`typescript
-import { createRouter } from '@agentuity/runtime';
-
-const router = createRouter();
-
-router.get('/', async (c) => {
-	// Call parent agent
-	const teamInfo = await c.agent.team.run({ action: 'info' });
-	
-	// Call subagents (nested access)
-	const members = await c.agent.team.members.run({ action: 'list' });
-	const tasks = await c.agent.team.tasks.run({ action: 'list' });
-	
-	return c.json({ teamInfo, members, tasks });
-});
-
-export default router;
-\`\`\`
-
-### Subagent Routes
-
-Routes for subagents automatically mount under the parent path:
-
-- Parent: \`/agent/team\`
-- Subagent: \`/agent/team/members\`
-- Subagent: \`/agent/team/tasks\`
-
-### Key Points About Subagents
-
-- **One level deep**: Only one level of nesting is supported (no nested subagents)
-- **Access parent**: Subagents can call their parent via \`ctx.agent.parentName.run()\`
-- **Agent names**: Subagents have dotted names like \`"team.members"\`
-- **Route hierarchy**: Routes inherit parent path structure
-- **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
-- **route.ts** must export default the router instance
-- Input/output schemas are enforced with @agentuity/schema validation
-- Setup return value type automatically flows to ctx.config (fully typed)
-- Use c.logger for logging, not console.log
-- Agent names in routes are accessed via c.agent.{folderName}
-- Subagents are one level deep only (team/members/, not team/members/subagent/)
-- Subagent routes mount under parent path (/agent/team/members)
-- Agents do not necessary need a route.ts file if they aren't exposed externally
-`;
+/**
+ * Generate the agent prompt with hash comment.
+ */
+export function generateLLMPrompt(): string {
+	return appendHashComment(agentPromptContent);
 }

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

@@ -0,0 +1,360 @@
+# APIs Folder Guide
+
+This folder contains REST API routes for your Agentuity application. Each API is organized in its own subdirectory.
+
+## Generated Types
+
+The `src/generated/` folder contains auto-generated TypeScript files:
+
+- `routes.ts` - Route registry with strongly-typed route definitions and schema types
+- `registry.ts` - Agent registry (for calling agents from routes)
+- `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 routes:
+
+```typescript
+import type { POST_Api_UsersInput, POST_Api_UsersOutput } from '../generated/routes';
+```
+
+## Directory Structure
+
+Each API folder must contain:
+
+- **route.ts** (required) - HTTP route definitions using Hono router
+
+Example structure:
+
+```
+src/api/
+├── index.ts         (optional, mounted at /api)
+├── status/
+│   └── route.ts     (mounted at /api/status)
+├── users/
+│   └── route.ts     (mounted at /api/users)
+├── agent-call/
+    └── route.ts     (mounted at /api/agent-call)
+```
+
+## Creating an API
+
+### Basic API (route.ts)
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+// GET /api/status
+router.get('/', (c) => {
+	return c.json({
+		status: 'ok',
+		timestamp: new Date().toISOString(),
+		version: '1.0.0',
+	});
+});
+
+// POST /api/status
+router.post('/', async (c) => {
+	const body = await c.req.json();
+	return c.json({ received: body });
+});
+
+export default router;
+```
+
+### API with Request Validation
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+import { validator } from 'hono/validator';
+
+const router = createRouter();
+
+const createUserSchema = s.object({
+	name: s.string(),
+	email: s.string(),
+	age: s.number(),
+});
+
+router.post(
+	'/',
+	validator('json', (value, c) => {
+		const result = createUserSchema['~standard'].validate(value);
+		if (result.issues) {
+			return c.json({ error: 'Validation failed', issues: result.issues }, 400);
+		}
+		return result.value;
+	}),
+	async (c) => {
+		const data = c.req.valid('json');
+		// data is fully typed: { name: string, email: string, age: number }
+		return c.json({
+			success: true,
+			user: data,
+		});
+	}
+);
+
+export default router;
+```
+
+### API Calling Agents
+
+APIs can call agents directly by importing them:
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import helloAgent from '@agent/hello';
+
+const router = createRouter();
+
+router.get('/', async (c) => {
+	// Call an agent directly
+	const result = await helloAgent.run({ name: 'API Caller', age: 42 });
+
+	return c.json({
+		success: true,
+		agentResult: result,
+	});
+});
+
+router.post('/with-input', async (c) => {
+	const body = await c.req.json();
+	const { name, age } = body;
+
+	// Call agent with dynamic input
+	const result = await helloAgent.run({ name, age });
+
+	return c.json({
+		success: true,
+		agentResult: result,
+	});
+});
+
+export default router;
+```
+
+### API with Agent Validation
+
+Use `agent.validator()` for automatic input validation from agent schemas:
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+import myAgent from '@agent/my-agent';
+
+const router = createRouter();
+
+// POST with automatic validation using agent's input schema
+router.post('/', myAgent.validator(), async (c) => {
+	const data = c.req.valid('json'); // Fully typed from agent schema!
+	const result = await myAgent.run(data);
+	return c.json({ success: true, result });
+});
+
+export default router;
+```
+
+### API with Logging
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+router.get('/log-test', (c) => {
+	c.var.logger.info('Info message');
+	c.var.logger.error('Error message');
+	c.var.logger.warn('Warning message');
+	c.var.logger.debug('Debug message');
+	c.var.logger.trace('Trace message');
+
+	return c.text('Check logs');
+});
+
+export default router;
+```
+
+## Route Context (c)
+
+The route handler receives a Hono context object with:
+
+- **c.req** - Request object (c.req.json(), c.req.param(), c.req.query(), etc.)
+- **c.json()** - Return JSON response
+- **c.text()** - Return text response
+- **c.html()** - Return HTML response
+- **c.redirect()** - Redirect to URL
+- **c.var.logger** - Structured logger (info, warn, error, debug, trace)
+- **c.var.kv** - Key-value storage
+- **c.var.vector** - Vector storage
+- **c.var.stream** - Stream management
+- **Import agents directly** - Import and call agents directly (recommended)
+
+## HTTP Methods
+
+```typescript
+const router = createRouter();
+
+router.get('/path', (c) => {
+	/* ... */
+});
+router.post('/path', (c) => {
+	/* ... */
+});
+router.put('/path', (c) => {
+	/* ... */
+});
+router.patch('/path', (c) => {
+	/* ... */
+});
+router.delete('/path', (c) => {
+	/* ... */
+});
+router.options('/path', (c) => {
+	/* ... */
+});
+```
+
+## Path Parameters
+
+```typescript
+// GET /api/users/:id
+router.get('/:id', (c) => {
+	const id = c.req.param('id');
+	return c.json({ userId: id });
+});
+
+// GET /api/posts/:postId/comments/:commentId
+router.get('/:postId/comments/:commentId', (c) => {
+	const postId = c.req.param('postId');
+	const commentId = c.req.param('commentId');
+	return c.json({ postId, commentId });
+});
+```
+
+## Query Parameters
+
+```typescript
+// GET /api/search?q=hello&limit=10
+router.get('/search', (c) => {
+	const query = c.req.query('q');
+	const limit = c.req.query('limit') || '20';
+	return c.json({ query, limit: parseInt(limit) });
+});
+```
+
+## Request Body
+
+```typescript
+// JSON body
+router.post('/', async (c) => {
+	const body = await c.req.json();
+	return c.json({ received: body });
+});
+
+// Form data
+router.post('/upload', async (c) => {
+	const formData = await c.req.formData();
+	const file = formData.get('file');
+	return c.json({ fileName: file?.name });
+});
+```
+
+## Error Handling
+
+```typescript
+import myAgent from '@agent/my-agent';
+
+router.get('/', async (c) => {
+	try {
+		const result = await myAgent.run({ data: 'test' });
+		return c.json({ success: true, result });
+	} catch (error) {
+		c.var.logger.error('Agent call failed:', error);
+		return c.json(
+			{
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			},
+			500
+		);
+	}
+});
+```
+
+## Response Types
+
+```typescript
+// JSON response
+return c.json({ data: 'value' });
+
+// Text response
+return c.text('Hello World');
+
+// HTML response
+return c.html('<h1>Hello</h1>');
+
+// Custom status code
+return c.json({ error: 'Not found' }, 404);
+
+// Redirect
+return c.redirect('/new-path');
+
+// Headers
+return c.json({ data: 'value' }, 200, {
+	'X-Custom-Header': 'value',
+});
+```
+
+## Streaming Routes
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+// Stream response
+router.stream('/events', (c) => {
+	return new ReadableStream({
+		start(controller) {
+			controller.enqueue('event 1\n');
+			controller.enqueue('event 2\n');
+			controller.close();
+		},
+	});
+});
+
+// Server-Sent Events
+router.sse('/notifications', (c) => {
+	return (stream) => {
+		stream.writeSSE({ data: 'Hello', event: 'message' });
+		stream.writeSSE({ data: 'World', event: 'message' });
+	};
+});
+
+// WebSocket
+router.websocket('/ws', (c) => {
+	return (ws) => {
+		ws.onOpen(() => {
+			ws.send('Connected!');
+		});
+		ws.onMessage((event) => {
+			ws.send(`Echo: ${event.data}`);
+		});
+	};
+});
+
+export default router;
+```
+
+## Rules
+
+- Each API folder name becomes the route name (e.g., `status/` → `/api/status`)
+- **route.ts** must export default the router instance
+- Use c.var.logger for logging, not console.log
+- Import agents directly to call them (e.g., `import agent from '@agent/name'`)
+- Validation should use @agentuity/schema or agent.validator() for type safety
+- Return appropriate HTTP status codes
+- APIs run at `/api/{folderName}` by default