@agentuity/cli 0.0.60 → 0.0.61

package/src/cmd/ai/capabilities/index.ts

@@ -1,11 +1,15 @@
 import type { CommandDefinition } from '../../../types';
 import { createCommand } from '../../../types';
 import { showSubcommand } from './show';
+import { getCommand } from '../../../command-prefix';
 
 export const capabilitiesCommand: CommandDefinition = createCommand({
 	name: 'capabilities',
 	description: 'Show CLI capabilities and available tasks',
 	tags: ['read-only', 'fast'],
+	examples: [
+		{ command: getCommand('ai capabilities show'), description: 'Show CLI capabilities' },
+	],
 	subcommands: [showSubcommand],
 });
 

package/src/cmd/ai/capabilities/show.ts

@@ -52,7 +52,13 @@ export const showSubcommand = createSubcommand({
 	name: 'show',
 	description: 'Display CLI capabilities',
 	tags: ['read-only', 'fast'],
-	examples: [getCommand('capabilities show'), getCommand('--json capabilities show')],
+	examples: [
+		{ command: getCommand('capabilities show'), description: 'Show details' },
+		{
+			command: getCommand('--json capabilities show'),
+			description: 'Show output in JSON format',
+		},
+	],
 	schema: {
 		response: CapabilitiesShowResponseSchema,
 	},
@@ -154,7 +160,12 @@ export const showSubcommand = createSubcommand({
 					id: 'storage',
 					name: 'Cloud Storage',
 					description: 'Manage storage resources',
-					commands: ['cloud storage list', 'cloud storage create', 'cloud storage get', 'cloud storage delete'],
+					commands: [
+						'cloud storage list',
+						'cloud storage create',
+						'cloud storage get',
+						'cloud storage delete',
+					],
 					requiresAuth: true,
 				},
 				{

package/src/cmd/ai/index.ts

@@ -2,10 +2,21 @@ import { createCommand } from '../../types';
 import capabilitiesCommand from './capabilities';
 import promptCommand from './prompt';
 import schemaCommand from './schema';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'ai',
 	description: 'AI coding agent related commands',
 	tags: ['fast'],
+	examples: [
+		{
+			command: getCommand('ai capabilities show'),
+			description: 'Show CLI capabilities for AI agents',
+		},
+		{
+			command: getCommand('ai schema show'),
+			description: 'Output CLI schema for AI consumption',
+		},
+	],
 	subcommands: [capabilitiesCommand, promptCommand, schemaCommand],
 });

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

@@ -0,0 +1,342 @@
+import { createSubcommand } from '../../../types';
+import type { CommandContext } from '../../../types';
+import { getCommand } from '../../../command-prefix';
+
+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);
+	},
+});
+
+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/agents/
+├── 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 { z } from 'zod';
+
+const agent = createAgent({
+	metadata: {
+		name: 'My Agent',
+		description: 'What this agent does',
+	},
+	schema: {
+		input: z.object({ 
+			name: z.string(),
+			age: z.number() 
+		}),
+		output: z.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 { z } from 'zod';
+
+const agent = createAgent({
+	metadata: {
+		name: 'Lifecycle Agent',
+		description: 'Agent with setup and shutdown',
+	},
+	schema: {
+		input: z.object({ message: z.string() }),
+		output: z.object({ result: z.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 { zValidator } from '@hono/zod-validator';
+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('/', zValidator('json', agent.inputSchema), 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
+- **c.var.agent** or **c.agent** - Access to all agents
+
+## 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}\`;
+}
+\`\`\`
+
+## Subagents (Nested Agents)
+
+Agents can have subagents organized one level deep. This is useful for grouping related functionality.
+
+### Directory Structure for Subagents
+
+\`\`\`
+src/agents/
+└── 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 { z } from 'zod';
+
+const agent = createAgent({
+	metadata: {
+		name: 'Team Manager',
+	},
+	schema: {
+		input: z.object({ action: z.enum(['info', 'count']) }),
+		output: z.object({ 
+			message: z.string(),
+			timestamp: z.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 { z } from 'zod';
+
+const agent = createAgent({
+	metadata: {
+		name: 'Members Subagent',
+	},
+	schema: {
+		input: z.object({
+			action: z.enum(['list', 'add', 'remove']),
+			name: z.string().optional(),
+		}),
+		output: z.object({
+			members: z.array(z.string()),
+			parentInfo: z.string().optional(),
+		}),
+	},
+	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 Zod 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
+`;
+}

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

@@ -0,0 +1,274 @@
+import { createSubcommand } from '../../../types';
+import type { CommandContext } from '../../../types';
+import { getCommand } from '../../../command-prefix';
+
+export const apiSubcommand = createSubcommand({
+	name: 'api',
+	description: 'Generate a comprehensive prompt for LLM agents for the apis folder',
+	tags: ['read-only', 'fast'],
+	idempotent: true,
+	examples: [{ command: getCommand('prompt api'), description: 'Run api command' }],
+	async handler(_ctx: CommandContext) {
+		const prompt = generateLLMPrompt();
+		console.log(prompt);
+	},
+});
+
+export function generateLLMPrompt(): string {
+	return `# APIs Folder Guide
+
+This folder contains REST API routes for your Agentuity application. Each API is organized in its own subdirectory.
+
+## Directory Structure
+
+Each API folder must contain:
+- **route.ts** (required) - HTTP route definitions using Hono router
+
+Example structure:
+\`\`\`
+src/apis/
+├── status/
+│   └── route.ts
+├── users/
+│   └── route.ts
+├── agent-call/
+    └── route.ts
+\`\`\`
+
+## 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 { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+
+const router = createRouter();
+
+const createUserSchema = z.object({
+	name: z.string(),
+	email: z.string().email(),
+	age: z.number().min(0),
+});
+
+router.post('/', zValidator('json', createUserSchema), 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:
+
+\`\`\`typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+
+router.get('/', async (c) => {
+	// Call an agent from the agents/ folder
+	const result = await c.agent.hello.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 c.agent.simple.run({ name, age });
+	
+	return c.json({
+		success: true,
+		agentResult: 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.agent** or **c.agent** - Access to all agents
+- **c.var.kv** - Key-value storage
+- **c.var.vector** - Vector storage
+- **c.var.stream** - Stream management
+
+## 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
+router.get('/', async (c) => {
+	try {
+		const result = await c.agent.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',
+});
+\`\`\`
+
+## 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
+- All agents are accessible via c.agent.{agentName}
+- Validation should use zValidator with Zod schemas or any Standard Schema compatible library
+- Return appropriate HTTP status codes
+- APIs run at \`/api/{folderName}\` by default
+`;
+}

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

@@ -1,12 +1,27 @@
-import type { CommandDefinition } from '../../../types';
 import { createCommand } from '../../../types';
 import { llmSubcommand } from './llm';
+import { apiSubcommand } from './api';
+import { agentSubcommand } from './agent';
+import { webSubcommand } from './web';
+import { getCommand } from '../../../command-prefix';
 
-export const promptCommand: CommandDefinition = createCommand({
+export const promptCommand = createCommand({
 	name: 'prompt',
 	description: 'Generate prompts for LLMs and agents',
 	tags: ['read-only', 'fast'],
-	subcommands: [llmSubcommand],
+	examples: [
+		{ command: getCommand('ai prompt llm'), description: 'Generate LLM-specific prompt' },
+		{
+			command: getCommand('ai prompt agent'),
+			description: 'Generate LLM-specific prompt for Agents',
+		},
+		{
+			command: getCommand('ai prompt api'),
+			description: 'Generate LLM-specific prompt for APIs',
+		},
+		{ command: getCommand('ai prompt web'), description: 'Generate LLM-specific prompt for Web' },
+	],
+	subcommands: [agentSubcommand, webSubcommand, llmSubcommand, apiSubcommand],
 });
 
 export default promptCommand;