@agentuity/cli 1.0.55 → 1.0.57

package/src/cmd/cloud/deploy-fork.ts

@@ -13,7 +13,7 @@
 import { spawn, type Subprocess } from 'bun';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { appendFileSync, createWriteStream, existsSync, readFileSync, unlinkSync } from 'node:fs';
 import type { APIClient } from '../../api';
 import { getUserAgent } from '../../api';
 import { isUnicode } from '../../tui/symbols';
@@ -37,12 +37,14 @@ export interface ForkDeployResult {
 }
 
 /**
- * Stream data to a Pulse stream URL
+ * Stream data to a Pulse stream URL.
+ * Accepts a string, Blob/BunFile, or ReadableStream as the body to avoid
+ * loading large outputs into memory.
  */
 async function streamToPulse(
 	streamURL: string,
 	sdkKey: string,
-	data: string,
+	data: string | Blob | ReadableStream<Uint8Array>,
 	logger: Logger
 ): Promise<void> {
 	try {
@@ -74,7 +76,8 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 	const buildLogsStreamURL = deployment.buildLogsStreamURL;
 	const reportFile = join(tmpdir(), `agentuity-deploy-${deploymentId}.json`);
 	const cleanLogsFile = join(tmpdir(), `agentuity-deploy-${deploymentId}-logs.txt`);
-	let outputBuffer = '';
+	const rawLogsFile = join(tmpdir(), `agentuity-deploy-${deploymentId}-raw.txt`);
+	const rawLogsWriter = createWriteStream(rawLogsFile);
 	let proc: Subprocess | null = null;
 	let cancelled = false;
 
@@ -195,7 +198,6 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 
 		const handleOutput = async (stream: ReadableStream<Uint8Array>, isStderr: boolean) => {
 			const reader = stream.getReader();
-			const decoder = new TextDecoder();
 			const target = isStderr ? process.stderr : process.stdout;
 
 			try {
@@ -203,8 +205,9 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					const { done, value } = await reader.read();
 					if (done) break;
 
-					const text = decoder.decode(value, { stream: true });
-					outputBuffer += text;
+					// Stream raw bytes to disk instead of accumulating in memory.
+					// This prevents OOM / ERR_STRING_TOO_LONG crashes on large builds.
+					rawLogsWriter.write(value);
 					target.write(value);
 				}
 			} catch (err) {
@@ -223,6 +226,11 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 
 		await Promise.all([stdoutPromise, stderrPromise]);
 
+		// Close the raw logs writer so the file is fully flushed before reading
+		await new Promise<void>((resolve) => {
+			rawLogsWriter.end(resolve);
+		});
+
 		const exitCode = await proc.exited;
 		logger.debug('Child process exited with code: %d', exitCode);
 
@@ -249,12 +257,11 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					logger.debug('Failed to read clean logs file: %s', err);
 				}
 			}
-			// Fall back to raw output if no clean logs
-			if (!logsContent && outputBuffer) {
-				logsContent = outputBuffer;
-			}
 			if (logsContent) {
 				await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
+			} else if (existsSync(rawLogsFile)) {
+				// Stream raw logs file directly to Pulse without loading into memory
+				await streamToPulse(buildLogsStreamURL, sdkKey, Bun.file(rawLogsFile), logger);
 			}
 		}
 
@@ -307,11 +314,27 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 					// ignore
 				}
 			}
