@agentuity/cli 0.0.110 → 0.0.111

package/src/cli.ts

@@ -15,7 +15,7 @@ import type {
 } from './types';
 import { showBanner, generateBanner } from './banner';
 import { requireAuth, optionalAuth, requireOrg, optionalOrg as selectOptionalOrg } from './auth';
-import { listRegions, type RegionList } from '@agentuity/server';
+import { listRegions, type RegionList, ValidationOutputError } from '@agentuity/server';
 import enquirer from 'enquirer';
 import * as tui from './tui';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInput } from './schema-parser';
@@ -26,6 +26,22 @@ import { getCommand } from './command-prefix';
 import { isValidateMode, outputValidation, type ValidationResult } from './output';
 import { StructuredError } from '@agentuity/core';
 
+/**
+ * Check if an error is a CLI input validation error (Zod error from schema parsing),
+ * and not an API response validation error (ValidationOutputError).
+ */
+function isCLIValidationError(error: unknown): boolean {
+	if (!error || typeof error !== 'object' || !('issues' in error)) {
+		return false;
+	}
+	// ValidationOutputError from API responses should NOT be treated as CLI validation errors
+	if (error instanceof ValidationOutputError) {
+		return false;
+	}
+	// Check for Zod error structure (has name 'ZodError' or is from SchemaValidationError)
+	return true;
+}
+
 const APIClientConfigError = StructuredError('APIClientConfigError');
 
 function createAPIClient(baseCtx: CommandContext, config: Config | null): APIClient {
@@ -1143,7 +1159,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
@@ -1322,7 +1338,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(
@@ -1447,7 +1463,7 @@ async function registerSubcommand(
 						subcommand.webUrl
 					);
 				} catch (error) {
-					if (error && typeof error === 'object' && 'issues' in error) {
+					if (isCLIValidationError(error)) {
 						handleValidationError(error, getFullCommandPath(cmd), baseCtx);
 					}
 					handleProjectConfigError(

package/src/cmd/build/vite/agent-discovery.ts

@@ -65,7 +65,7 @@ export interface AgentMetadata {
 
 export interface EvalMetadata {
 	id: string;
-	evalId: string;
+	identifier: string;
 	name: string;
 	filename: string;
 	version: string;
@@ -459,13 +459,13 @@ function extractEvalsFromSource(
 
 				if (evalName) {
 					const id = getEvalId(projectId, deploymentId, filename, evalName, version);
-					const evalId = generateStableEvalId(projectId, agentId, evalName);
+					const identifier = generateStableEvalId(projectId, agentId, evalName);
 
-					logger.trace(`Found eval '${evalName}' in ${filename} (evalId: ${evalId})`);
+					logger.trace(`Found eval '${evalName}' in ${filename} (identifier: ${identifier})`);
 
 					evals.push({
 						id,
-						evalId,
+						identifier,
 						name: evalName,
 						filename,
 						version,

package/src/cmd/build/vite/index.ts

@@ -87,7 +87,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 			}
 
 			if (routeInfoList.length > 0) {
-				generateRouteRegistry(srcDir, routeInfoList, agents);
+				await generateRouteRegistry(srcDir, routeInfoList, agents);
 				logger.trace('Generated route registry with %d route(s)', routeInfoList.length);
 			}
 

package/src/cmd/build/vite/metadata-generator.ts

@@ -443,7 +443,7 @@ export async function generateMetadata(options: MetadataGeneratorOptions): Promi
 			evals: agent.evals?.map((evalItem) => ({
 				filename: evalItem.filename,
 				id: evalItem.id,
-				evalId: evalItem.evalId,
+				identifier: evalItem.identifier,
 				name: evalItem.name,
 				version: evalItem.version,
 				description: evalItem.description,

package/src/cmd/build/vite/registry-generator.ts

@@ -6,6 +6,7 @@
 
 import { join } from 'node:path';
 import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { StructuredError } from '@agentuity/core';
 import { toCamelCase, toPascalCase } from '../../../utils/string';
 import type { AgentMetadata } from './agent-discovery';
@@ -29,6 +30,28 @@ function sanitizePathSegment(segment: string): string {
 	return toCamelCase(segment.replace(ROUTE_PARAM_CHARS, ''));
 }
 
+/**
+ * Generate TypeScript type for path parameters.
+ * Returns 'never' if no path params, or '{ param1: string; param2: string }' format.
+ */
+function generatePathParamsType(pathParams?: string[]): string {
+	if (!pathParams || pathParams.length === 0) {
+		return 'never';
+	}
+	return `{ ${pathParams.map((p) => `${p}: string`).join('; ')} }`;
+}
+
+/**
+ * Generate TypeScript tuple type for path parameters (for positional args).
+ * Returns '[]' if no path params, or '[string, string]' format.
+ */
+function generatePathParamsTupleType(pathParams?: string[]): string {
+	if (!pathParams || pathParams.length === 0) {
+		return '[]';
+	}
+	return `[${pathParams.map(() => 'string').join(', ')}]`;
+}
+
 /**
  * Generate src/generated/registry.ts with agent registry and types
  */
@@ -362,8 +385,10 @@ function generateRPCRegistryType(
 				jsdoc.push(`${indent} */`);
 				lines.push(...jsdoc);
 
+				const pathParamsType = generatePathParamsType(routeInfo.pathParams);
+				const pathParamsTupleType = generatePathParamsTupleType(routeInfo.pathParams);
 				lines.push(
-					`${indent}${key}: { input: ${value.input}; output: ${value.output}; type: ${value.type} };`
+					`${indent}${key}: { input: ${value.input}; output: ${value.output}; type: ${value.type}; params: ${pathParamsType}; paramsTuple: ${pathParamsTupleType} };`
 				);
 			} else {
 				// Nested node
@@ -393,7 +418,7 @@ function generateRPCRuntimeMetadata(
 	sseRoutes: RouteInfo[]
 ): string {
 	interface MetadataNode {
-		[key: string]: MetadataNode | { type: string };
+		[key: string]: MetadataNode | { type: string; path: string; pathParams?: string[] };
 	}
 
 	const tree: MetadataNode = {};
@@ -431,7 +456,14 @@ function generateRPCRuntimeMetadata(
 						? 'stream'
 						: route.method.toLowerCase();
 
-		current[terminalMethod] = { type: routeType };
+		const metadata: { type: string; path: string; pathParams?: string[] } = {
+			type: routeType,
+			path: route.path,
+		};
+		if (route.pathParams && route.pathParams.length > 0) {
+			metadata.pathParams = route.pathParams;
+		}
+		current[terminalMethod] = metadata;
 	};
 
 	apiRoutes.forEach((r) => addRoute(r, r.routeType === 'stream' ? 'stream' : 'api'));
@@ -461,15 +493,15 @@ function generateRPCRuntimeMetadata(
  * Creates a module augmentation for @agentuity/react that provides
  * strongly-typed route keys with input/output schema information.
  */
-export function generateRouteRegistry(
+export async function generateRouteRegistry(
 	srcDir: string,
 	routes: RouteInfo[],
 	agents: AgentMetadata[] = []
-): void {
-	// Check if project uses @agentuity/react
+): Promise<void> {
 	const projectRoot = join(srcDir, '..');
 	const packageJsonPath = join(projectRoot, 'package.json');
 	let hasReactDependency = false;
+	let hasFrontendDependency = false;
 
 	try {
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
@@ -477,10 +509,25 @@ export function generateRouteRegistry(
 			packageJson.dependencies?.['@agentuity/react'] ||
 			packageJson.devDependencies?.['@agentuity/react']
 		);
+		hasFrontendDependency = !!(
+			packageJson.dependencies?.['@agentuity/frontend'] ||
+			packageJson.devDependencies?.['@agentuity/frontend']
+		);
 	} catch {
-		// If we can't read package.json, assume no React dependency
+		// If we can't read package.json, assume no frontend dependencies
 	}
 
+	const webDir = join(srcDir, 'web');
+	let hasWebDirectory = false;
+	try {
+		const webDirStat = await stat(webDir);
+		hasWebDirectory = webDirStat.isDirectory();
+	} catch {
+		// Directory doesn't exist
+	}
+
+	const shouldEmitFrontendClient = hasFrontendDependency && !hasReactDependency && hasWebDirectory;
+
 	// Filter routes by type and sort by path for deterministic output
 	const sortByPath = (a: RouteInfo, b: RouteInfo) => a.path.localeCompare(b.path);
 	const apiRoutes = routes
@@ -769,13 +816,18 @@ export function generateRouteRegistry(
 		// because only 'json' validators extract input schemas
 		// Also check if agentVariable exists but import wasn't added (missing agentImportPath)
 		const hasValidAgentImport = route.agentVariable ? !!importName : false;
+
+		// Generate pathParams type
+		const pathParamsType = generatePathParamsType(route.pathParams);
+
 		if (!route.inputSchemaVariable && !route.outputSchemaVariable && !hasValidAgentImport) {
 			const streamValue = route.stream === true ? 'true' : 'false';
 			return `\t'${routeKey}': {
-\t\tinputSchema: never;
-\t\toutputSchema: never;
-\t\tstream: ${streamValue};
-\t};`;
+		\t\tinputSchema: never;
+		\t\toutputSchema: never;
+		\t\tstream: ${streamValue};
+		\t\tparams: ${pathParamsType};
+		\t};`;
 		}
 		const streamValue = importName
 			? `typeof ${importName} extends { stream?: infer S } ? S : false`
@@ -784,10 +836,11 @@ export function generateRouteRegistry(
 				: 'false';
 
 		return `\t'${routeKey}': {
-\t\tinputSchema: ${pascalName}InputSchema;
-\t\toutputSchema: ${pascalName}OutputSchema;
-\t\tstream: ${streamValue};
-\t};`;
+		\t\tinputSchema: ${pascalName}InputSchema;
+		\t\toutputSchema: ${pascalName}OutputSchema;
+		\t\tstream: ${streamValue};
+		\t\tparams: ${pathParamsType};
+		\t};`;
 	};
 
 	// Generate route entries with METHOD prefix for API routes
@@ -817,7 +870,7 @@ export function generateRouteRegistry(
 	const generatedContent = `// @generated
 // Auto-generated by Agentuity - DO NOT EDIT
 ${importsStr}${typeImports}${
-		!hasReactDependency
+		shouldEmitFrontendClient
 			? `
 import { createClient } from '@agentuity/frontend';`
 			: ''
@@ -842,7 +895,7 @@ ${routeSchemaTypes}
  * Individual route Input/Output types are exported above for direct usage.
  */
 ${
-	!hasReactDependency
+	shouldEmitFrontendClient
 		? `
 /**
  * RPC Route Registry
@@ -907,13 +960,14 @@ if (typeof globalThis !== 'undefined') {
 	(globalThis as Record<string, unknown>).__rpcRouteMetadata = _rpcRouteMetadata;
 }
 ${
-	!hasReactDependency
+	shouldEmitFrontendClient
 		? `
 /**
  * Create a type-safe API client with optional configuration.
  *
- * This function is only generated when @agentuity/react is not installed.
- * If using React, import createAPIClient from '@agentuity/react' instead.
+ * This function is only generated when @agentuity/frontend is installed
+ * but @agentuity/react is not. For React apps, import createAPIClient
+ * from '@agentuity/react' instead.
  *
  * @example
  * \`\`\`typescript
@@ -932,7 +986,8 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
 	return createClient(options || {}, _rpcRouteMetadata) as import('@agentuity/frontend').Client<RPCRouteRegistry>;
 }
 `
-		: `
+		: hasReactDependency
+			? `
 /**
  * Type-safe API client is available from @agentuity/react
  *
@@ -945,6 +1000,7 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
  * \`\`\`
  */
 `
+			: ''
 }
 
 // FOUND AN ERROR IN THIS FILE?
@@ -955,9 +1011,7 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
 	const generatedDir = join(srcDir, 'generated');
 	const registryPath = join(generatedDir, 'routes.ts');
 
-	if (!existsSync(generatedDir)) {
-		mkdirSync(generatedDir, { recursive: true });
-	}
+	mkdirSync(generatedDir, { recursive: true });
 
 	// Collapse 2+ consecutive empty lines into 1 empty line (3+ \n becomes 2 \n)
 	const cleanedContent = generatedContent.replace(/\n{3,}/g, '\n\n');

package/src/cmd/build/vite/route-discovery.ts

@@ -40,6 +40,24 @@ export interface RouteInfo {
 	inputSchemaCode?: string;
 	outputSchemaCode?: string;
 	stream?: boolean;
+	pathParams?: string[];
+}
+
+/**
+ * Extract path parameters from a route path.
+ * Matches patterns like :id, :userId, :id?, *path, etc.
+ */
+export function extractPathParams(path: string): string[] {
+	const params: string[] = [];
+	const parts = path.split('/');
+	for (const part of parts) {
+		if (part.startsWith(':')) {
+			params.push(part.replace(/^:|[?+*]$/g, ''));
+		} else if (part.startsWith('*') && part.length > 1) {
+			params.push(part.substring(1).replace(/[?+*]$/g, ''));
+		}
+	}
+	return params;
 }
 
 /**
@@ -90,6 +108,7 @@ export async function discoverRoutes(
 
 					// Convert to RouteInfo for registry
 					for (const route of parsedRoutes) {
+						const pathParams = extractPathParams(route.path);
 						routeInfoList.push({
 							method: route.method.toUpperCase(),
 							path: route.path,
@@ -106,6 +125,7 @@ export async function discoverRoutes(
 									: route.type === 'stream'
 										? true
 										: undefined,
+							pathParams: pathParams.length > 0 ? pathParams : undefined,
 						});
 					}
 				}

package/src/cmd/build/vite/vite-builder.ts

@@ -305,7 +305,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// Generate agent and route registries for type augmentation BEFORE builds
 	// (TypeScript needs these files to exist during type checking)
 	generateAgentRegistry(srcDir, agentMetadata);
-	generateRouteRegistry(srcDir, routeInfoList);
+	await generateRouteRegistry(srcDir, routeInfoList);
 	logger.debug('Agent and route registries generated');
 
 	// Check if web frontend exists

package/src/cmd/cloud/deploy.ts

@@ -8,7 +8,14 @@ import { isRunningFromExecutable } from '../upgrade';
 import { createSubcommand, DeployOptionsSchema } from '../../types';
 import { getUserAgent } from '../../api';
 import * as tui from '../../tui';
-import { saveProjectDir, getDefaultConfigDir, loadProjectSDKKey } from '../../config';
+import {
+	saveProjectDir,
+	getDefaultConfigDir,
+	loadProjectSDKKey,
+	updateProjectConfig,
+} from '../../config';
+import { getProjectGithubStatus } from '../integration/api';
+import { runGitLink } from '../git/link';
 import {
 	runSteps,
 	stepSuccess,
@@ -163,6 +170,76 @@ export const deploySubcommand = createSubcommand({
 		try {
 			await saveProjectDir(projectDir);
 
+			// Check GitHub status and prompt for setup if not linked
+			// Skip in non-TTY environments (CI, automated runs) to prevent hanging
+			const hasTTY = process.stdin.isTTY && process.stdout.isTTY;
+			if (!useExistingDeployment && !project.skipGitSetup && hasTTY) {
+				try {
+					const githubStatus = await getProjectGithubStatus(apiClient, project.projectId);
+
+					if (githubStatus.linked && githubStatus.autoDeploy) {
+						// GitHub is already set up with auto-deploy, tell user to push instead
+						tui.newline();
+						tui.info(
+							`This project is linked to ${tui.bold(githubStatus.repoFullName ?? 'GitHub')} with automatic deployments enabled.`
+						);
+						tui.newline();
+						tui.info(
+							`Push a commit to the ${tui.bold(githubStatus.branch ?? 'main')} branch to trigger a deployment.`
+						);
+						tui.newline();
+						throw new DeploymentCancelledError();
+					}
+
+					if (!githubStatus.linked) {
+						tui.newline();
+						const wantSetup = await tui.confirm(
+							'Would you like to set up automatic deployments from GitHub?'
+						);
+
+						if (wantSetup) {
+							const result = await runGitLink({
+								apiClient,
+								projectId: project.projectId,
+								orgId: project.orgId,
+								logger,
+								skipAlreadyLinkedCheck: true,
+								config,
+							});
+
+							if (result.linked && result.autoDeploy) {
+								// GitHub linked with auto-deploy, tell user to push instead
+								tui.newline();
+								tui.info('GitHub integration set up successfully!');
+								tui.newline();
+								tui.info('Push a commit to trigger your first deployment.');
+								tui.newline();
+								throw new DeploymentCancelledError();
+							} else if (result.linked) {
+								// Linked but auto-deploy disabled, continue with manual deploy
+								tui.newline();
+								tui.info('GitHub repository linked. Continuing with deployment...');
+								tui.newline();
+							}
+						} else {
+							await updateProjectConfig(projectDir, { skipGitSetup: true }, config);
+							tui.newline();
+							tui.info(
+								`Skipping GitHub setup. Run ${tui.bold(getCommand('git link'))} later to enable it.`
+							);
+							tui.newline();
+						}
+					}
+				} catch (err) {
+					// Re-throw intentional cancellations
+					if (err instanceof DeploymentCancelledError) {
+						throw err;
+					}
+					// Log other errors as non-fatal and continue
+					logger.trace('Failed to check GitHub status: %s', err);
+				}
+			}
+
 			await runSteps(
 				[
 					!project.deployment?.domains?.length

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

@@ -4,6 +4,12 @@ import * as tui from '../../../tui';
 import { createSandboxClient, parseFileArgs } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxCreate } from '@agentuity/server';
+import { StructuredError } from '@agentuity/core';
+
+const InvalidMetadataError = StructuredError(
+	'InvalidMetadataError',
+	'Metadata must be a valid JSON object'
+);
 
 const SandboxCreateResponseSchema = z.object({
 	sandboxId: z.string().describe('Unique sandbox identifier'),
@@ -55,6 +61,7 @@ export const createSubcommand = createCommand({
 				.array(z.string())
 				.optional()
 				.describe('Apt packages to install (can be specified multiple times)'),
+			metadata: z.string().optional().describe('JSON object of user-defined metadata'),
 		}),
 		response: SandboxCreateResponseSchema,
 	},
@@ -77,6 +84,20 @@ export const createSubcommand = createCommand({
 		const files = parseFileArgs(opts.file);
 		const hasFiles = files.length > 0;
 
+		let metadata: Record<string, unknown> | undefined;
+		if (opts.metadata) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(opts.metadata);
+			} catch {
+				throw new InvalidMetadataError();
+			}
+			if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+				throw new InvalidMetadataError();
+			}
+			metadata = parsed as Record<string, unknown>;
+		}
+
 		const result = await sandboxCreate(client, {
 			options: {
 				resources:
@@ -93,6 +114,7 @@ export const createSubcommand = createCommand({
 				command: hasFiles ? { exec: [], files } : undefined,
 				snapshot: opts.snapshot,
 				dependencies: opts.dependency,
+				metadata,
 			},
 			orgId,
 		});

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

@@ -14,7 +14,7 @@ const SandboxDeleteResponseSchema = z.object({
 
 export const deleteSubcommand = createCommand({
 	name: 'delete',
-	aliases: ['del', 'rm', 'remove', 'destroy'],
+	aliases: ['del', 'remove', 'destroy'],
 	description: 'Delete a sandbox',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	requires: { auth: true, region: true, org: true },
@@ -25,11 +25,7 @@ export const deleteSubcommand = createCommand({
 			description: 'Delete a sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox rm abc123'),
-			description: 'Delete using alias',
-		},
-		{
-			command: getCommand('cloud sandbox rm abc123 --confirm'),
+			command: getCommand('cloud sandbox delete abc123 --confirm'),
 			description: 'Delete without confirmation prompt',
 		},
 	],

package/src/cmd/cloud/sandbox/download.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { writeFileSync } from 'node:fs';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxDownloadArchive } from '@agentuity/server';
+
+export const downloadSubcommand = createCommand({
+	name: 'download',
+	aliases: ['dl'],
+	description: 'Download files from a sandbox as a compressed archive',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz'),
+			description: 'Download sandbox files as tar.gz archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.zip --format zip'),
+			description: 'Download sandbox files as zip archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz --path /subdir'),
+			description: 'Download only a specific directory',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('The sandbox ID'),
+			output: z.string().describe('Output file path for the archive'),
+		}),
+		options: z.object({
+			path: z.string().optional().describe('Path in sandbox to download (defaults to root)'),
+			format: z
+				.enum(['zip', 'tar.gz'])
+				.default('tar.gz')
+				.optional()
+				.describe('Archive format (zip or tar.gz)'),
+		}),
+		response: z.object({
+			success: z.boolean(),
+			output: z.string(),
+			bytes: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+
+		const client = createSandboxClient(logger, auth, region);
+		const format = opts.format || 'tar.gz';
+
+		const stream = await sandboxDownloadArchive(client, {
+			sandboxId: args.sandboxId,
+			path: opts.path || '.',
+			format,
+			orgId,
+		});
+
+		const chunks: Uint8Array[] = [];
+		const reader = stream.getReader();
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+		}
+
+		const totalBytes = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+		const buffer = new Uint8Array(totalBytes);
+		let offset = 0;
+		for (const chunk of chunks) {
+			buffer.set(chunk, offset);
+			offset += chunk.length;
+		}
+
+		writeFileSync(args.output, buffer);
+
+		if (!options.json) {
+			tui.success(`Downloaded ${formatSize(totalBytes)} to ${args.output}`);
+		}
+
+		return { success: true, output: args.output, bytes: totalBytes };
+	},
+});
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} bytes`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+export default downloadSubcommand;