@agentuity/cli 0.0.104 → 0.0.106

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

@@ -0,0 +1,254 @@
+import { z } from 'zod';
+import { Writable } from 'node:stream';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxExecute, executionGet, writeAndDrain } from '@agentuity/server';
+import type { Logger } from '@agentuity/core';
+
+const POLL_INTERVAL_MS = 500;
+const MAX_POLL_ATTEMPTS = 7200;
+
+const SandboxExecResponseSchema = z.object({
+	executionId: z.string().describe('Unique execution identifier'),
+	status: z.string().describe('Execution status'),
+	exitCode: z.number().optional().describe('Exit code (if completed)'),
+	durationMs: z.number().optional().describe('Duration in milliseconds (if completed)'),
+	output: z.string().optional().describe('Combined stdout/stderr output'),
+});
+
+export const execSubcommand = createCommand({
+	name: 'exec',
+	aliases: ['execute'],
+	description: 'Execute a command in a running sandbox',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox exec abc123 -- echo "hello"'),
+			description: 'Execute a command in a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox exec abc123 --timeout 5m -- bun run build'),
+			description: 'Execute with timeout',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+			command: z.array(z.string()).describe('Command and arguments to execute'),
+		}),
+		options: z.object({
+			timeout: z.string().optional().describe('Execution timeout (e.g., "5m", "1h")'),
+			timestamps: z
+				.boolean()
+				.default(false)
+				.optional()
+				.describe('Include timestamps in output (default: false)'),
+		}),
+		response: SandboxExecResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+		const started = Date.now();
+
+		const abortController = new AbortController();
+		const handleSignal = () => {
+			abortController.abort();
+		};
+		process.on('SIGINT', handleSignal);
+		process.on('SIGTERM', handleSignal);
+
+		const outputChunks: string[] = [];
+
+		// For JSON output, capture to buffer; otherwise stream 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 execution = await sandboxExecute(client, {
+				sandboxId: args.sandboxId,
+				options: {
+					command: args.command,
+					timeout: opts.timeout,
+					stream: opts.timestamps !== undefined ? { timestamps: opts.timestamps } : undefined,
+				},
+				orgId,
+			});
+
+			const stdoutStreamUrl = execution.stdoutStreamUrl;
+			const stderrStreamUrl = execution.stderrStreamUrl;
+			const streamAbortController = new AbortController();
+			const streamPromises: Promise<void>[] = [];
+
+			// Check if stdout and stderr are the same stream (combined output)
+			const isCombinedOutput =
+				stdoutStreamUrl && stderrStreamUrl && stdoutStreamUrl === stderrStreamUrl;
+
+			if (isCombinedOutput) {
+				// Stream combined output to stdout only to avoid duplicates
+				logger.debug('using combined output stream (stdout === stderr): %s', stdoutStreamUrl);
+				streamPromises.push(
+					streamUrlToWritable(stdoutStreamUrl, stdout, streamAbortController.signal, logger)
+				);
+			} else {
+				if (stdoutStreamUrl) {
+					logger.debug('starting stdout stream from: %s', stdoutStreamUrl);
+					streamPromises.push(
+						streamUrlToWritable(stdoutStreamUrl, stdout, streamAbortController.signal, logger)
+					);
+				}
+
+				if (stderrStreamUrl) {
+					logger.debug('starting stderr stream from: %s', stderrStreamUrl);
+					streamPromises.push(
+						streamUrlToWritable(stderrStreamUrl, stderr, streamAbortController.signal, logger)
+					);
+				}
+			}
+
+			let attempts = 0;
+			let finalExecution = execution;
+
+			while (attempts < MAX_POLL_ATTEMPTS) {
+				if (abortController.signal.aborted) {
+					throw new Error('Execution cancelled');
+				}
+
+				await sleep(POLL_INTERVAL_MS);
+				attempts++;
+
+				try {
+					const execInfo = await executionGet(client, {
+						executionId: execution.executionId,
+						orgId,
+					});
+
+					if (
+						execInfo.status === 'completed' ||
+						execInfo.status === 'failed' ||
+						execInfo.status === 'timeout' ||
+						execInfo.status === 'cancelled'
+					) {
+						finalExecution = {
+							executionId: execInfo.executionId,
+							status: execInfo.status,
+							exitCode: execInfo.exitCode,
+							durationMs: execInfo.durationMs,
+						};
+						break;
+					}
+				} catch {
+					continue;
+				}
+			}
+
+			// Wait for all streams to reach EOF (Pulse blocks until true EOF)
+			await Promise.all(streamPromises);
+
+			// Ensure stdout is fully flushed before continuing
+			if (!options.json && process.stdout.writable) {
+				await new Promise<void>((resolve) => {
+					if (process.stdout.writableNeedDrain) {
+						process.stdout.once('drain', () => resolve());
+					} else {
+						resolve();
+					}
+				});
+			}
+
+			const duration = Date.now() - started;
+			const output = outputChunks.join('');
+
+			if (!options.json) {
+				if (finalExecution.exitCode === 0) {
+					// no op
+				} else if (finalExecution.exitCode !== undefined) {
+					tui.error(`failed with exit code ${finalExecution.exitCode} in ${duration}ms`);
+				} else {
+					tui.info(
+						`Execution ${tui.bold(finalExecution.executionId)} - Status: ${finalExecution.status}`
+					);
+				}
+			}
+
+			return {
+				executionId: finalExecution.executionId,
+				status: finalExecution.status,
+				exitCode: finalExecution.exitCode,
+				durationMs: finalExecution.durationMs,
+				output: options.json ? output : undefined,
+			};
+		} finally {
+			process.off('SIGINT', handleSignal);
+			process.off('SIGTERM', handleSignal);
+		}
+	},
+});
+
+async function streamUrlToWritable(
+	url: string,
+	writable: NodeJS.WritableStream,
+	signal: AbortSignal,
+	logger: Logger
+): Promise<void> {
+	try {
+		logger.debug('fetching stream: %s', url);
+		const response = await fetch(url, { signal });
+		logger.debug('stream response status: %d', response.status);
+
+		if (!response.ok || !response.body) {
+			logger.debug('stream response not ok or no body');
+			return;
+		}
+
+		const reader = response.body.getReader();
+
+		// Read until EOF - Pulse will block until data is available
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) {
+				logger.debug('stream EOF');
+				break;
+			}
+
+			if (value) {
+				logger.debug('stream chunk: %d bytes', value.length);
+				await writeAndDrain(writable, value);
+			}
+		}
+	} catch (err) {
+		if (err instanceof Error && err.name === 'AbortError') {
+			logger.debug('stream aborted');
+			return;
+		}
+		logger.debug('stream error: %s', err);
+	}
+}
+
+function createCaptureStream(onChunk: (chunk: string) => void): NodeJS.WritableStream {
+	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();
+		},
+	});
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export default execSubcommand;

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

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { executionGet } from '@agentuity/server';
+
+const ExecutionGetResponseSchema = z.object({
+	executionId: z.string().describe('Execution ID'),
+	sandboxId: z.string().describe('Sandbox ID'),
+	status: z.string().describe('Current status'),
+	command: z.array(z.string()).optional().describe('Command that was executed'),
+	exitCode: z.number().optional().describe('Exit code'),
+	durationMs: z.number().optional().describe('Duration in milliseconds'),
+	startedAt: z.string().optional().describe('Start timestamp'),
+	completedAt: z.string().optional().describe('Completion timestamp'),
+	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'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	aliases: ['info', 'show'],
+	description: 'Get information about a specific execution',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox execution get exec_abc123'),
+			description: 'Get execution information',
+		},
+	],
+	schema: {
+		args: z.object({
+			executionId: z.string().describe('Execution ID'),
+		}),
+		response: ExecutionGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const result = await executionGet(client, { executionId: args.executionId, orgId });
+
+		if (!options.json) {
+			const statusColor =
+				result.status === 'completed'
+					? tui.colorSuccess
+					: result.status === 'running'
+						? tui.colorWarning
+						: result.status === 'failed' || result.status === 'timeout'
+							? tui.colorError
+							: tui.colorMuted;
+
+			console.log(`${tui.muted('Execution:')}       ${tui.bold(result.executionId)}`);
+			console.log(`${tui.muted('Sandbox:')}         ${result.sandboxId}`);
+			console.log(`${tui.muted('Status:')}          ${statusColor(result.status)}`);
+			if (result.exitCode !== undefined) {
+				const exitCodeColor = result.exitCode === 0 ? tui.colorSuccess : tui.colorError;
+				console.log(
+					`${tui.muted('Exit Code:')}       ${exitCodeColor(String(result.exitCode))}`
+				);
+			}
+			if (result.durationMs !== undefined) {
+				console.log(`${tui.muted('Duration:')}        ${result.durationMs}ms`);
+			}
+			if (result.startedAt) {
+				console.log(`${tui.muted('Started:')}         ${result.startedAt}`);
+			}
+			if (result.completedAt) {
+				console.log(`${tui.muted('Completed:')}       ${result.completedAt}`);
+			}
+			if (result.error) {
+				console.log(`${tui.muted('Error:')}           ${tui.colorError(result.error)}`);
+			}
+			if (result.stdoutStreamUrl) {
+				console.log(`${tui.muted('Stdout:')}          ${result.stdoutStreamUrl}`);
+			}
+			if (result.stderrStreamUrl) {
+				console.log(`${tui.muted('Stderr:')}          ${result.stderrStreamUrl}`);
+			}
+			if (result.command && result.command.length > 0) {
+				console.log(`${tui.muted('Command:')}         ${result.command.join(' ')}`);
+			}
+		}
+
+		return {
+			executionId: result.executionId,
+			sandboxId: result.sandboxId,
+			status: result.status,
+			command: result.command,
+			exitCode: result.exitCode,
+			durationMs: result.durationMs,
+			startedAt: result.startedAt,
+			completedAt: result.completedAt,
+			error: result.error,
+			stdoutStreamUrl: result.stdoutStreamUrl,
+			stderrStreamUrl: result.stderrStreamUrl,
+		};
+	},
+});
+
+export default getSubcommand;

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

