@agentuity/cli 0.0.105 → 0.0.107

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

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCommand } from '../../../command-prefix';
+import { sandboxList } from '@agentuity/server';
+import { createSandboxClient } from './util';
+import type { SandboxStatus } from '@agentuity/core';
+
+const SandboxInfoSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	status: z.string().describe('Current status'),
+	createdAt: z.string().describe('Creation timestamp'),
+	region: z.string().optional().describe('Region where sandbox is running'),
+	snapshotId: z.string().optional().describe('Snapshot ID sandbox was created from'),
+	snapshotTag: z.string().optional().describe('Snapshot tag sandbox was created from'),
+	executions: z.number().describe('Number of executions'),
+});
+
+const SandboxListResponseSchema = z.object({
+	sandboxes: z.array(SandboxInfoSchema).describe('List of sandboxes'),
+	total: z.number().describe('Total count'),
+});
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List sandboxes with optional filtering',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	optional: { project: true },
+	idempotent: true,
+	pagination: {
+		supported: true,
+		defaultLimit: 50,
+		maxLimit: 100,
+		parameters: {
+			limit: 'limit',
+			offset: 'offset',
+		},
+	},
+	examples: [
+		{
+			command: getCommand('cloud sandbox list'),
+			description: 'List all sandboxes',
+		},
+		{
+			command: getCommand('cloud sandbox list --status running'),
+			description: 'List running sandboxes',
+		},
+		{
+			command: getCommand('cloud sandbox list --project-id proj_123'),
+			description: 'List sandboxes for a specific project',
+		},
+		{
+			command: getCommand('cloud sandbox list --limit 10 --offset 20'),
+			description: 'List with pagination',
+		},
+	],
+	schema: {
+		options: z.object({
+			status: z
+				.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+				.optional()
+				.describe('Filter by status'),
+			projectId: z.string().optional().describe('Filter by project ID'),
+			limit: z.number().optional().describe('Maximum number of results (default: 50, max: 100)'),
+			offset: z.number().optional().describe('Pagination offset'),
+		}),
+		response: SandboxListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options, auth, project, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const projectId = opts.projectId || project?.projectId;
+
+		const result = await sandboxList(client, {
+			orgId,
+			projectId,
+			status: opts.status as SandboxStatus | undefined,
+			limit: opts.limit,
+			offset: opts.offset,
+		});
+
+		if (!options.json) {
+			if (result.sandboxes.length === 0) {
+				tui.info('No sandboxes found');
+			} else {
+				const tableData = result.sandboxes.map((sandbox) => {
+					const snapshotDisplay = sandbox.snapshotTag
+						? `${sandbox.snapshotTag} (${sandbox.snapshotId})`
+						: sandbox.snapshotId || '-';
+					return {
+						ID: sandbox.sandboxId,
+						Status: sandbox.status,
+						'Created At': sandbox.createdAt,
+						Snapshot: snapshotDisplay,
+						Executions: sandbox.executions,
+					};
+				});
+				tui.table(tableData, [
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Status', alignment: 'left' },
+					{ name: 'Created At', alignment: 'left' },
+					{ name: 'Snapshot', alignment: 'left' },
+					{ name: 'Executions', alignment: 'right' },
+				]);
+
+				tui.info(`Total: ${result.total} ${tui.plural(result.total, 'sandbox', 'sandboxes')}`);
+			}
+		}
+
+		return {
+			sandboxes: result.sandboxes.map((s) => ({
+				sandboxId: s.sandboxId,
+				status: s.status,
+				createdAt: s.createdAt,
+				region: s.region,
+				snapshotId: s.snapshotId,
+				snapshotTag: s.snapshotTag,
+				executions: s.executions,
+			})),
+			total: result.total,
+		};
+	},
+});
+
+export default listSubcommand;

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

