@agentuity/cli 1.0.44 → 1.0.46

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

@@ -45,32 +45,41 @@ const SandboxCpResponseSchema = z.object({
 	directoriesCreated: z
 		.array(z.string())
 		.optional()
-		.describe('Parent directories auto-created on the destination'),
+		.describe(
+			'Parent directories that were auto-created on the destination (not present in --strict mode or when all directories already exist)'
+		),
 });
 
 export const cpSubcommand = createCommand({
 	name: 'cp',
 	aliases: ['copy'],
-	description: 'Copy files or directories to or from a sandbox',
+	description:
+		'Copy files or directories to or from a sandbox. Parent directories are automatically created if they do not exist (similar to mkdir -p).',
 	tags: ['slow', 'requires-auth'],
 	requires: { auth: true, apiClient: true },
 	examples: [
 		{
-			command: getCommand('cloud sandbox cp ./local-file.txt snbx_abc123:/path/to/file.txt'),
+			command: getCommand('cloud sandbox cp ./local-file.txt sbx_abc123:/path/to/file.txt'),
 			description: 'Copy a local file to a sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox cp snbx_abc123:/path/to/file.txt ./local-file.txt'),
+			command: getCommand('cloud sandbox cp sbx_abc123:/path/to/file.txt ./local-file.txt'),
 			description: 'Copy a file from a sandbox to local',
 		},
 		{
-			command: getCommand('cloud sandbox cp --recursive ./local-dir snbx_abc123:/path/to/dir'),
+			command: getCommand('cloud sandbox cp --recursive ./local-dir sbx_abc123:/path/to/dir'),
 			description: 'Copy a local directory to a sandbox recursively',
 		},
 		{
-			command: getCommand('cloud sandbox cp -r snbx_abc123:/path/to/dir ./local-dir'),
+			command: getCommand('cloud sandbox cp -r sbx_abc123:/path/to/dir ./local-dir'),
 			description: 'Copy a directory from a sandbox to local recursively',
 		},
+		{
+			command: getCommand(
+				'cloud sandbox cp --strict ./local-file.txt sbx_abc123:/path/to/file.txt'
+			),
+			description: 'Copy a file, failing if the target directory does not exist',
+		},
 	],
 	schema: {
 		args: z.object({
@@ -82,6 +91,13 @@ export const cpSubcommand = createCommand({
 		options: z.object({
 			timeout: z.string().optional().describe('Operation timeout (e.g., "5m", "1h")'),
 			recursive: z.boolean().default(false).optional().describe('Copy directories recursively'),
+			strict: z
+				.boolean()
+				.default(false)
+				.optional()
+				.describe(
+					'Fail if the target parent directory does not exist instead of auto-creating it'
+				),
 		}),
 		aliases: {
 			recursive: ['r'],
@@ -103,7 +119,7 @@ export const cpSubcommand = createCommand({
 
 		if (!source.sandboxId && !destination.sandboxId) {
 			logger.fatal(
-				'At least one path must include a sandbox ID (e.g., snbx_abc123:/path/to/file)'
+				'At least one path must include a sandbox ID (e.g., sbx_abc123:/path/to/file)'
 			);
 		}
 
@@ -115,6 +131,7 @@ export const cpSubcommand = createCommand({
 
 		const client = createSandboxClient(logger, auth, region);
 		const recursive = opts.recursive ?? false;
+		const strict = opts.strict ?? false;
 
 		if (source.sandboxId) {
 			return await downloadFromSandbox(
@@ -138,7 +155,8 @@ export const cpSubcommand = createCommand({
 				destination.path,
 				opts.timeout,
 				recursive,
-				options.json ?? false
+				options.json ?? false,
+				strict
 			);
 		}
 	},
@@ -193,7 +211,8 @@ async function uploadToSandbox(
 	remotePath: string,
 	timeout: string | undefined,
 	recursive: boolean,
-	jsonOutput: boolean
+	jsonOutput: boolean,
+	strict: boolean
 ): Promise<z.infer<typeof SandboxCpResponseSchema>> {
 	const resolvedPath = resolve(localPath);
 
@@ -218,7 +237,8 @@ async function uploadToSandbox(
 			resolvedPath,
 			remotePath,
 			timeout,
-			jsonOutput
+			jsonOutput,
+			strict
 		);
 	}
 
@@ -231,20 +251,22 @@ async function uploadToSandbox(
 		localPath,
 		remotePath,
 		timeout,
-		jsonOutput
+		jsonOutput,
+		strict
 	);
 }
 
 async function uploadSingleFile(
 	client: APIClient,
-	_logger: Logger,
+	logger: Logger,
 	orgId: string,
 	sandboxId: string,
 	resolvedPath: string,
 	displayPath: string,
 	remotePath: string,
 	_timeout: string | undefined,
-	jsonOutput: boolean
+	jsonOutput: boolean,
+	strict: boolean
 ): Promise<z.infer<typeof SandboxCpResponseSchema>> {
 	const buffer = readFileSync(resolvedPath);
 
@@ -254,6 +276,32 @@ async function uploadSingleFile(
 		targetPath = baseDir ? baseDir + basename(resolvedPath) : basename(resolvedPath);
 	}
 
+	if (strict) {
+		const parentDir = dirname(targetPath);
+		const knownDirs = new Set(['/', '/home', '/home/agentuity']);
+		if (!knownDirs.has(parentDir)) {
+			const checkExecution = await sandboxExecute(client, {
+				sandboxId,
+				options: {
+					command: ['test', '-d', parentDir],
+				},
+				orgId,
+			});
+			await waitForExecution(client, orgId, checkExecution.executionId, logger);
+			const execInfo = await executionGet(client, {
+				executionId: checkExecution.executionId,
+				orgId,
+			});
+			if (execInfo.exitCode !== 0) {
+				logger.fatal(
+					`Target directory does not exist: ${parentDir}\n` +
+						`Use without --strict to auto-create parent directories, or create it first with:\n` +
+						`  ${getCommand(`cloud sandbox mkdir ${sandboxId} ${parentDir} -p`)}`
+				);
+			}
+		}
+	}
+
 	const files: FileToWrite[] = [{ path: targetPath, content: buffer }];
 
 	await sandboxWriteFiles(client, { sandboxId, files, orgId });
@@ -280,7 +328,8 @@ async function uploadDirectory(
 	localDir: string,
 	remotePath: string,
 	_timeout: string | undefined,
-	jsonOutput: boolean
+	jsonOutput: boolean,
+	strict: boolean
 ): Promise<z.infer<typeof SandboxCpResponseSchema>> {
 	const allFiles = getAllFiles(localDir);
 
@@ -295,6 +344,32 @@ async function uploadDirectory(
 		? effectiveRemotePath.slice(0, -1)
 		: effectiveRemotePath;
 
+	if (strict) {
+		const parentDir = dirname(baseRemotePath);
+		const knownDirs = new Set(['/', '/home', '/home/agentuity']);
+		if (!knownDirs.has(parentDir)) {
+			const checkExecution = await sandboxExecute(client, {
+				sandboxId,
+				options: {
+					command: ['test', '-d', parentDir],
+				},
+				orgId,
+			});
+			await waitForExecution(client, orgId, checkExecution.executionId, logger);
+			const execInfo = await executionGet(client, {
+				executionId: checkExecution.executionId,
+				orgId,
+			});
+			if (execInfo.exitCode !== 0) {
+				logger.fatal(
+					`Target directory does not exist: ${parentDir}\n` +
+						`Use without --strict to auto-create parent directories, or create it first with:\n` +
+						`  ${getCommand(`cloud sandbox mkdir ${sandboxId} ${parentDir} -p`)}`
+				);
+			}
+		}
+	}
+
 	for (const filePath of allFiles) {
 		const relativePath = toForwardSlash(relative(localDir, filePath));
 		const targetPath = `${baseRemotePath}/${relativePath}`;

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

@@ -0,0 +1,108 @@
+import { sandboxEventList } from '@agentuity/server';
+import { z } from 'zod';
+import { getCommand } from '../../../command-prefix';
+import * as tui from '../../../tui';
+import { createCommand } from '../../../types';
+import { createSandboxClient, getSandboxRegion } from './util';
+
+const SandboxEventInfoSchema = z.object({
+	eventId: z.string().describe('Event ID'),
+	sandboxId: z.string().describe('Sandbox ID'),
+	type: z.string().describe('Event type'),
+	event: z.record(z.string(), z.unknown()).describe('Event data'),
+	createdAt: z.string().describe('Creation timestamp'),
+});
+
+const SandboxEventListResponseSchema = z.object({
+	events: z.array(SandboxEventInfoSchema).describe('List of events'),
+});
+
+export const eventsSubcommand = createCommand({
+	name: 'events',
+	aliases: ['event'],
+	description: 'List events for a sandbox',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox events sbx_abc123'),
+			description: 'List events for a sandbox (oldest first)',
+		},
+		{
+			command: getCommand('cloud sandbox events sbx_abc123 --reverse'),
+			description: 'List events newest first',
+		},
+		{
+			command: getCommand('cloud sandbox events sbx_abc123 --limit 10'),
+			description: 'List events with a limit',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+		}),
+		options: z.object({
+			limit: z.number().optional().describe('Maximum number of results (default: 50, max: 100)'),
+			reverse: z.boolean().optional().describe('Reverse sort order (newest first)'),
+			orgId: z.string().optional().describe('filter by organization id'),
+		}),
+		response: SandboxEventListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, logger, orgId: ctxOrgId, config } = ctx;
+		const effectiveOrgId = opts?.orgId || ctxOrgId;
+		const region = await getSandboxRegion(
+			logger,
+			auth,
+			config?.name,
+			args.sandboxId,
+			effectiveOrgId,
+			config
+		);
+		const client = createSandboxClient(logger, auth, region);
+
+		const result = await sandboxEventList(client, {
+			sandboxId: args.sandboxId,
+			orgId: effectiveOrgId,
+			limit: opts.limit,
+			direction: opts.reverse ? 'desc' : undefined,
+		});
+
+		if (!options.json) {
+			if (result.events.length === 0) {
+				tui.info('No events found');
+			} else {
+				const tableData = result.events.map((evt) => {
+					return {
+						ID: evt.eventId,
+						Type: evt.type,
+						Created: evt.createdAt,
+					};
+				});
+				tui.table(tableData, [
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Type', alignment: 'left' },
+					{ name: 'Created', alignment: 'left' },
+				]);
+
+				tui.info(
+					`Total: ${result.events.length} ${tui.plural(result.events.length, 'event', 'events')}`
+				);
+			}
+		}
+
+		return {
+			events: result.events.map((e) => ({
+				eventId: e.eventId,
+				sandboxId: e.sandboxId,
+				type: e.type,
+				event: e.event,
+				createdAt: e.createdAt,
+			})),
+		};
+	},
+});
+
+export default eventsSubcommand;

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Writable } from 'node:stream';
+import { ErrorCode } from '../../../errors';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createSandboxClient } from './util';
@@ -24,6 +25,14 @@ const SandboxExecResponseSchema = z.object({
 		.optional()
 		.describe('Standard error output (only when separate streams are available)'),
 	output: z.string().optional().describe('Combined stdout/stderr output'),
+	outputTruncated: z
+		.boolean()
+		.optional()
+		.describe('Whether the captured output was truncated due to size limits'),
+	autoResumed: z
+		.boolean()
+		.optional()
+		.describe('True if the sandbox was automatically resumed from a suspended state'),
 });
 
 export const execSubcommand = createCommand({
@@ -62,6 +71,18 @@ export const execSubcommand = createCommand({
 	async handler(ctx) {
 		const { args, opts, options, auth, logger, apiClient } = ctx;
 
+		// Validate timeout format if provided (fail fast before any network calls)
+		if (opts.timeout) {
+			// Go's time.ParseDuration accepts "0" or one-or-more number+unit tokens.
+			// Valid units: ns, us, µs (U+00B5), μs (U+03BC), ms, s, m, h
+			if (!/^(?:0|(\d+(\.\d+)?(ns|us|[µμ]s|ms|s|m|h))+)$/.test(opts.timeout)) {
+				tui.fatal(
+					`Invalid timeout format '${opts.timeout}': expected duration like '5s', '1m', '1h', '300ms'`,
+					ErrorCode.INVALID_ARGUMENT
+				);
+			}
+		}
+
 		// Resolve sandbox to get region and orgId using CLI API
 		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
 		const { region, orgId } = sandboxInfo;
@@ -87,6 +108,10 @@ export const execSubcommand = createCommand({
 				orgId,
 			});
 
+			if (execution.autoResumed && !options.json) {
+				tui.warning('Sandbox was automatically resumed from suspended state');
+			}
+
 			const stdoutStreamUrl = execution.stdoutStreamUrl;
 			const stderrStreamUrl = execution.stderrStreamUrl;
 			const streamAbortController = new AbortController();
@@ -213,6 +238,8 @@ export const execSubcommand = createCommand({
 				stdout: options.json ? stdoutOutput : undefined,
 				stderr: options.json ? stderrOutput : undefined,
 				output: options.json ? output : undefined,
+				outputTruncated: finalExecution.outputTruncated ?? undefined,
+				autoResumed: execution.autoResumed ?? undefined,
 			};
 		} finally {
 			process.off('SIGINT', handleSignal);

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

@@ -17,6 +17,10 @@ const ExecutionGetResponseSchema = z.object({
 	error: z.string().optional().describe('Error message if failed'),
 	stdoutStreamUrl: z.string().optional().describe('URL to stream stdout'),
 	stderrStreamUrl: z.string().optional().describe('URL to stream stderr'),
+	outputTruncated: z
+		.boolean()
+		.optional()
+		.describe('Whether the captured output was truncated due to size limits'),
 });
 
 export const getSubcommand = createCommand({
@@ -108,6 +112,7 @@ export const getSubcommand = createCommand({
 			error: result.error,
 			stdoutStreamUrl: result.stdoutStreamUrl,
 			stderrStreamUrl: result.stderrStreamUrl,
+			outputTruncated: result.outputTruncated,
 		};
 	},
 });

package/src/cmd/cloud/sandbox/execution/list.ts

@@ -1,9 +1,9 @@
-import { executionList } from '@agentuity/server';
+import { executionList, sandboxResolve } from '@agentuity/server';
 import { z } from 'zod';
 import { getCommand } from '../../../../command-prefix';
 import * as tui from '../../../../tui';
 import { createCommand } from '../../../../types';
-import { createSandboxClient, getSandboxRegion } from '../util';
+import { createSandboxClient } from '../util';
 
 const ExecutionInfoSchema = z.object({
 	executionId: z.string().describe('Execution ID'),
@@ -25,7 +25,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List executions for a sandbox',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	requires: { auth: true, org: true },
+	requires: { auth: true, apiClient: true },
 	idempotent: true,
 	examples: [
 		{
@@ -43,22 +43,21 @@ export const listSubcommand = createCommand({
 		}),
 		options: z.object({
 			limit: z.number().optional().describe('Maximum number of results (default: 50, max: 100)'),
-			orgId: z.string().optional().describe('filter by organization id'),
+			orgId: z
+				.string()
+				.optional()
+				.describe('Override organization ID (default: resolved from sandbox)'),
 		}),
 		response: ExecutionListResponseSchema,
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, logger, orgId: ctxOrgId, config } = ctx;
-		const effectiveOrgId = opts?.orgId || ctxOrgId;
-		const region = await getSandboxRegion(
-			logger,
-			auth,
-			config?.name,
-			args.sandboxId,
-			effectiveOrgId,
-			config
-		);
+		const { args, opts, options, auth, logger, apiClient } = ctx;
+
+		// Resolve sandbox to get region and orgId (like exec.ts does)
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId: resolvedOrgId } = sandboxInfo;
+		const effectiveOrgId = opts?.orgId || resolvedOrgId;
 		const client = createSandboxClient(logger, auth, region);
 
 		const result = await executionList(client, {

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

@@ -79,6 +79,7 @@ export const getSubcommand = createCommand({
 		const result = await sandboxGet(client, {
 			sandboxId: args.sandboxId,
 			orgId: sandboxInfo.orgId,
+			includeDeleted: true,
 		});
 
 		// Cache the region for future lookups

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

@@ -20,6 +20,7 @@ import { pauseSubcommand } from './pause';
 import { resumeSubcommand } from './resume';
 import { checkpointCommand } from './checkpoint';
 import { statsSubcommand } from './stats';
+import { eventsSubcommand } from './events';
 import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
@@ -63,6 +64,7 @@ export const command = createCommand({
 		resumeSubcommand,
 		checkpointCommand,
 		statsSubcommand,
+		eventsSubcommand,
 	],
 	requires: { auth: true, org: true },
 });

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

@@ -41,7 +41,7 @@ export async function getSandboxRegion(
 		config
 	);
 
-	const sandbox = await sandboxGet(globalClient, { sandboxId, orgId });
+	const sandbox = await sandboxGet(globalClient, { sandboxId, orgId, includeDeleted: true });
 	if (!sandbox.region) {
 		tui.fatal(`Sandbox '${sandboxId}' has no region information`, ErrorCode.RESOURCE_NOT_FOUND);
 	}