@agentuity/cli 0.0.101 → 0.0.103

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,EACN,gBAAgB,EAChB,mBAAmB,IAAI,yBAAyB,GAChD,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,CAAC,IAAI,GAAG,EAAE,MAAM,KAAK,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAI5B,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC3C,IAAI,EAAE,GAAG;SACP,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACnE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QACpD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;KAChF,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,+DAA+D,CAAC;IAC3E,OAAO,EAAE,GAAG;SACV,MAAM,CAAC;QACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;KACvE,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,gCAAgC,CAAC;IAC5C,SAAS,EAAE,GAAG;SACZ,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAC/D,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAC/D,aAAa,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACtE,UAAU,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QAChE,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAC9D,UAAU,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;QACtE,YAAY,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACpE,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAC1D,WAAW,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QAClE,kBAAkB,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;KAC1F,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,4BAA4B,CAAC;IACxC,WAAW,EAAE,GAAG;SACd,MAAM,CAAC;QACP,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAClF,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC1F,mBAAmB,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;QACxF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAClE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC5E,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,kBAAkB,CAAC;IAC9B,OAAO,EAAE,GAAG;SACV,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACxE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;KACzE,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,gCAAgC,CAAC;CAC5C,CAAC,CAAC;AAqSH,MAAM,UAAU,gBAAgB,CAM9B,UAiCD;IACA,OAAO,UAA6C,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,aAAa,CAM3B,UAoCD;IACA,OAAO,UAA0C,CAAC;AACnD,CAAC;AA2GD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC;IACvC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IACnD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;IACxF,UAAU,EAAE,gBAAgB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CAChF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/cli",
-	"version": "0.0.101",
+	"version": "0.0.103",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -40,8 +40,8 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.101",
-		"@agentuity/server": "0.0.101",
+		"@agentuity/core": "0.0.103",
+		"@agentuity/server": "0.0.103",
 		"@datasert/cronjs-parser": "^1.4.0",
 		"@terascope/fetch-github-release": "^2.2.1",
 		"@vitejs/plugin-react": "^5.1.2",
@@ -61,7 +61,7 @@
 		"zod": "^4.1.12"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "0.0.101",
+		"@agentuity/test-utils": "0.0.103",
 		"@types/adm-zip": "^0.5.7",
 		"@types/bun": "latest",
 		"@types/tar-fs": "^2.0.4",

package/src/cli.ts

@@ -138,6 +138,35 @@ async function executeOrValidate(
 /**
  * Handle validation error - output structured result in validate mode, otherwise log and exit
  */
+/**
+ * Format a user-friendly message for a validation issue
+ */
+function formatValidationIssueMessage(field: string, message: string): string {
+	// Detect "expected X, received undefined" pattern (missing required value)
+	if (message.includes('received undefined')) {
+		if (field && field !== 'unknown') {
+			return `Missing required option: --${field}`;
+		}
+		return 'Missing required value';
+	}
+
+	// Detect "expected X, received Y" pattern (wrong type)
+	const typeMatch = message.match(/expected (\w+), received (\w+)/i);
+	if (typeMatch) {
+		const [, expected, received] = typeMatch;
+		if (field && field !== 'unknown') {
+			return `Invalid value for --${field}: expected ${expected}, got ${received}`;
+		}
+		return `Invalid value: expected ${expected}, got ${received}`;
+	}
+
+	// Default: include the field name if we have it
+	if (field && field !== 'unknown') {
+		return `--${field}: ${message}`;
+	}
+	return message;
+}
+
 function handleValidationError(
 	error: unknown,
 	commandName: string,
@@ -146,30 +175,36 @@ function handleValidationError(
 	if (error && typeof error === 'object' && 'issues' in error) {
 		const issues = (error as { issues: Array<{ path: string[]; message: string }> }).issues;
 
+		const formattedIssues = issues.map((issue) => {
+			const field = issue.path?.length ? issue.path.join('.') : 'unknown';
+			return {
+				field,
+				message: issue.message,
+				formatted: formatValidationIssueMessage(field, issue.message),
+			};
+		});
+
 		if (isValidateMode(baseCtx.options)) {
 			// In validate mode, output structured validation result
 			const result: ValidationResult = {
 				valid: false,
 				command: commandName,
-				errors: issues.map((issue) => ({
-					field: issue.path?.length ? issue.path.join('.') : 'unknown',
-					message: issue.message,
-				})),
+				errors: formattedIssues.map(({ field, message }) => ({ field, message })),
 			};
 			outputValidation(result, baseCtx.options);
 			process.exit(ExitCode.VALIDATION_ERROR);
 		} else {
-			// Use centralized error handling
+			// Build a clear, actionable error message
+			const errorMessages = formattedIssues.map((i) => i.formatted);
+			const primaryMessage =
+				errorMessages.length === 1 ? errorMessages[0] : 'Invalid options or arguments';
+
 			exitWithError(
 				{
 					code: ErrorCode.VALIDATION_FAILED,
-					message: 'Validation error',
-					details: {
-						issues: issues.map((issue) => ({
-							field: issue.path?.length ? issue.path.join('.') : 'unknown',
-							message: issue.message,
-						})),
-					},
+					message: primaryMessage,
+					details: errorMessages.length > 1 ? { errors: errorMessages } : undefined,
+					suggestions: [`Run 'agentuity ${commandName} --help' for usage information`],
 				},
 				baseCtx.logger,
 				baseCtx.options.errorFormat ?? 'text'

package/src/cmd/ai/index.ts

@@ -2,6 +2,7 @@ import { createCommand } from '../../types';
 import capabilitiesCommand from './capabilities';
 import promptCommand from './prompt';
 import schemaCommand from './schema';
+import skillsCommand from './skills';
 import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
@@ -18,6 +19,10 @@ export const command = createCommand({
 			command: getCommand('ai schema show'),
 			description: 'Output CLI schema for AI consumption',
 		},
+		{
+			command: getCommand('ai skills generate --output ./skills'),
+			description: 'Generate Agent Skills from CLI schema',
+		},
 	],
-	subcommands: [capabilitiesCommand, promptCommand, schemaCommand],
+	subcommands: [capabilitiesCommand, promptCommand, schemaCommand, skillsCommand],
 });

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

@@ -0,0 +1,306 @@
+# 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
+- `routes.ts` - Route registry for API, WebSocket, and SSE endpoints
+- `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('user:123', { name: 'Alice', age: 30 });
+	const user = await ctx.kv.get('user:123');
+	await ctx.kv.delete('user:123');
+	const keys = await ctx.kv.list('user:*');
+	return user;
+};
+```
+
+### 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('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/)