@agentuity/cli 0.0.111 → 0.0.112

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

@@ -0,0 +1,296 @@
+/**
+ * Deploy fork wrapper
+ *
+ * This module implements a fork-based deployment wrapper that:
+ * 1. Spawns the deploy command as a child process using bunx
+ * 2. Tees stdout/stderr to both the terminal and a Pulse stream
+ * 3. On failure, sends diagnostics to the API
+ *
+ * This approach captures crashes, Bun runtime issues, and all output
+ * for debugging failed deployments.
+ */
+
+import { spawn, type Subprocess } from 'bun';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import type { APIClient } from '../../api';
+import { getUserAgent } from '../../api';
+import { isUnicode } from '../../tui/symbols';
+import { projectDeploymentFail, type ClientDiagnostics, type Deployment } from '@agentuity/server';
+import type { Logger } from '@agentuity/core';
+
+export interface ForkDeployOptions {
+	projectDir: string;
+	apiClient: APIClient;
+	logger: Logger;
+	sdkKey: string;
+	deployment: Deployment;
+	args: string[];
+}
+
+export interface ForkDeployResult {
+	success: boolean;
+	exitCode: number;
+	diagnostics?: ClientDiagnostics;
+}
+
+/**
+ * Stream data to a Pulse stream URL
+ */
+async function streamToPulse(
+	streamURL: string,
+	sdkKey: string,
+	data: string,
+	logger: Logger
+): Promise<void> {
+	try {
+		const response = await fetch(streamURL, {
+			method: 'PUT',
+			headers: {
+				'Content-Type': 'text/plain',
+				Authorization: `Bearer ${sdkKey}`,
+				'User-Agent': getUserAgent(),
+			},
+			body: data,
+		});
+
+		if (!response.ok) {
+			logger.error('Failed to stream to Pulse: %s', response.status);
+		}
+	} catch (err) {
+		logger.error('Error streaming to Pulse: %s', err);
+	}
+}
+
+/**
+ * Run the deploy command as a forked child process
+ */
+export async function runForkedDeploy(options: ForkDeployOptions): Promise<ForkDeployResult> {
+	const { projectDir, apiClient, logger, sdkKey, deployment, args } = options;
+
+	const deploymentId = deployment.id;
+	const buildLogsStreamURL = deployment.buildLogsStreamURL;
+	const reportFile = join(tmpdir(), `agentuity-deploy-${deploymentId}.json`);
+	const cleanLogsFile = join(tmpdir(), `agentuity-deploy-${deploymentId}-logs.txt`);
+	let outputBuffer = '';
+	let proc: Subprocess | null = null;
+
+	try {
+		const childArgs = [
+			'agentuity',
+			'deploy',
+			'--child-mode',
+			`--report-file=${reportFile}`,
+			...args,
+		];
+
+		// Pass the deployment info via environment variable (same format as CI builds)
+		const deploymentEnvValue = JSON.stringify({
+			id: deployment.id,
+			orgId: deployment.orgId,
+			publicKey: deployment.publicKey,
+		});
+
+		logger.debug('Spawning child deploy process: bunx %s', childArgs.join(' '));
+
+		// Get terminal dimensions to pass to child
+		const columns = process.stdout.columns || 80;
+		const rows = process.stdout.rows || 24;
+
+		proc = spawn({
+			cmd: ['bunx', ...childArgs],
+			cwd: projectDir,
+			env: {
+				...process.env,
+				AGENTUITY_FORK_PARENT: '1',
+				AGENTUITY_DEPLOYMENT: deploymentEnvValue,
+				// Force color and unicode output since child stdout/stderr are piped (not TTY)
+				FORCE_COLOR: '1',
+				// Only force unicode if parent terminal supports it
+				...(isUnicode ? { FORCE_UNICODE: '1' } : {}),
+				// Pass terminal dimensions
+				COLUMNS: String(columns),
+				LINES: String(rows),
+				// Enable clean log collection for Pulse streaming
+				AGENTUITY_CLEAN_LOGS_FILE: cleanLogsFile,
+			},
+			stdin: 'inherit',
+			stdout: 'pipe',
+			stderr: 'pipe',
+		});
+
+		const handleOutput = async (stream: ReadableStream<Uint8Array>, isStderr: boolean) => {
+			const reader = stream.getReader();
+			const decoder = new TextDecoder();
+			const target = isStderr ? process.stderr : process.stdout;
+
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+
+					const text = decoder.decode(value, { stream: true });
+					outputBuffer += text;
+					target.write(value);
+				}
+			} catch (err) {
+				logger.debug('Stream read error: %s', err);
+			}
+		};
+
+		const stdoutPromise =
+			proc.stdout && typeof proc.stdout !== 'number'
+				? handleOutput(proc.stdout, false)
+				: Promise.resolve();
+		const stderrPromise =
+			proc.stderr && typeof proc.stderr !== 'number'
+				? handleOutput(proc.stderr, true)
+				: Promise.resolve();
+
+		await Promise.all([stdoutPromise, stderrPromise]);
+
+		const exitCode = await proc.exited;
+		logger.debug('Child process exited with code: %d', exitCode);
+
+		let diagnostics: ClientDiagnostics | undefined;
+
+		if (existsSync(reportFile)) {
+			try {
+				const reportContent = readFileSync(reportFile, 'utf-8');
+				diagnostics = JSON.parse(reportContent) as ClientDiagnostics;
+				unlinkSync(reportFile);
+			} catch (err) {
+				logger.debug('Failed to read report file: %s', err);
+			}
+		}
+
+		// Stream clean logs to Pulse (prefer clean logs over raw output)
+		if (buildLogsStreamURL) {
+			let logsContent = '';
+			if (existsSync(cleanLogsFile)) {
+				try {
+					logsContent = readFileSync(cleanLogsFile, 'utf-8');
+					unlinkSync(cleanLogsFile);
+				} catch (err) {
+					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);
+			}
+		}
+
+		if (exitCode !== 0) {
+			const errorMessage = `Deploy process exited with code ${exitCode}`;
+
+			if (!diagnostics) {
+				diagnostics = {
+					success: false,
+					errors: [
+						{
+							type: 'general',
+							scope: 'deploy',
+							message: errorMessage,
+							code: 'DEPLOY_CRASH',
+						},
+					],
+					warnings: [],
+					diagnostics: [],
+					error: errorMessage,
+				};
+			} else if (!diagnostics.error) {
+				diagnostics.error = errorMessage;
+			}
+
+			try {
+				await projectDeploymentFail(apiClient, deploymentId, {
+					error: errorMessage,
+					diagnostics,
+				});
+			} catch (err) {
+				logger.error('Failed to report deployment failure: %s', err);
+			}
+
+			return { success: false, exitCode, diagnostics };
+		}
+
+		return { success: true, exitCode, diagnostics };
+	} catch (err) {
+		const errorMessage = err instanceof Error ? err.message : String(err);
+		logger.error('Fork deploy error: %s', errorMessage);
+
+		if (buildLogsStreamURL) {
+			let logsContent = '';
+			if (existsSync(cleanLogsFile)) {
+				try {
+					logsContent = readFileSync(cleanLogsFile, 'utf-8');
+					unlinkSync(cleanLogsFile);
+				} catch {
+					// ignore
+				}
+			}
+			if (!logsContent) {
+				logsContent = outputBuffer;
+			}
+			logsContent += `\n\n--- FORK ERROR ---\n${errorMessage}\n`;
+			await streamToPulse(buildLogsStreamURL, sdkKey, logsContent, logger);
+		}
+
+		try {
+			await projectDeploymentFail(apiClient, deploymentId, {
+				error: errorMessage,
+				diagnostics: {
+					success: false,
+					errors: [
+						{
+							type: 'general',
+							scope: 'deploy',
+							message: errorMessage,
+							code: 'DEPLOY_FORK_ERROR',
+						},
+					],
+					warnings: [],
+					diagnostics: [],
+					error: errorMessage,
+				},
+			});
+		} catch (failErr) {
+			logger.error('Failed to report deployment failure: %s', failErr);
+		}
+
+		return {
+			success: false,
+			exitCode: 1,
+			diagnostics: {
+				success: false,
+				errors: [
+					{
+						type: 'general',
+						scope: 'deploy',
+						message: errorMessage,
+						code: 'DEPLOY_FORK_ERROR',
+					},
+				],
+				warnings: [],
+				diagnostics: [],
+				error: errorMessage,
+			},
+		};
+	} finally {
+		// Clean up temp files
+		for (const file of [reportFile, cleanLogsFile]) {
+			if (existsSync(file)) {
+				try {
+					unlinkSync(file);
+				} catch {
+					// ignore
+				}
+			}
+		}
+	}
+}

