@agentuity/cli 1.0.22 → 1.0.24

package/src/cmd/cloud/sandbox/snapshot/build.ts

@@ -1,27 +1,27 @@
-import { z } from 'zod';
-import { resolve, join, extname } from 'node:path';
-import { existsSync, statSync, createReadStream, createWriteStream } from 'node:fs';
-import { YAML } from 'bun';
-import * as tar from 'tar';
-import { createCommand } from '../../../../types';
-import * as tui from '../../../../tui';
-import { ErrorCode } from '../../../../errors';
-import { getCommand } from '../../../../command-prefix';
+import { createHash, createPublicKey, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream, existsSync, statSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+import type { SnapshotBuildGitInfo, SnapshotFileInfo } from '@agentuity/server';
 import {
-	snapshotBuildInit,
+	NPM_PACKAGE_NAME_PATTERN,
+	SnapshotBuildFileSchema,
 	snapshotBuildFinalize,
+	snapshotBuildInit,
 	snapshotUpload,
-	SnapshotBuildFileSchema,
-	NPM_PACKAGE_NAME_PATTERN,
 } from '@agentuity/server';
-import type { SnapshotFileInfo, SnapshotBuildGitInfo } from '@agentuity/server';
+import { YAML } from 'bun';
+import * as tar from 'tar';
+import { z } from 'zod';
+import { getCommand } from '../../../../command-prefix';
 import { getCatalystAPIClient } from '../../../../config';
+import { encryptFIPSKEMDEMStream } from '../../../../crypto/box';
+import { ErrorCode } from '../../../../errors';
+import * as tui from '../../../../tui';
+import { createCommand } from '../../../../types';
 import { validateAptDependencies } from '../../../../utils/apt-validator';
 import { getGitInfo, mergeGitInfo } from '../../../../utils/git';
-import { encryptFIPSKEMDEMStream } from '../../../../crypto/box';
-import { tmpdir } from 'node:os';
-import { randomUUID, createHash, createPublicKey } from 'node:crypto';
-import { rm } from 'node:fs/promises';
 
 export const SNAPSHOT_TAG_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 export const MAX_SNAPSHOT_TAG_LENGTH = 128;
@@ -175,9 +175,9 @@ function substituteVariables(
 }
 
 // Default patterns that are always excluded from snapshot builds
-const DEFAULT_EXCLUSIONS = ['.git', '.git/**', 'node_modules/**', '.agentuity/**', '.env*'];
+export const DEFAULT_EXCLUSIONS = ['.git', '.git/**', 'node_modules/**', '.agentuity/**', '.env*'];
 
-async function resolveFileGlobs(
+export async function resolveFileGlobs(
 	directory: string,
 	patterns: string[]
 ): Promise<Map<string, FileEntry>> {
@@ -206,9 +206,9 @@ async function resolveFileGlobs(
 						size: stat.size,
 					});
 				}
-			} catch {
+			} catch (err) {
 				// Skip files that can't be stat'd (broken symlinks, permission issues, etc.)
-				continue;
+				console.debug(`Skipping ${file}: ${err instanceof Error ? err.message : err}`);
 			}
 		}
 	}