@@ -0,0 +1,170 @@
+import { z } from 'zod';
+import { Writable } from 'node:stream';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient, parseFileArgs } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxRun } from '@agentuity/server';
+
+const SandboxRunResponseSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	exitCode: z.number().describe('Exit code from the process'),
+	durationMs: z.number().describe('Duration in milliseconds'),
+	output: z.string().optional().describe('Combined stdout/stderr output'),
+});
+
+export const runSubcommand = createCommand({
+	name: 'run',
+	description: 'Run a one-shot command in a sandbox (creates, executes, destroys)',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox run -- echo "hello world"'),
+			description: 'Run a simple command',
+		},
+		{
+			command: getCommand('cloud sandbox run --memory 1Gi --cpu 1000m -- bun run index.ts'),
+			description: 'Run with resource limits',
+		},
+		{
+			command: getCommand('cloud sandbox run --network -- curl https://api.example.com'),
+			description: 'Run with network access enabled',
+		},
+	],
+	schema: {
+		args: z.object({
+			command: z.array(z.string()).describe('Command and arguments to execute'),
+		}),
+		options: z.object({
+			memory: z.string().optional().describe('Memory limit (e.g., "500Mi", "1Gi")'),
+			cpu: z.string().optional().describe('CPU limit in millicores (e.g., "500m", "1000m")'),
+			disk: z.string().optional().describe('Disk limit (e.g., "500Mi", "1Gi")'),
+			network: z.boolean().default(false).optional().describe('Enable outbound network access'),
+			timeout: z.string().optional().describe('Execution timeout (e.g., "5m", "1h")'),
+			env: z.array(z.string()).optional().describe('Environment variables (KEY=VALUE)'),
+			file: z
+				.array(z.string())
+				.optional()
+				.describe('Files to create in sandbox (sandbox-path:local-path)'),
+			timestamps: z
+				.boolean()
+				.default(false)
+				.optional()
+				.describe('Include timestamps in output (default: true)'),
+			snapshot: z.string().optional().describe('Snapshot ID or tag to restore from'),
+			dependency: z
+				.array(z.string())
+				.optional()
+				.describe('Apt packages to install (can be specified multiple times)'),
+		}),
+		response: SandboxRunResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+		const started = Date.now();
+
+		const envMap: Record<string, string> = {};
+		if (opts.env) {
+			for (const e of opts.env) {
+				const [key, ...valueParts] = e.split('=');
+				if (key) {
+					envMap[key] = valueParts.join('=');
+				}
+			}
+		}
+
+		const files = parseFileArgs(opts.file);
+		const hasFiles = files.length > 0;
+
+		const abortController = new AbortController();
+		const handleSignal = () => {
+			abortController.abort();
+		};
+		process.on('SIGINT', handleSignal);
+		process.on('SIGTERM', handleSignal);
+
+		const outputChunks: string[] = [];
+
+		// Determine if we have stdin data (not a TTY means piped input)
+		const hasStdin = !process.stdin.isTTY;
+
+		// For JSON output, we need to capture output instead of streaming to process
+		const stdout = options.json
+			? createCaptureStream((chunk) => outputChunks.push(chunk))
+			: process.stdout;
+		const stderr = options.json
+			? createCaptureStream((chunk) => outputChunks.push(chunk))
+			: process.stderr;
+
+		try {
+			const result = await sandboxRun(client, {
+				options: {
+					command: {
+						exec: args.command,
+						files: hasFiles ? files : undefined,
+					},
+					resources:
+						opts.memory || opts.cpu || opts.disk
+							? {
+									memory: opts.memory,
+									cpu: opts.cpu,
+									disk: opts.disk,
+								}
+							: undefined,
+					network: opts.network ? { enabled: true } : undefined,
+					timeout: opts.timeout ? { execution: opts.timeout } : undefined,
+					env: Object.keys(envMap).length > 0 ? envMap : undefined,
+					stream: opts.timestamps !== undefined ? { timestamps: opts.timestamps } : undefined,
+					snapshot: opts.snapshot,
+					dependencies: opts.dependency,
+				},
+				orgId,
+				region,
+				apiKey: auth.apiKey,
+				signal: abortController.signal,
+				stdin: hasStdin ? process.stdin : undefined,
+				stdout,
+				stderr,
+				logger,
+			});
+
+			const duration = Date.now() - started;
+			const output = outputChunks.join('');
+
+			if (!options.json) {
+				if (result.exitCode !== 0) {
+					tui.error(`failed with exit code ${result.exitCode} in ${duration}ms`);
+				}
+			}
+
+			return {
+				sandboxId: result.sandboxId,
+				exitCode: result.exitCode,
+				durationMs: result.durationMs,
+				output: options.json ? output : undefined,
+			};
+		} finally {
+			process.off('SIGINT', handleSignal);
+			process.off('SIGTERM', handleSignal);
+		}
+	},
+});
+
+function createCaptureStream(onChunk: (chunk: string) => void): Writable {
+	return new Writable({
+		write(
+			chunk: Buffer | string,
+			_encoding: string,
+			callback: (error?: Error | null) => void
+		): void {
+			const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+			onChunk(text);
+			callback();
+		},
+	});
+}
+
+export default runSubcommand;

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

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { snapshotCreate } from '@agentuity/server';
+
+const SnapshotCreateResponseSchema = z.object({
+	snapshotId: z.string().describe('Snapshot ID'),
+	sandboxId: z.string().describe('Source sandbox ID'),
+	tag: z.string().optional().nullable().describe('Snapshot tag'),
+	sizeBytes: z.number().describe('Snapshot size in bytes'),
+	fileCount: z.number().describe('Number of files in snapshot'),
+	createdAt: z.string().describe('Snapshot creation timestamp'),
+});
+
+export const createSubcommand = createCommand({
+	name: 'create',
+	description: 'Create a snapshot from a sandbox',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot create sbx_abc123'),
+			description: 'Create a snapshot from a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot create sbx_abc123 --tag latest'),
+			description: 'Create a tagged snapshot',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID to snapshot'),
+		}),
+		options: z.object({
+			tag: z.string().optional().describe('Tag for the snapshot'),
+		}),
+		response: SnapshotCreateResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const snapshot = await snapshotCreate(client, {
+			sandboxId: args.sandboxId,
+			tag: opts.tag,
+			orgId,
+		});
+
+		if (!options.json) {
+			tui.success(`created snapshot ${tui.bold(snapshot.snapshotId)}`);
+			tui.info(`Size: ${tui.formatBytes(snapshot.sizeBytes)}, Files: ${snapshot.fileCount}`);
+			if (snapshot.tag) {
+				tui.info(`Tag: ${snapshot.tag}`);
+			}
+		}
+
+		return {
+			snapshotId: snapshot.snapshotId,
+			sandboxId: snapshot.sandboxId,
+			tag: snapshot.tag ?? undefined,
+			sizeBytes: snapshot.sizeBytes,
+			fileCount: snapshot.fileCount,
+			createdAt: snapshot.createdAt,
+		};
+	},
+});
+
+export default createSubcommand;

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

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { snapshotDelete } from '@agentuity/server';
+
+const SnapshotDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	snapshotId: z.string().describe('Deleted snapshot ID'),
+	message: z.string().optional().describe('Status message'),
+});
+
+export const deleteSubcommand = createCommand({
+	name: 'delete',
+	aliases: ['del', 'rm', 'remove'],
+	description: 'Delete a snapshot',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot delete snp_abc123'),
+			description: 'Delete a snapshot',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot rm snp_abc123 --confirm'),
+			description: 'Delete without confirmation prompt',
+		},
+	],
+	schema: {
+		args: z.object({
+			snapshotId: z.string().describe('Snapshot ID to delete'),
+		}),
+		options: z.object({
+			confirm: z.boolean().optional().default(false).describe('Skip confirmation prompt'),
+		}),
+		response: SnapshotDeleteResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options, opts, auth, region, logger, orgId } = ctx;
+
+		if (!opts.confirm) {
+			const confirmed = await tui.confirm(`Delete snapshot "${args.snapshotId}"?`, false);
+			if (!confirmed) {
+				logger.info('Cancelled');
+				return {
+					success: false,
+					snapshotId: args.snapshotId,
+					message: 'Cancelled',
+				};
+			}
+		}
+
+		const client = createSandboxClient(logger, auth, region);
+
+		await snapshotDelete(client, {
+			snapshotId: args.snapshotId,
+			orgId,
+		});
+
+		if (!options.json) {
+			tui.success(`deleted snapshot ${tui.bold(args.snapshotId)}`);
+		}
+
+		return {
+			success: true,
+			snapshotId: args.snapshotId,
+		};
+	},
+});
+
+export default deleteSubcommand;

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

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { snapshotGet, sandboxList } from '@agentuity/server';
+import type { SnapshotFileInfo } from '@agentuity/server';
+import type { SandboxInfo } from '@agentuity/core';
+
+const SnapshotFileSchema = z.object({
+	path: z.string(),
+	size: z.number(),
+});
+
+const SandboxInfoSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	status: z.string().describe('Current status'),
+	createdAt: z.string().describe('Creation timestamp'),
+	executions: z.number().describe('Number of executions'),
+});
+
+const SnapshotGetResponseSchema = z.object({
+	snapshotId: z.string().describe('Snapshot ID'),
+	sandboxId: z.string().describe('Source sandbox ID'),
+	tag: z.string().nullable().optional().describe('Snapshot tag'),
+	sizeBytes: z.number().describe('Snapshot size in bytes'),
+	fileCount: z.number().describe('Number of files'),
+	parentSnapshotId: z.string().nullable().optional().describe('Parent snapshot ID'),
+	createdAt: z.string().describe('Creation timestamp'),
+	downloadUrl: z.string().optional().describe('Presigned download URL'),
+	files: z.array(SnapshotFileSchema).optional().describe('Files in snapshot'),
+	sandboxes: z
+		.array(SandboxInfoSchema)
+		.optional()
+		.describe('Attached sandboxes (idle or running)'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	aliases: ['info', 'show'],
+	description: 'Get snapshot details',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot get snp_abc123'),
+			description: 'Get details for a snapshot',
+		},
+	],
+	schema: {
+		args: z.object({
+			snapshotId: z.string().describe('Snapshot ID'),
+		}),
+		response: SnapshotGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const snapshot = await snapshotGet(client, {
+			snapshotId: args.snapshotId,
+			orgId,
+		});
+
+		const sandboxesResult = await sandboxList(client, {
+			orgId,
+			snapshotId: args.snapshotId,
+		});
+
+		const activeSandboxes = sandboxesResult.sandboxes.filter(
+			(s) => s.status === 'idle' || s.status === 'running'
+		);
+
+		if (!options.json) {
+			tui.info(`Snapshot: ${tui.bold(snapshot.snapshotId)}`);
+			console.log(`  ${tui.muted('Sandbox:')} ${snapshot.sandboxId}`);
+			if (snapshot.tag) {
+				console.log(`  ${tui.muted('Tag:')}     ${snapshot.tag}`);
+			}
+			console.log(`  ${tui.muted('Size:')}    ${tui.formatBytes(snapshot.sizeBytes)}`);
+			console.log(`  ${tui.muted('Files:')}   ${snapshot.fileCount}`);
+			console.log(`  ${tui.muted('Created:')} ${snapshot.createdAt}`);
+			if (snapshot.parentSnapshotId) {
+				console.log(`  ${tui.muted('Parent:')}  ${snapshot.parentSnapshotId}`);
+			}
+
+			if (snapshot.files && snapshot.files.length > 0) {
+				console.log('');
+				tui.info('Files:');
+				printFileTree(snapshot.files);
+			}
+
+			if (activeSandboxes.length > 0) {
+				console.log('');
+				tui.info(`Attached Sandboxes (${activeSandboxes.length}):`);
+				printSandboxTree(activeSandboxes);
+			}
+		}
+
+		return {
+			...snapshot,
+			sandboxes: activeSandboxes.map((s) => ({
+				sandboxId: s.sandboxId,
+				status: s.status,
+				createdAt: s.createdAt,
+				executions: s.executions,
+			})),
+		};
+	},
+});
+
+interface TreeNode {
+	name: string;
+	size?: number;
+	isFile: boolean;
+	children: Map<string, TreeNode>;
+}
+
+function buildFileTree(files: SnapshotFileInfo[]): TreeNode {
+	const root: TreeNode = { name: '', isFile: false, children: new Map() };
+
+	for (const file of files) {
+		const parts = file.path.split('/');
+		let current = root;
+
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (!current.children.has(part)) {
+				current.children.set(part, {
+					name: part,
+					isFile: i === parts.length - 1,
+					children: new Map(),
+				});
+			}
+			current = current.children.get(part)!;
+
+			if (i === parts.length - 1) {
+				current.size = file.size;
+				current.isFile = true;
+			}
+		}
+	}
+
+	return root;
+}
+
+function printFileTree(files: SnapshotFileInfo[]): void {
+	const tree = buildFileTree(files);
+	printTreeNode(tree, '  ');
+}
+
+function printTreeNode(node: TreeNode, prefix: string): void {
+	const entries = Array.from(node.children.entries()).sort((a, b) => {
+		const aIsDir = !a[1].isFile;
+		const bIsDir = !b[1].isFile;
+		if (aIsDir !== bIsDir) return aIsDir ? -1 : 1;
+		return a[0].localeCompare(b[0]);
+	});
+
+	for (let i = 0; i < entries.length; i++) {
+		const [, child] = entries[i];
+		const isLast = i === entries.length - 1;
+		const connector = tui.muted(isLast ? '└── ' : '├── ');
+		const sizeStr =
+			child.isFile && child.size !== undefined ? ` (${tui.formatBytes(child.size)})` : '';
+
+		console.log(`${prefix}${connector}${child.name}${sizeStr}`);
+
+		if (child.children.size > 0) {
+			const newPrefix = prefix + (isLast ? '    ' : tui.muted('│   '));
+			printTreeNode(child, newPrefix);
+		}
+	}
+}
+
+function printSandboxTree(sandboxes: SandboxInfo[]): void {
+	const sorted = [...sandboxes].sort((a, b) => a.sandboxId.localeCompare(b.sandboxId));
+	for (let i = 0; i < sorted.length; i++) {
+		const sandbox = sorted[i];
+		const isLast = i === sorted.length - 1;
+		const connector = tui.muted(isLast ? '└── ' : '├── ');
+		const statusColor = sandbox.status === 'running' ? tui.success : tui.muted;
+		console.log(`  ${connector}${sandbox.sandboxId} ${statusColor(`(${sandbox.status})`)}`);
+	}
+}
+
+export default getSubcommand;

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

@@ -0,0 +1,28 @@
+import { createCommand } from '../../../../types';
+import { createSubcommand } from './create';
+import { listSubcommand } from './list';
+import { getSubcommand } from './get';
+import { deleteSubcommand } from './delete';
+import { tagSubcommand } from './tag';
+import { getCommand } from '../../../../command-prefix';
+
+export const snapshotCommand = createCommand({
+	name: 'snapshot',
+	aliases: ['snap'],
+	description: 'Manage sandbox snapshots',
+	tags: ['slow', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot create <sandbox-id>'),
+			description: 'Create a snapshot from a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot list'),
+			description: 'List all snapshots',
+		},
+	],
+	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand, tagSubcommand],
+	requires: { auth: true, region: true, org: true },
+});
+
+export default snapshotCommand;