@@ -0,0 +1,25 @@
+import { createCommand } from '../../../../types';
+import { getSubcommand } from './get';
+import { listSubcommand } from './list';
+import { getCommand } from '../../../../command-prefix';
+
+export const command = createCommand({
+	name: 'execution',
+	aliases: ['executions'],
+	description: 'Manage sandbox executions',
+	tags: ['read-only', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud sandbox execution list snbx_abc123'),
+			description: 'List executions for a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox execution get exec_abc123'),
+			description: 'Get details of a specific execution',
+		},
+	],
+	subcommands: [getSubcommand, listSubcommand],
+	requires: { auth: true, region: true, org: true },
+});
+
+export default command;

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

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { executionList } from '@agentuity/server';
+
+const ExecutionInfoSchema = z.object({
+	executionId: z.string().describe('Execution ID'),
+	sandboxId: z.string().describe('Sandbox ID'),
+	status: z.string().describe('Current status'),
+	exitCode: z.number().optional().describe('Exit code'),
+	durationMs: z.number().optional().describe('Duration in milliseconds'),
+	startedAt: z.string().optional().describe('Start timestamp'),
+	completedAt: z.string().optional().describe('Completion timestamp'),
+	error: z.string().optional().describe('Error message if failed'),
+});
+
+const ExecutionListResponseSchema = z.object({
+	executions: z.array(ExecutionInfoSchema).describe('List of executions'),
+});
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List executions for a sandbox',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox execution list snbx_abc123'),
+			description: 'List executions for a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox execution list snbx_abc123 --limit 10'),
+			description: 'List 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)'),
+		}),
+		response: ExecutionListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const result = await executionList(client, {
+			sandboxId: args.sandboxId,
+			orgId,
+			limit: opts.limit,
+		});
+
+		if (!options.json) {
+			if (result.executions.length === 0) {
+				tui.info('No executions found');
+			} else {
+				const tableData = result.executions.map((exec) => {
+					const statusColor =
+						exec.status === 'completed'
+							? tui.colorSuccess
+							: exec.status === 'running'
+								? tui.colorWarning
+								: exec.status === 'failed' || exec.status === 'timeout'
+									? tui.colorError
+									: tui.colorMuted;
+
+					return {
+						ID: exec.executionId,
+						Status: statusColor(exec.status),
+						'Exit Code': exec.exitCode !== undefined ? String(exec.exitCode) : '-',
+						Duration: exec.durationMs !== undefined ? `${exec.durationMs}ms` : '-',
+						Started: exec.startedAt || '-',
+					};
+				});
+				tui.table(tableData, [
+					{ name: 'ID', alignment: 'left' },
+					{ name: 'Status', alignment: 'left' },
+					{ name: 'Exit Code', alignment: 'right' },
+					{ name: 'Duration', alignment: 'right' },
+					{ name: 'Started', alignment: 'left' },
+				]);
+
+				tui.info(
+					`Total: ${result.executions.length} ${tui.plural(result.executions.length, 'execution', 'executions')}`
+				);
+			}
+		}
+
+		return {
+			executions: result.executions.map((e) => ({
+				executionId: e.executionId,
+				sandboxId: e.sandboxId,
+				status: e.status,
+				exitCode: e.exitCode,
+				durationMs: e.durationMs,
+				startedAt: e.startedAt,
+				completedAt: e.completedAt,
+				error: e.error,
+			})),
+		};
+	},
+});
+
+export default listSubcommand;

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

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxGet } from '@agentuity/server';
+
+const SandboxGetResponseSchema = 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'),
+	stdoutStreamUrl: z.string().optional().describe('URL to stdout output stream'),
+	stderrStreamUrl: z.string().optional().describe('URL to stderr output stream'),
+	dependencies: z.array(z.string()).optional().describe('Apt packages installed'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	aliases: ['info', 'show'],
+	description: 'Get information about a sandbox',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	idempotent: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox get abc123'),
+			description: 'Get sandbox information',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+		}),
+		response: SandboxGetResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, options, auth, region, logger, orgId } = ctx;
+		const client = createSandboxClient(logger, auth, region);
+
+		const result = await sandboxGet(client, { sandboxId: args.sandboxId, orgId });
+
+		if (!options.json) {
+			const statusColor =
+				result.status === 'running'
+					? tui.colorSuccess
+					: result.status === 'idle'
+						? tui.colorWarning
+						: result.status === 'failed'
+							? tui.colorError
+							: tui.colorMuted;
+
+			console.log(`${tui.muted('Sandbox:')}         ${tui.bold(result.sandboxId)}`);
+			console.log(`${tui.muted('Status:')}          ${statusColor(result.status)}`);
+			console.log(`${tui.muted('Created:')}         ${result.createdAt}`);
+			if (result.region) {
+				console.log(`${tui.muted('Region:')}          ${result.region}`);
+			}
+			if (result.snapshotId || result.snapshotTag) {
+				const snapshotDisplay = result.snapshotTag
+					? `${result.snapshotTag} ${tui.muted('(' + result.snapshotId + ')')}`
+					: result.snapshotId;
+				console.log(`${tui.muted('Snapshot:')}        ${snapshotDisplay}`);
+			}
+			console.log(`${tui.muted('Executions:')}      ${result.executions}`);
+			if (
+				result.stdoutStreamUrl &&
+				result.stderrStreamUrl &&
+				result.stdoutStreamUrl === result.stderrStreamUrl
+			) {
+				console.log(`${tui.muted('Stream:')}          ${tui.link(result.stdoutStreamUrl)}`);
+			} else {
+				if (result.stdoutStreamUrl) {
+					console.log(`${tui.muted('Stream (stdout):')} ${tui.link(result.stdoutStreamUrl)}`);
+				}
+				if (result.stderrStreamUrl) {
+					console.log(`${tui.muted('Stream (stderr):')} ${tui.link(result.stderrStreamUrl)}`);
+				}
+			}
+			if (result.dependencies && result.dependencies.length > 0) {
+				console.log(`${tui.muted('Dependencies:')}    ${result.dependencies.join(', ')}`);
+			}
+		}
+
+		return {
+			sandboxId: result.sandboxId,
+			status: result.status,
+			createdAt: result.createdAt,
+			region: result.region,
+			snapshotId: result.snapshotId,
+			snapshotTag: result.snapshotTag,
+			executions: result.executions,
+			stdoutStreamUrl: result.stdoutStreamUrl,
+			stderrStreamUrl: result.stderrStreamUrl,
+			dependencies: result.dependencies,
+		};
+	},
+});
+
+export default getSubcommand;

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

@@ -0,0 +1,46 @@
+import { createCommand } from '../../../types';
+import { runSubcommand } from './run';
+import { createSubcommand } from './create';
+import { execSubcommand } from './exec';
+import { listSubcommand } from './list';
+import { getSubcommand } from './get';
+import { deleteSubcommand } from './delete';
+import { snapshotCommand } from './snapshot';
+import { cpSubcommand } from './cp';
+import { command as executionCommand } from './execution';
+import { getCommand } from '../../../command-prefix';
+
+export const command = createCommand({
+	name: 'sandbox',
+	aliases: ['sb'],
+	description: 'Manage sandboxes for isolated code execution',
+	tags: ['slow', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud sandbox run -- echo "hello"'),
+			description: 'Run a one-shot command in a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox create'),
+			description: 'Create an interactive sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox list'),
+			description: 'List all sandboxes',
+		},
+	],
+	subcommands: [
+		runSubcommand,
+		createSubcommand,
+		execSubcommand,
+		listSubcommand,
+		getSubcommand,
+		deleteSubcommand,
+		snapshotCommand,
+		cpSubcommand,
+		executionCommand,
+	],
+	requires: { auth: true, region: true, org: true },
+});
+
+export default command;