-			if (!logsContent) {
-				logsContent = outputBuffer;
+			if (logsContent) {
+				logsContent += `\n\n--- FORK ERROR ---\n${errorMessage}\n`;
+				await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
+			} else {
+				// Append error to raw logs file and stream it without loading into memory
+				try {
+					appendFileSync(rawLogsFile, `\n\n--- FORK ERROR ---\n${errorMessage}\n`);
+				} catch {
+					// ignore — file may not exist if child never produced output
+				}
+				if (existsSync(rawLogsFile)) {
+					await streamToPulse(buildLogsStreamURL, sdkKey, Bun.file(rawLogsFile), logger);
+				} else {
+					await streamToPulse(
+						buildLogsStreamURL,
+						sdkKey,
+						`--- FORK ERROR ---\n${errorMessage}\n`,
+						logger
+					);
+				}
 			}
-			logsContent += `\n\n--- FORK ERROR ---\n${errorMessage}\n`;
-			await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
 		}
 
 		try {
@@ -360,7 +383,7 @@ export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkD
 		process.off('SIGTERM', sigtermHandler);
 
 		// Clean up temp files
-		for (const file of [reportFile, cleanLogsFile]) {
+		for (const file of [reportFile, cleanLogsFile, rawLogsFile]) {
 			if (existsSync(file)) {
 				try {
 					unlinkSync(file);

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

@@ -98,6 +98,8 @@ export const execSubcommand = createCommand({
 		process.on('SIGTERM', handleSignal);
 
 		try {
+			logger.debug('[exec] calling sandboxExecute for %s', args.sandboxId);
+			const executeStart = Date.now();
 			const execution = await sandboxExecute(client, {
 				sandboxId: args.sandboxId,
 				options: {
@@ -107,6 +109,13 @@ export const execSubcommand = createCommand({
 				},
 				orgId,
 			});
+			logger.debug(
+				'[exec] sandboxExecute returned in %dms: executionId=%s, stdoutUrl=%s, stderrUrl=%s',
+				Date.now() - executeStart,
+				execution.executionId,
+				execution.stdoutStreamUrl ?? 'none',
+				execution.stderrStreamUrl ?? 'none'
+			);
 
 			if (execution.autoResumed && !options.json) {
 				tui.warning('Sandbox was automatically resumed from suspended state');
@@ -116,10 +125,17 @@ export const execSubcommand = createCommand({
 			const stderrStreamUrl = execution.stderrStreamUrl;
 			const streamAbortController = new AbortController();
 			const streamPromises: Promise<void>[] = [];
+			const streamLabels: string[] = [];
 
 			// Check if stdout and stderr are the same stream (combined output)
 			const isCombinedOutput =
 				stdoutStreamUrl && stderrStreamUrl && stdoutStreamUrl === stderrStreamUrl;
+			logger.debug(
+				'[exec] stream mode: combined=%s, stdoutUrl=%s, stderrUrl=%s',
+				isCombinedOutput,
+				stdoutStreamUrl ?? 'none',
+				stderrStreamUrl ?? 'none'
+			);
 
 			// Set up stream capture — in JSON mode, capture to buffers;
 			// when streams are separate, capture stdout/stderr independently
@@ -153,9 +169,11 @@ export const execSubcommand = createCommand({
 
 			if (isCombinedOutput) {
 				// Stream combined output to stdout only to avoid duplicates
-				logger.debug('using combined output stream (stdout === stderr): %s', stdoutStreamUrl);
+				logger.debug('[exec] starting combined stream: %s', stdoutStreamUrl);
+				streamLabels.push('combined');
 				streamPromises.push(
 					streamUrlToWritable(
+						'combined',
 						stdoutStreamUrl,
 						stdoutWritable,
 						streamAbortController.signal,
@@ -164,9 +182,11 @@ export const execSubcommand = createCommand({
 				);
 			} else {
 				if (stdoutStreamUrl) {
-					logger.debug('starting stdout stream from: %s', stdoutStreamUrl);
+					logger.debug('[exec] starting stdout stream: %s', stdoutStreamUrl);
+					streamLabels.push('stdout');
 					streamPromises.push(
 						streamUrlToWritable(
+							'stdout',
 							stdoutStreamUrl,
 							stdoutWritable,
 							streamAbortController.signal,
@@ -176,9 +196,11 @@ export const execSubcommand = createCommand({
 				}
 
 				if (stderrStreamUrl) {
-					logger.debug('starting stderr stream from: %s', stderrStreamUrl);
+					logger.debug('[exec] starting stderr stream: %s', stderrStreamUrl);
+					streamLabels.push('stderr');
 					streamPromises.push(
 						streamUrlToWritable(
+							'stderr',
 							stderrStreamUrl,
 							stderrWritable,
 							streamAbortController.signal,
@@ -188,17 +210,63 @@ export const execSubcommand = createCommand({
 				}
 			}
 
+			logger.debug(
+				'[exec] %d stream(s) started [%s], now long-polling executionGet',
+				streamPromises.length,
+				streamLabels.join(', ')
+			);
+
 			// Use server-side long-polling to wait for execution completion
 			// This is more efficient than client-side polling and provides immediate
 			// error detection if the sandbox is terminated
-			const finalExecution = await executionGet(client, {
-				executionId: execution.executionId,
-				orgId,
-				wait: EXECUTION_WAIT_DURATION,
-			});
+			let finalExecution: Awaited<ReturnType<typeof executionGet>>;
+			const pollStart = Date.now();
+			try {
+				finalExecution = await executionGet(client, {
+					executionId: execution.executionId,
+					orgId,
+					wait: EXECUTION_WAIT_DURATION,
+				});
+			} catch (err) {
+				// Abort any active stream readers before rethrowing so they
+				// don't keep running after the execution poll has failed.
+				streamAbortController.abort();
+				throw err;
+			}
+			logger.debug(
+				'[exec] executionGet returned in %dms: status=%s, exitCode=%s',
+				Date.now() - pollStart,
+				finalExecution.status,
+				finalExecution.exitCode ?? 'undefined'
+			);
 
-			// Wait for all streams to reach EOF (Pulse blocks until true EOF)
-			await Promise.all(streamPromises);
+			// Wait for all streams to reach EOF (Pulse blocks until true EOF).
+			// Safety: execution is confirmed complete so all data has been written
+			// and complete/v2 sent. If Pulse doesn't close the response within
+			// a grace period (e.g. cross-server routing delay, stale metadata
+			// cache), abort the streams to prevent an indefinite hang.
+			if (streamPromises.length > 0) {
+				logger.debug('[exec] waiting for %d stream(s) to EOF', streamPromises.length);
+				const streamWaitStart = Date.now();
+				let graceTriggered = false;
+				const streamGrace = setTimeout(() => {
+					graceTriggered = true;
+					logger.debug(
+						'[exec] stream grace period (5s) expired after execution complete — aborting streams'
+					);
+					streamAbortController.abort();
+				}, 5_000);
+				try {
+					await Promise.all(streamPromises);
+				} finally {
+					clearTimeout(streamGrace);
+				}
+				logger.debug(
+					'[exec] all streams done in %dms (graceTriggered=%s)',
+					Date.now() - streamWaitStart,
+					graceTriggered
+				);
+			}
 
 			// Ensure stdout is fully flushed before continuing
 			if (!options.json && process.stdout.writable) {
@@ -258,42 +326,72 @@ export const execSubcommand = createCommand({
 });
 
 async function streamUrlToWritable(
+	label: string,
 	url: string,
 	writable: NodeJS.WritableStream,
 	signal: AbortSignal,
 	logger: Logger
 ): Promise<void> {
+	const streamStart = Date.now();
 	try {
-		logger.debug('fetching stream: %s', url);
-		const response = await fetch(url, { signal });
-		logger.debug('stream response status: %d', response.status);
+		// Signal to Pulse that this is a v2 stream so it waits for v2 metadata
+		// instead of falling back to the legacy download path on a short timeout.
+		const v2Url = new URL(url);
+		v2Url.searchParams.set('v', '2');
+		logger.debug('[stream:%s] fetching: %s', label, v2Url.href);
+		const response = await fetch(v2Url.href, { signal });
+		logger.debug(
+			'[stream:%s] response status=%d in %dms',
+			label,
+			response.status,
+			Date.now() - streamStart
+		);
 
 		if (!response.ok || !response.body) {
-			logger.debug('stream response not ok or no body');
+			logger.debug('[stream:%s] not ok or no body — returning', label);
 			return;
 		}
 
 		const reader = response.body.getReader();
+		let chunks = 0;
+		let totalBytes = 0;
 
 		// Read until EOF - Pulse will block until data is available
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) {
-				logger.debug('stream EOF');
+				logger.debug(
+					'[stream:%s] EOF after %dms (%d chunks, %d bytes)',
+					label,
+					Date.now() - streamStart,
+					chunks,
+					totalBytes
+				);
 				break;
 			}
 
 			if (value) {
-				logger.debug('stream chunk: %d bytes', value.length);
+				chunks++;
+				totalBytes += value.length;
+				if (chunks <= 3 || chunks % 100 === 0) {
+					logger.debug(
+						'[stream:%s] chunk #%d: %d bytes (total: %d bytes, +%dms)',
+						label,
+						chunks,
+						value.length,
+						totalBytes,
+						Date.now() - streamStart
+					);
+				}
 				await writeAndDrain(writable, value);
 			}
 		}
 	} catch (err) {
 		if (err instanceof Error && err.name === 'AbortError') {
-			logger.debug('stream aborted');
+			logger.debug('[stream:%s] aborted after %dms', label, Date.now() - streamStart);
 			return;
 		}
-		logger.debug('stream error: %s', err);
+		logger.debug('[stream:%s] error after %dms: %s', label, Date.now() - streamStart, err);
 	}
 }
 

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

@@ -198,6 +198,12 @@ export const runSubcommand = createCommand({
 				if (!options.json) {
 					tui.error(`failed with exit code ${result.exitCode} in ${duration}ms`);
 				}
+				// Use process.exit() directly rather than process.exitCode to ensure
+				// the exit code propagates reliably across all runtimes (Bun/Node).
+				// process.exitCode can be overwritten by later async cleanup.
+				if (!options.json) {
+					process.exit(result.exitCode);
+				}
 				process.exitCode = result.exitCode;
 			}
 

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

@@ -17,7 +17,7 @@ import { z } from 'zod';
 import { getCommand } from '../../../../command-prefix';
 import { getCatalystAPIClient } from '../../../../config';
 import { encryptFIPSKEMDEMStream } from '../../../../crypto/box';
-import { ErrorCode } from '../../../../errors';
+import { ErrorCode, getExitCode } from '../../../../errors';
 import * as tui from '../../../../tui';
 import { createCommand } from '../../../../types';
 import { validateAptDependencies } from '../../../../utils/apt-validator';
@@ -941,7 +941,7 @@ export const buildSubcommand = createCommand({
 									2
 								)
 							);
-							process.exit(ErrorCode.MALWARE_DETECTED);
+							process.exit(getExitCode(ErrorCode.MALWARE_DETECTED));
 						}
 
 						console.log('');

package/src/errors.ts

@@ -1,22 +1,51 @@
 import type { Logger } from './types';
 
 /**
- * Standard exit codes for the CLI
+ * Standard exit codes for the CLI.
+ *
+ * Values start at 10 to avoid collisions with Unix signal numbers (1-9)
+ * and shell conventions (e.g. 2 = misuse of builtins, 9 = SIGKILL/OOM).
+ * Range 10-125 is safe — below shell-reserved 126-128 and signal-death
+ * codes 128+N.
+ *
+ * 0 and 1 are kept as universal success/failure codes.
  */
 export enum ExitCode {
 	SUCCESS = 0,
 	GENERAL_ERROR = 1,
-	VALIDATION_ERROR = 2,
-	AUTH_ERROR = 3,
-	NOT_FOUND = 4,
-	PERMISSION_ERROR = 5,
-	NETWORK_ERROR = 6,
-	FILE_ERROR = 7,
-	USER_CANCELLED = 8,
-	BUILD_FAILED = 9,
-	SECURITY_ERROR = 10,
+	VALIDATION_ERROR = 10,
+	AUTH_ERROR = 11,
+	NOT_FOUND = 12,
+	PERMISSION_ERROR = 13,
+	NETWORK_ERROR = 14,
+	FILE_ERROR = 15,
+	USER_CANCELLED = 16,
+	BUILD_FAILED = 17,
+	SECURITY_ERROR = 18,
+	PAYMENT_REQUIRED = 19,
+	UPGRADE_REQUIRED = 20,
 }
 
+/**
+ * Human-readable descriptions for each exit code.
+ * This is the single source of truth consumed by the schema generator and AI help.
+ */
+export const exitCodeDescriptions: Record<number, string> = {
+	[ExitCode.SUCCESS]: 'Success',
+	[ExitCode.GENERAL_ERROR]: 'General error',
+	[ExitCode.VALIDATION_ERROR]: 'Validation error (invalid arguments or options)',
+	[ExitCode.AUTH_ERROR]: 'Authentication error (login required or credentials invalid)',
+	[ExitCode.NOT_FOUND]: 'Resource not found (project, file, deployment, etc.)',
+	[ExitCode.PERMISSION_ERROR]: 'Permission denied (insufficient access rights)',
+	[ExitCode.NETWORK_ERROR]: 'Network error (API unreachable or timeout)',
+	[ExitCode.FILE_ERROR]: 'File system error (file read/write failed)',
+	[ExitCode.USER_CANCELLED]: 'User cancelled (operation aborted by user)',
+	[ExitCode.BUILD_FAILED]: 'Build failed',
+	[ExitCode.SECURITY_ERROR]: 'Security error (malware detected)',
+	[ExitCode.PAYMENT_REQUIRED]: 'Payment required (plan upgrade needed)',
+	[ExitCode.UPGRADE_REQUIRED]: 'Upgrade required (CLI version too old)',
+};
+
 /**
  * Standard error codes for the CLI
  */
@@ -152,7 +181,11 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 
 		// Payment required - user needs to upgrade their plan
 		case ErrorCode.PAYMENT_REQUIRED:
-			return ExitCode.GENERAL_ERROR;
+			return ExitCode.PAYMENT_REQUIRED;
+
+		// Upgrade required - CLI version too old
+		case ErrorCode.UPGRADE_REQUIRED:
+			return ExitCode.UPGRADE_REQUIRED;
 
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
@@ -162,7 +195,6 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.RUNTIME_ERROR:
 		case ErrorCode.INTERNAL_ERROR:
 		case ErrorCode.NOT_IMPLEMENTED:
-		case ErrorCode.UPGRADE_REQUIRED:
 		default:
 			return ExitCode.GENERAL_ERROR;
 	}

package/src/schema-generator.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import type { CommandDefinition, SubcommandDefinition, CommandSchemas } from './types';
+import { exitCodeDescriptions } from './errors';
 import { parseArgsSchema, parseOptionsSchema } from './schema-parser';
 import * as z from 'zod';
 
@@ -313,18 +314,7 @@ export function generateCLISchema(
 		name: 'agentuity',
 		version,
 		description: 'Agentuity CLI',
-		exitCodes: {
-			0: 'Success',
-			1: 'General error',
-			2: 'Validation error (invalid arguments or options)',
-			3: 'Authentication error (login required or credentials invalid)',
-			4: 'Resource not found (project, file, deployment, etc.)',
-			5: 'Permission denied (insufficient access rights)',
-			6: 'Network error (API unreachable or timeout)',
-			7: 'File system error (file read/write failed)',
-			8: 'User cancelled (operation aborted by user)',
-			9: 'Build failed',
-		},
+		exitCodes: { ...exitCodeDescriptions },
 		globalOptions: [
 			{
 				name: 'config',

package/src/utils/stream-capture.ts

@@ -0,0 +1,39 @@
+import { createWriteStream } from 'node:fs';
+
+/**
+ * Stream a ReadableStream of raw bytes to a file on disk.
+ *
+ * This mirrors the pattern used by the deploy fork wrapper to capture child
+ * process stdout/stderr without accumulating the output in memory.  Returns
+ * the total number of bytes written.
+ */
+export async function captureStreamToFile(
+	stream: ReadableStream<Uint8Array>,
+	filePath: string
+): Promise<number> {
+	const writer = createWriteStream(filePath);
+	const reader = stream.getReader();
+	let totalBytes = 0;
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			const ok = writer.write(value);
+			totalBytes += value.byteLength;
+
+			// Respect backpressure: wait for drain when the internal buffer is full
+			if (!ok) {
+				await new Promise<void>((resolve) => writer.once('drain', resolve));
+			}
+		}
+	} finally {
+		await new Promise<void>((resolve, reject) => {
+			writer.once('error', reject);
+			writer.end(resolve);
+		});
+	}
+
+	return totalBytes;
+}