@@ -358,9 +358,7 @@ export const buildSubcommand = createCommand({
 			description: 'Build using a custom build file',
 		},
 		{
-			command: getCommand(
-				'cloud sandbox snapshot build . --env API_KEY=secret --tag production'
-			),
+			command: getCommand('cloud sandbox snapshot build . --env API_KEY=secret --tag production'),
 			description: 'Build with environment variable substitution and custom tag',
 		},
 		{
@@ -381,10 +379,7 @@ export const buildSubcommand = createCommand({
 				.string()
 				.optional()
 				.describe('Path to build file (defaults to agentuity-snapshot.[json|yaml|yml])'),
-			env: z
-				.array(z.string())
-				.optional()
-				.describe('Environment variable substitution (KEY=VALUE)'),
+			env: z.array(z.string()).optional().describe('Environment variable substitution (KEY=VALUE)'),
 			name: z.string().optional().describe('Snapshot name (overrides build file)'),
 			tag: z.string().optional().describe('Snapshot tag (defaults to "latest")'),
 			description: z.string().optional().describe('Snapshot description (overrides build file)'),
@@ -416,7 +411,7 @@ export const buildSubcommand = createCommand({
 
 		const dryRun = options.dryRun === true;
 
-		const directory = resolve(args.directory);
+		let directory = resolve(args.directory);
 		if (!existsSync(directory)) {
 			logger.fatal(`Directory not found: ${directory}`);
 		}
@@ -475,6 +470,29 @@ export const buildSubcommand = createCommand({
 
 		const buildConfig = validationResult.data;
 
+		// If dir is specified in the build file, use it as the effective build context
+		if (buildConfig.dir) {
+			if (isAbsolute(buildConfig.dir)) {
+				logger.fatal(`'dir' must be a relative path, got: ${buildConfig.dir}`);
+			}
+			const dirPath = resolve(directory, buildConfig.dir);
+			if (!dirPath.startsWith(`${directory}/`) && dirPath !== directory) {
+				logger.fatal(`'dir' resolves outside the build root: ${dirPath}`);
+			}
+			let isDir = false;
+			try {
+				isDir = statSync(dirPath).isDirectory();
+			} catch {
+				// path does not exist
+			}
+			if (!isDir) {
+				logger.fatal(
+					`Build context directory not found or is not a directory: ${dirPath} (specified by 'dir: ${buildConfig.dir}' in build file)`
+				);
+			}
+			directory = dirPath;
+		}
+
 		// Determine if snapshot is public: CLI flag takes precedence, otherwise use build file
 		const isPublic =
 			opts.public === true || (opts.public === undefined && buildConfig.public === true);
@@ -483,21 +501,21 @@ export const buildSubcommand = createCommand({
 			if (!opts.confirm) {
 				if (!tui.isTTYLike()) {
 					logger.fatal(
-						`Publishing a public snapshot requires confirmation.\n\n` +
-							`Public snapshots make all environment variables and files publicly accessible.\n\n` +
-							`To proceed, add the --confirm flag:\n` +
+						'Publishing a public snapshot requires confirmation.\n\n' +
+							'Public snapshots make all environment variables and files publicly accessible.\n\n' +
+							'To proceed, add the --confirm flag:\n' +
 							`  ${getCommand('cloud sandbox snapshot build . --public --confirm')}\n\n` +
-							`To preview what will be published, use --dry-run first:\n` +
+							'To preview what will be published, use --dry-run first:\n' +
 							`  ${getCommand('cloud sandbox snapshot build . --public --dry-run')}`
 					);
 				}
 
 				tui.warningBox(
 					'Public Snapshot',
-					`You are publishing a public snapshot.\n\n` +
-						`This will make all environment variables and\n` +
-						`files in the snapshot publicly accessible.\n\n` +
-						`Run with --dry-run to preview the contents.`
+					'You are publishing a public snapshot.\n\n' +
+						'This will make all environment variables and\n' +
+						'files in the snapshot publicly accessible.\n\n' +
+						'Run with --dry-run to preview the contents.'
 				);
 				console.log('');
 
@@ -511,9 +529,7 @@ export const buildSubcommand = createCommand({
 
 		if (opts.tag) {
 			if (opts.tag.length > MAX_SNAPSHOT_TAG_LENGTH) {
-				logger.fatal(
-					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
-				);
+				logger.fatal(`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`);
 			}
 			if (!SNAPSHOT_TAG_REGEX.test(opts.tag)) {
 				logger.fatal(
@@ -560,12 +576,7 @@ export const buildSubcommand = createCommand({
 				message: 'Validating apt dependencies...',
 				type: 'simple',
 				callback: async () => {
-					return await validateAptDependencies(
-						buildConfig.dependencies!,
-						region,
-						config,
-						logger
-					);
+					return await validateAptDependencies(buildConfig.dependencies!, region, config, logger);
 				},
 			});
 
@@ -665,7 +676,7 @@ export const buildSubcommand = createCommand({
 
 				if (buildConfig.dependencies && buildConfig.dependencies.length > 0) {
 					console.log('');
-					tui.info('Dependencies:');
+					tui.header('Dependencies');
 					for (const dep of buildConfig.dependencies) {
 						console.log(`  ${tui.muted('•')} ${dep}`);
 					}
@@ -673,7 +684,7 @@ export const buildSubcommand = createCommand({
 
 				if (buildConfig.packages && buildConfig.packages.length > 0) {
 					console.log('');
-					tui.info('Packages (npm/bun):');
+					tui.header('Packages (npm/bun)');
 					for (const pkg of buildConfig.packages) {
 						console.log(`  ${tui.muted('•')} ${pkg}`);
 					}
@@ -681,7 +692,7 @@ export const buildSubcommand = createCommand({
 
 				if (finalEnv && Object.keys(finalEnv).length > 0) {
 					console.log('');
-					tui.info('Environment:');
+					tui.header('Environment');
 					for (const [envKey, envValue] of Object.entries(finalEnv)) {
 						console.log(`  ${tui.muted('•')} ${envKey}=${tui.maskSecret(envValue)}`);
 					}
@@ -689,7 +700,7 @@ export const buildSubcommand = createCommand({
 
 				if (fileList.length > 0) {
 					console.log('');
-					tui.info('Files:');
+					tui.header('Files');
 					printFileTree(fileList);
 				}
 			}
@@ -879,11 +890,7 @@ export const buildSubcommand = createCommand({
 						clearOnError: true,
 						callback: async (updateProgress) => {
 							const uploadFile = Bun.file(uploadPath);
-							const progressStream = createProgressStream(
-								uploadFile,
-								uploadSize,
-								updateProgress
-							);
+							const progressStream = createProgressStream(uploadFile, uploadSize, updateProgress);
 							await snapshotUpload(client, {
 								snapshotId: initResult.snapshotId!,
 								body: progressStream,
@@ -926,10 +933,7 @@ export const buildSubcommand = createCommand({
 							'Malware Detected',
 							`Your snapshot was rejected because it contains malware.\n\nVirus: ${virusName}\n\nPlease remove the infected files and try again.`
 						);
-						tui.fatal(
-							'Snapshot build failed due to malware detection',
-							ErrorCode.MALWARE_DETECTED
-						);
+						tui.fatal('Snapshot build failed due to malware detection', ErrorCode.MALWARE_DETECTED);
 					}
 
 					throw err;
@@ -976,7 +980,7 @@ export const buildSubcommand = createCommand({
 
 				if (buildConfig.dependencies && buildConfig.dependencies.length > 0) {
 					console.log('');
-					tui.info('Dependencies:');
+					tui.header('Dependencies');
 					for (const dep of buildConfig.dependencies) {
 						console.log(`  ${tui.muted('•')} ${dep}`);
 					}
@@ -984,7 +988,7 @@ export const buildSubcommand = createCommand({
 
 				if (buildConfig.packages && buildConfig.packages.length > 0) {
 					console.log('');
-					tui.info('Packages (npm/bun):');
+					tui.header('Packages (npm/bun)');
 					for (const pkg of buildConfig.packages) {
 						console.log(`  ${tui.muted('•')} ${pkg}`);
 					}
@@ -992,7 +996,7 @@ export const buildSubcommand = createCommand({
 
 				if (finalEnv && Object.keys(finalEnv).length > 0) {
 					console.log('');
-					tui.info('Environment:');
+					tui.header('Environment');
 					for (const [envKey, envValue] of Object.entries(finalEnv)) {
 						console.log(`  ${tui.muted('•')} ${envKey}=${tui.maskSecret(envValue)}`);
 					}
@@ -1000,7 +1004,7 @@ export const buildSubcommand = createCommand({
 
 				if (finalMetadata && Object.keys(finalMetadata).length > 0) {
 					console.log('');
-					tui.info('Metadata:');
+					tui.header('Metadata');
 					for (const key of Object.keys(finalMetadata)) {
 						console.log(`  ${tui.muted('•')} ${key}=${finalMetadata[key]}`);
 					}
@@ -1008,7 +1012,7 @@ export const buildSubcommand = createCommand({
 
 				if (snapshot.files && snapshot.files.length > 0) {
 					console.log('');
-					tui.info('Files:');
+					tui.header('Files');
 					printFileTree(snapshot.files);
 				}
 			}

package/src/cmd/cloud/sandbox/snapshot/generate.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { createCommand } from '../../../../types';
 import { getCommand } from '../../../../command-prefix';
+import { createCommand } from '../../../../types';
 
 const TEMPLATE_YAML = `# yaml-language-server: $schema=https://agentuity.dev/schema/cli/v1/agentuity-snapshot.json
 #
@@ -27,6 +27,10 @@ runtime: bun:1
 # Can be overridden with --description flag
 description: My sandbox snapshot
 
+# Optional: Subdirectory to use as the build context
+# Files are resolved relative to this directory instead of the CLI directory argument
+# dir: src
+
 # Optional: Apt packages to install
 # Packages are validated against Debian stable repositories
 # Supports version pinning: package=version or package=version* (prefix match)

package/src/cmd/cloud/sandbox/snapshot/get.ts

@@ -138,7 +138,7 @@ export const getSubcommand = createCommand({
 				Object.keys(snapshot.userMetadata).length > 0
 			) {
 				console.log('');
-				tui.info('Metadata:');
+				tui.header('Metadata');
 				for (const [key, value] of Object.entries(snapshot.userMetadata)) {
 					console.log(`  ${tui.muted('•')} ${key}=${value}`);
 				}
@@ -146,13 +146,13 @@ export const getSubcommand = createCommand({
 
 			if (snapshot.files && snapshot.files.length > 0) {
 				console.log('');
-				tui.info('Files:');
+				tui.header('Files');
 				printFileTree(snapshot.files);
 			}
 
 			if (activeSandboxes.length > 0) {
 				console.log('');
-				tui.info(`Attached Sandboxes (${activeSandboxes.length}):`);
+				tui.header(`Attached Sandboxes (${activeSandboxes.length}):`);
 				printSandboxTree(activeSandboxes);
 			}
 		}

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getGlobalCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { getServiceStats, type ServiceStatsData } from '@agentuity/server';
+
+function formatNumber(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+function formatLatency(ms: number): string {
+	if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+	return `${Math.round(ms)}ms`;
+}
+
+function displayStats(data: ServiceStatsData): void {
+	const svc = data.services.sandbox;
+	if (!svc) {
+		tui.info('No sandbox data found.');
+		return;
+	}
+	tui.header('Sandbox Statistics');
+	tui.newline();
+	console.log(
+		`  ${tui.muted('Active:')}          ${formatNumber(svc.totalActive)} (${svc.running} running, ${svc.idle} idle, ${svc.creating} creating)`
+	);
+	console.log(
+		`  ${tui.muted('Executions:')}      ${formatNumber(svc.totalExecutions)}`
+	);
+	console.log(`  ${tui.muted('CPU Time:')}        ${formatLatency(svc.totalCpuTimeMs)}`);
+	console.log(
+		`  ${tui.muted('Memory:')}          ${tui.formatBytes(svc.totalMemoryByteSec)}`
+	);
+	console.log(
+		`  ${tui.muted('Network Out:')}     ${tui.formatBytes(svc.totalNetworkEgressBytes)}`
+	);
+}
+
+export const statsSubcommand = createCommand({
+	name: 'stats',
+	description: 'View sandbox statistics',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox stats'),
+			description: 'View sandbox statistics',
+		},
+	],
+	schema: {
+		options: z.object({
+			start: z.string().optional().describe('Start time (ISO 8601)'),
+			end: z.string().optional().describe('End time (ISO 8601)'),
+		}),
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const client = await getGlobalCatalystAPIClient(ctx.logger, ctx.auth, ctx.config?.name);
+		const orgId = ctx.orgId ?? ctx.options.orgId ?? ctx.config?.preferences?.orgId;
+
+		if (!orgId) {
+			ctx.logger.fatal('Organization ID is required. Use --org-id or set a preferred org.');
+			return;
+		}
+
+		const data = await getServiceStats(client, orgId, {
+			service: 'sandbox',
+			start: opts.start,
+			end: opts.end,
+			orgIdHeader: orgId,
+		});
+
+		if (!options.json) {
+			displayStats(data);
+		}
+
+		return data;
+	},
+});
+
+export default statsSubcommand;

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

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createScheduleAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const CreateScheduleResponseSchema = z.object({
+	schedule: z.object({
+		id: z.string(),
+		name: z.string(),
+		expression: z.string(),
+		description: z.string().nullable(),
+		due_date: z.string(),
+		created_at: z.string(),
+		updated_at: z.string(),
+		created_by: z.string(),
+	}),
+	destinations: z.array(
+		z.object({
+			id: z.string(),
+			schedule_id: z.string(),
+			created_at: z.string(),
+			updated_at: z.string(),
+			created_by: z.string(),
+			type: z.enum(['url', 'sandbox']),
+			config: z.record(z.string(), z.unknown()),
+		})
+	),
+});
+
+export const createSubcommand = createCommand({
+	name: 'create',
+	description: 'Create a schedule',
+	tags: ['mutating', 'creates-resource', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand("cloud schedule create --name nightly --expression '0 0 * * *'"),
+			description: 'Create a nightly schedule',
+		},
+	],
+	schema: {
+		options: z.object({
+			name: z.string().min(1).describe('Schedule name'),
+			expression: z.string().min(1).describe('Cron expression'),
+			description: z.string().optional().describe('Schedule description'),
+		}),
+		response: CreateScheduleResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const schedule = await createScheduleAdapter(ctx);
+		const result = await schedule.create({
+			name: opts.name,
+			expression: opts.expression,
+			description: opts.description,
+		});
+
+		if (!options.json) {
+			tui.success(`Created schedule: ${result.schedule.name}`);
+			tui.table(
+				[
+					{
+						Name: result.schedule.name,
+						ID: result.schedule.id,
+						Expression: result.schedule.expression,
+						Description: result.schedule.description || '-',
+						'Next Due': result.schedule.due_date,
+						Created: new Date(result.schedule.created_at).toLocaleString(),
+					},
+				],
+				undefined,
+				{ layout: 'vertical' }
+			);
+		}
+
+		return result;
+	},
+});
+
+export default createSubcommand;

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createScheduleAdapter } from './util';
+import { getCommand } from '../../../command-prefix';
+
+const ScheduleDeleteResponseSchema = z.object({
+	success: z.boolean(),
+	schedule_id: z.string(),
+});
+
+export const deleteSubcommand = createCommand({
+	name: 'delete',
+	aliases: ['rm'],
+	description: 'Delete a schedule',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	requires: { auth: true },
+	idempotent: true,
+	examples: [
+		{ command: getCommand('cloud schedule delete sched_abc123'), description: 'Delete a schedule' },
+	],
+	schema: {
+		args: z.object({
+			schedule_id: z.string().min(1).describe('Schedule ID'),
+		}),
+		response: ScheduleDeleteResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const schedule = await createScheduleAdapter(ctx);
+		await schedule.delete(args.schedule_id);
+
+		if (!options.json) {
+			tui.success(`Deleted schedule: ${args.schedule_id}`);
+		}
+
+		return { success: true, schedule_id: args.schedule_id };
+	},
+});
+
+export default deleteSubcommand;

package/src/cmd/cloud/schedule/delivery/get.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createScheduleAdapter } from '../util';
+import { getCommand } from '../../../../command-prefix';
+
+const DeliveryGetResponseSchema = z.object({
+	delivery: z.object({
+		id: z.string(),
+		date: z.string(),
+		schedule_id: z.string(),
+		schedule_destination_id: z.string(),
+		status: z.enum(['pending', 'success', 'failed']),
+		retries: z.number(),
+		error: z.string().nullable(),
+		response: z.record(z.string(), z.unknown()).nullable(),
+	}),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get delivery details',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud schedule delivery get sched_abc123 sdel_abc456'),
+			description: 'Get delivery details',
+		},
+	],
+	schema: {
+		args: z.object({
+			schedule_id: z.string().min(1).describe('Schedule ID'),
+			delivery_id: z.string().min(1).describe('Delivery ID'),
+		}),
+		options: z.object({
+			limit: z.coerce
+				.number()
+				.min(0)
+				.optional()
+				.describe('Maximum number of deliveries to scan while filtering'),
+			offset: z.coerce
+				.number()
+				.min(0)
+				.optional()
+				.describe('Offset while scanning deliveries for filtering'),
+		}),
+		response: DeliveryGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const schedule = await createScheduleAdapter(ctx);
+		const delivery = await schedule.getDelivery(args.schedule_id, args.delivery_id, {
+			limit: opts.limit,
+			offset: opts.offset,
+		});
+
+		if (!options.json) {
+			const details: Record<string, unknown> = {
+				ID: delivery.id,
+				'Schedule ID': delivery.schedule_id,
+				'Destination ID': delivery.schedule_destination_id,
+				Date: new Date(delivery.date).toLocaleString(),
+				Status: delivery.status,
+				Retries: delivery.retries,
+				Error: delivery.error ?? '-',
+			};
+
+			tui.table([details], undefined, { layout: 'vertical' });
+
+			if (delivery.response) {
+				tui.newline();
+				tui.header('Response');
+				tui.json(delivery.response);
+			}
+		}
+
+		return { delivery };
+	},
+});
+
+export default getSubcommand;

package/src/cmd/cloud/schedule/delivery/index.ts

@@ -0,0 +1,24 @@
+import { createCommand } from '../../../../types';
+import { listSubcommand } from './list';
+import { getSubcommand } from './get';
+import { getCommand } from '../../../../command-prefix';
+
+export const command = createCommand({
+	name: 'delivery',
+	description: 'Manage schedule delivery attempts',
+	tags: ['requires-auth'],
+	requires: { auth: true },
+	subcommands: [listSubcommand, getSubcommand],
+	examples: [
+		{
+			command: getCommand('cloud schedule delivery list sched_abc123'),
+			description: 'List deliveries for schedule',
+		},
+		{
+			command: getCommand('cloud schedule delivery get sched_abc123 sdel_abc456'),
+			description: 'Get delivery details',
+		},
+	],
+});
+
+export default command;