package/src/cmd/cloud/deploy.ts

@@ -53,6 +53,7 @@ import * as domain from '../../domain';
 import { ErrorCode } from '../../errors';
 import { typecheck } from '../build/typecheck';
 import { BuildReportCollector, setGlobalCollector, clearGlobalCollector } from '../../build-report';
+import { runForkedDeploy } from './deploy-fork';
 
 const DeploymentCancelledError = StructuredError(
 	'DeploymentCancelled',
@@ -107,6 +108,11 @@ export const deploySubcommand = createSubcommand({
 					.describe(
 						'file path to save build report JSON with errors, warnings, and diagnostics'
 					),
+				childMode: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('Internal: run as forked child process'),
 			})
 		),
 		response: DeployResponseSchema,
@@ -140,8 +146,67 @@ export const deploySubcommand = createSubcommand({
 			);
 		}
 
-		// Check for pre-created deployment from CI build environment
+		// Check if we're running as a forked child process
+		const isChildProcess = opts.childMode || process.env.AGENTUITY_FORK_PARENT === '1';
 		const deploymentEnv = process.env.AGENTUITY_DEPLOYMENT;
+
+		// If not in child mode and no pre-created deployment, run as fork wrapper to capture crashes
+		// (CI builds set AGENTUITY_DEPLOYMENT, fork wrapper also sets it for the child)
+		if (!isChildProcess && !deploymentEnv) {
+			logger.debug('Running deploy as fork wrapper');
+
+			// First, create the deployment to get the ID, publicKey, and stream URL
+			const deploymentConfig = project.deployment ?? {};
+			const initialDeployment = await projectDeploymentCreate(
+				apiClient,
+				project.projectId,
+				deploymentConfig
+			);
+
+			logger.debug('Created deployment: %s', initialDeployment.id);
+
+			// Build args to pass to child, excluding child-mode specific ones
+			const childArgs: string[] = [];
+			if (opts.logsUrl) childArgs.push(`--logs-url=${opts.logsUrl}`);
+			if (opts.trigger) childArgs.push(`--trigger=${opts.trigger}`);
+			if (opts.commitUrl) childArgs.push(`--commit-url=${opts.commitUrl}`);
+			if (opts.message) childArgs.push(`--message=${opts.message}`);
+			if (opts.commit) childArgs.push(`--commit=${opts.commit}`);
+			if (opts.branch) childArgs.push(`--branch=${opts.branch}`);
+			if (opts.provider) childArgs.push(`--provider=${opts.provider}`);
+			if (opts.repo) childArgs.push(`--repo=${opts.repo}`);
+			if (opts.event) childArgs.push(`--event=${opts.event}`);
+			if (opts.pullRequestNumber)
+				childArgs.push(`--pull-request-number=${opts.pullRequestNumber}`);
+			if (opts.pullRequestUrl) childArgs.push(`--pull-request-url=${opts.pullRequestUrl}`);
+
+			const result = await runForkedDeploy({
+				projectDir,
+				apiClient,
+				logger,
+				sdkKey: sdkKey!,
+				deployment: initialDeployment,
+				args: childArgs,
+			});
+
+			if (!result.success) {
+				const appUrl = getAppBaseURL(
+					process.env.AGENTUITY_REGION ?? config?.name,
+					config?.overrides
+				);
+				const deploymentLink = `${appUrl}/projects/${project.projectId}/deployments/${initialDeployment.id}`;
+				tui.fatal(
+					`Deployment failed: ${tui.link(deploymentLink, 'Deployment Page')}`,
+					ErrorCode.BUILD_FAILED
+				);
+			}
+
+			return {
+				success: true,
+				deploymentId: initialDeployment.id,
+				projectId: project.projectId,
+			};
+		}
 		let useExistingDeployment = false;
 		if (deploymentEnv) {
 			const ExistingDeploymentSchema = z.object({
@@ -267,7 +332,9 @@ export const deploySubcommand = createSubcommand({
 						label: 'Sync Env & Secrets',
 						run: async () => {
 							try {
-								if (useExistingDeployment) {
+								const isCIBuild =
+									useExistingDeployment && process.env.AGENTUITY_FORK_PARENT !== '1';
+								if (isCIBuild) {
 									return stepSkipped('skipped in CI build');
 								}
 								// Read env file
@@ -307,7 +374,7 @@ export const deploySubcommand = createSubcommand({
 						label: 'Create Deployment',
 						run: async () => {
 							if (useExistingDeployment) {
-								return stepSkipped('skipped in CI build');
+								return stepSkipped('using pre-created deployment');
 							}
 							try {
 								deployment = await projectDeploymentCreate(

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

@@ -5,6 +5,12 @@ import { createSandboxClient } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxGet } from '@agentuity/server';
 
+const SandboxResourcesSchema = z.object({
+	memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
+	cpu: z.string().optional().describe('CPU limit (e.g., "500m", "1000m")'),
+	disk: z.string().optional().describe('Disk limit (e.g., "1Gi", "10Gi")'),
+});
+
 const SandboxGetResponseSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID'),
 	status: z.string().describe('Current status'),
@@ -17,6 +23,7 @@ const SandboxGetResponseSchema = z.object({
 	stderrStreamUrl: z.string().optional().describe('URL to stderr output stream'),
 	dependencies: z.array(z.string()).optional().describe('Apt packages installed'),
 	metadata: z.record(z.string(), z.unknown()).optional().describe('User-defined metadata'),
+	resources: SandboxResourcesSchema.optional().describe('Resource limits'),
 });
 
 export const getSubcommand = createCommand({
@@ -85,6 +92,15 @@ export const getSubcommand = createCommand({
 			if (result.dependencies && result.dependencies.length > 0) {
 				console.log(`${tui.muted('Dependencies:')}    ${result.dependencies.join(', ')}`);
 			}
+			if (result.resources) {
+				const resourceParts: string[] = [];
+				if (result.resources.memory) resourceParts.push(`memory=${result.resources.memory}`);
+				if (result.resources.cpu) resourceParts.push(`cpu=${result.resources.cpu}`);
+				if (result.resources.disk) resourceParts.push(`disk=${result.resources.disk}`);
+				if (resourceParts.length > 0) {
+					console.log(`${tui.muted('Resources:')}       ${resourceParts.join(', ')}`);
+				}
+			}
 			if (result.metadata && Object.keys(result.metadata).length > 0) {
 				console.log(`${tui.muted('Metadata:')}        ${JSON.stringify(result.metadata)}`);
 			}
@@ -102,6 +118,7 @@ export const getSubcommand = createCommand({
 			stderrStreamUrl: result.stderrStreamUrl,
 			dependencies: result.dependencies,
 			metadata: result.metadata,
+			resources: result.resources,
 		};
 	},
 });

package/src/cmd/cloud/ssh.ts

@@ -4,7 +4,7 @@ import * as tui from '../../tui';
 import { getIONHost } from '../../config';
 import { getCommand } from '../../command-prefix';
 const args = z.object({
-	identifier: z.string().optional().describe('The project or deployment id to use'),
+	identifier: z.string().optional().describe('The project, deployment, or sandbox id to use'),
 	command: z.string().optional().describe('The command to run'),
 });
 
@@ -14,7 +14,7 @@ const options = z.object({
 
 export const sshSubcommand = createSubcommand({
 	name: 'ssh',
-	description: 'SSH into a cloud project',
+	description: 'SSH into a cloud project or sandbox',
 	tags: ['read-only', 'slow', 'requires-auth', 'requires-deployment'],
 	idempotent: true,
 	examples: [
@@ -24,6 +24,10 @@ export const sshSubcommand = createSubcommand({
 			command: getCommand('cloud ssh deploy_abc123xyz'),
 			description: 'SSH into specific deployment',
 		},
+		{
+			command: getCommand('cloud ssh sbx_abc123xyz'),
+			description: 'SSH into a sandbox',
+		},
 		{ command: getCommand("cloud ssh 'ps aux'"), description: 'Run command and exit' },
 		{
 			command: getCommand("cloud ssh proj_abc123xyz 'tail -f /var/log/app.log'"),
@@ -47,7 +51,13 @@ export const sshSubcommand = createSubcommand({
 		let identifier = args?.identifier;
 		let command = args?.command;
 
-		if (!(identifier?.startsWith('proj_') || identifier?.startsWith('deploy_'))) {
+		if (
+			!(
+				identifier?.startsWith('proj_') ||
+				identifier?.startsWith('deploy_') ||
+				identifier?.startsWith('sbx_')
+			)
+		) {
 			command = identifier;
 			identifier = undefined;
 		}

package/src/cmd/dev/index.ts

@@ -707,7 +707,7 @@ export const command = createCommand({
 							generateRouteRegistry(srcDir, routeInfoList);
 							logger.debug('Agent and route registries generated for dev mode');
 
-							// Step 3: Generate entry file with workbench config
+							// Step 3: Generate entry file with workbench and analytics config
 							// Note: vitePort is NOT passed here - the app reads process.env.VITE_PORT at runtime
 							const { generateEntryFile } = await import('../build/entry-generator');
 							await generateEntryFile({
@@ -717,6 +717,7 @@ export const command = createCommand({
 								logger,
 								mode: 'dev',
 								workbench: workbenchConfigData.enabled ? workbenchConfigData : undefined,
+								analytics: agentuityConfig?.analytics,
 							});
 
 							// Step 4: Bundle the app with LLM patches (dev mode = no minification)
@@ -783,19 +784,24 @@ export const command = createCommand({
 						console.log('');
 						fileWatcher.resume();
 						// wait for a file change or shutdown to trigger a recompile
-						while (true) {
-							if (shutdownRequested) {
-								return;
-							}
-							if (shouldRestart) {
-								break;
-							}
+						while (!shutdownRequested && !shouldRestart) {
 							await tui.spinner({
 								message: 'Waiting for changes...',
 								clearOnSuccess: true,
-								callback: () => Bun.sleep(1000),
+								callback: async () => {
+									// Check more frequently so CTRL+C is responsive
+									for (let i = 0; i < 10; i++) {
+										if (shutdownRequested || shouldRestart) {
+											return;
+										}
+										await Bun.sleep(100);
+									}
+								},
 							});
 						}
+						if (shutdownRequested) {
+							return;
+						}
 					}
 				} catch (error) {
 					tui.error(`Failed to build dev bundle: ${error}`);
@@ -817,10 +823,6 @@ export const command = createCommand({
 				}
 
 				try {
-					// Set environment variables for LLM provider patches BEFORE starting server
-					// These must be set so the bundled patches can route LLM calls through AI Gateway
-					const serviceUrls = getServiceUrls(project?.region);
-
 					// Load SDK key from project .env files for AI Gateway routing
 					// This must be set so the bundled AI SDK patches can inject the API key
 					if (!process.env.AGENTUITY_SDK_KEY) {
@@ -848,6 +850,9 @@ export const command = createCommand({
 					process.env.AGENTUITY_PORT = process.env.PORT;
 
 					if (project) {
+						// Set environment variables for LLM provider patches
+						// These must be set so the bundled patches can route LLM calls through AI Gateway
+						const serviceUrls = getServiceUrls(project.region);
 						process.env.AGENTUITY_TRANSPORT_URL = serviceUrls.catalyst;
 						process.env.AGENTUITY_CATALYST_URL = serviceUrls.catalyst;
 						process.env.AGENTUITY_VECTOR_URL = serviceUrls.vector;

package/src/config.ts

@@ -556,7 +556,7 @@ export const InitialProjectConfigSchema = z.intersection(
 type InitialProjectConfig = z.infer<typeof InitialProjectConfigSchema>;
 
 export async function createProjectConfig(dir: string, config: InitialProjectConfig) {
-	const { sdkKey, ...sanitizedConfig } = config;
+	const { sdkKey, skipGitSetup: _skipGitSetup, ...sanitizedConfig } = config;
 
 	// generate the project config
 	const configPath = join(dir, 'agentuity.json');

package/src/log-collector.ts

@@ -0,0 +1,77 @@
+/**
+ * Log Collector for clean build logs
+ *
+ * Provides a mechanism to collect clean, non-animated log output
+ * for streaming to external services (like Pulse) while keeping
+ * animated TUI output for the user's terminal.
+ *
+ * Usage:
+ * - Set AGENTUITY_CLEAN_LOGS_FILE env var to a file path
+ * - TUI components call appendLog() for final state messages
+ * - Logs are written to the file for the parent process to read
+ */
+
+import { appendFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Get the clean logs file path from environment
+ */
+function getCleanLogsFile(): string | undefined {
+	return process.env.AGENTUITY_CLEAN_LOGS_FILE;
+}
+
+/**
+ * Disable log collection (called on write errors to prevent repeated failures)
+ */
+function disableLogCollection(error: unknown): void {
+	console.debug('Log collection disabled due to write error: %s', error);
+	delete process.env.AGENTUITY_CLEAN_LOGS_FILE;
+}
+
+/**
+ * Check if log collection is enabled (via environment variable)
+ */
+export function isLogCollectionEnabled(): boolean {
+	return !!getCleanLogsFile();
+}
+
+/**
+ * Initialize the clean logs file (clears any existing content)
+ */
+export function initCleanLogsFile(filePath: string): void {
+	try {
+		writeFileSync(filePath, '');
+		process.env.AGENTUITY_CLEAN_LOGS_FILE = filePath;
+	} catch (err) {
+		console.debug('Failed to initialize clean logs file: %s', err);
+	}
+}
+
+/**
+ * Append a clean log line (no ANSI codes, no animation)
+ * Only appends if collection is enabled
+ */
+export function appendLog(message: string): void {
+	const file = getCleanLogsFile();
+	if (file) {
+		try {
+			appendFileSync(file, message + '\n');
+		} catch (err) {
+			disableLogCollection(err);
+		}
+	}
+}
+
+/**
+ * Append multiple log lines
+ */
+export function appendLogs(messages: string[]): void {
+	const file = getCleanLogsFile();
+	if (file) {
+		try {
+			appendFileSync(file, messages.join('\n') + '\n');
+		} catch (err) {
+			disableLogCollection(err);
+		}
+	}
+}

package/src/output.ts

@@ -1,4 +1,5 @@
 import type { GlobalOptions } from './types';
+import { isTTYLike } from './tui';
 
 /**
  * Output formatting utilities for agent-friendly CLI
@@ -59,7 +60,7 @@ export function shouldDisableColors(options: GlobalOptions): boolean {
 		return false;
 	}
 	// auto mode - disable in JSON/quiet mode or non-TTY
-	return options.json === true || options.quiet === true || !process.stdout.isTTY;
+	return options.json === true || options.quiet === true || !isTTYLike();
 }
 
 /**