@agentuity/cli 0.0.110 → 0.0.112

package/src/cmd/build/vite/vite-builder.ts

@@ -103,6 +103,7 @@ export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
 			logger,
 			mode: dev ? 'dev' : 'prod',
 			workbench: workbenchConfig.enabled ? workbenchConfig : undefined,
+			analytics: config?.analytics,
 		});
 
 		// Finally, build with Bun.build
@@ -165,7 +166,7 @@ export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
 		const isLocalRegion = options.region === 'local';
 		const cdnDomain = isLocalRegion
 			? 'localstack-static-assets.t3.storage.dev'
-			: 'static.agentuity.com';
+			: 'cdn.agentuity.com';
 		const cdnBaseUrl =
 			!dev && deploymentId ? `https://${cdnDomain}/${deploymentId}/client/` : undefined;
 
@@ -305,7 +306,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// Generate agent and route registries for type augmentation BEFORE builds
 	// (TypeScript needs these files to exist during type checking)
 	generateAgentRegistry(srcDir, agentMetadata);
-	generateRouteRegistry(srcDir, routeInfoList);
+	await generateRouteRegistry(srcDir, routeInfoList);
 	logger.debug('Agent and route registries generated');
 
 	// Check if web frontend exists

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

@@ -8,7 +8,14 @@ import { isRunningFromExecutable } from '../upgrade';
 import { createSubcommand, DeployOptionsSchema } from '../../types';
 import { getUserAgent } from '../../api';
 import * as tui from '../../tui';
-import { saveProjectDir, getDefaultConfigDir, loadProjectSDKKey } from '../../config';
+import {
+	saveProjectDir,
+	getDefaultConfigDir,
+	loadProjectSDKKey,
+	updateProjectConfig,
+} from '../../config';
+import { getProjectGithubStatus } from '../integration/api';
+import { runGitLink } from '../git/link';
 import {
 	runSteps,
 	stepSuccess,
@@ -46,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',
@@ -100,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,
@@ -133,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({
@@ -163,6 +235,76 @@ export const deploySubcommand = createSubcommand({
 		try {
 			await saveProjectDir(projectDir);
 
+			// Check GitHub status and prompt for setup if not linked
+			// Skip in non-TTY environments (CI, automated runs) to prevent hanging
+			const hasTTY = process.stdin.isTTY && process.stdout.isTTY;
+			if (!useExistingDeployment && !project.skipGitSetup && hasTTY) {
+				try {
+					const githubStatus = await getProjectGithubStatus(apiClient, project.projectId);
+
+					if (githubStatus.linked && githubStatus.autoDeploy) {
+						// GitHub is already set up with auto-deploy, tell user to push instead
+						tui.newline();
+						tui.info(
+							`This project is linked to ${tui.bold(githubStatus.repoFullName ?? 'GitHub')} with automatic deployments enabled.`
+						);
+						tui.newline();
+						tui.info(
+							`Push a commit to the ${tui.bold(githubStatus.branch ?? 'main')} branch to trigger a deployment.`
+						);
+						tui.newline();
+						throw new DeploymentCancelledError();
+					}
+
+					if (!githubStatus.linked) {
+						tui.newline();
+						const wantSetup = await tui.confirm(
+							'Would you like to set up automatic deployments from GitHub?'
+						);
+
+						if (wantSetup) {
+							const result = await runGitLink({
+								apiClient,
+								projectId: project.projectId,
+								orgId: project.orgId,
+								logger,
+								skipAlreadyLinkedCheck: true,
+								config,
+							});
+
+							if (result.linked && result.autoDeploy) {
+								// GitHub linked with auto-deploy, tell user to push instead
+								tui.newline();
+								tui.info('GitHub integration set up successfully!');
+								tui.newline();
+								tui.info('Push a commit to trigger your first deployment.');
+								tui.newline();
+								throw new DeploymentCancelledError();
+							} else if (result.linked) {
+								// Linked but auto-deploy disabled, continue with manual deploy
+								tui.newline();
+								tui.info('GitHub repository linked. Continuing with deployment...');
+								tui.newline();
+							}
+						} else {
+							await updateProjectConfig(projectDir, { skipGitSetup: true }, config);
+							tui.newline();
+							tui.info(
+								`Skipping GitHub setup. Run ${tui.bold(getCommand('git link'))} later to enable it.`
+							);
+							tui.newline();
+						}
+					}
+				} catch (err) {
+					// Re-throw intentional cancellations
+					if (err instanceof DeploymentCancelledError) {
+						throw err;
+					}
+					// Log other errors as non-fatal and continue
+					logger.trace('Failed to check GitHub status: %s', err);
+				}
+			}
+
 			await runSteps(
 				[
 					!project.deployment?.domains?.length
@@ -190,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
@@ -230,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/create.ts

@@ -4,6 +4,12 @@ import * as tui from '../../../tui';
 import { createSandboxClient, parseFileArgs } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxCreate } from '@agentuity/server';
+import { StructuredError } from '@agentuity/core';
+
+const InvalidMetadataError = StructuredError(
+	'InvalidMetadataError',
+	'Metadata must be a valid JSON object'
+);
 
 const SandboxCreateResponseSchema = z.object({
 	sandboxId: z.string().describe('Unique sandbox identifier'),
@@ -55,6 +61,7 @@ export const createSubcommand = createCommand({
 				.array(z.string())
 				.optional()
 				.describe('Apt packages to install (can be specified multiple times)'),
+			metadata: z.string().optional().describe('JSON object of user-defined metadata'),
 		}),
 		response: SandboxCreateResponseSchema,
 	},
@@ -77,6 +84,20 @@ export const createSubcommand = createCommand({
 		const files = parseFileArgs(opts.file);
 		const hasFiles = files.length > 0;
 
+		let metadata: Record<string, unknown> | undefined;
+		if (opts.metadata) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(opts.metadata);
+			} catch {
+				throw new InvalidMetadataError();
+			}
+			if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+				throw new InvalidMetadataError();
+			}
+			metadata = parsed as Record<string, unknown>;
+		}
+
 		const result = await sandboxCreate(client, {
 			options: {
 				resources:
@@ -93,6 +114,7 @@ export const createSubcommand = createCommand({
 				command: hasFiles ? { exec: [], files } : undefined,
 				snapshot: opts.snapshot,
 				dependencies: opts.dependency,
+				metadata,
 			},
 			orgId,
 		});

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

@@ -14,7 +14,7 @@ const SandboxDeleteResponseSchema = z.object({
 
 export const deleteSubcommand = createCommand({
 	name: 'delete',
-	aliases: ['del', 'rm', 'remove', 'destroy'],
+	aliases: ['del', 'remove', 'destroy'],
 	description: 'Delete a sandbox',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	requires: { auth: true, region: true, org: true },
@@ -25,11 +25,7 @@ export const deleteSubcommand = createCommand({
 			description: 'Delete a sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox rm abc123'),
-			description: 'Delete using alias',
-		},
-		{
-			command: getCommand('cloud sandbox rm abc123 --confirm'),
+			command: getCommand('cloud sandbox delete abc123 --confirm'),
 			description: 'Delete without confirmation prompt',
 		},
 	],

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

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { writeFileSync } from 'node:fs';
+import { createCommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createSandboxClient } from './util';
+import { getCommand } from '../../../command-prefix';
+import { sandboxDownloadArchive } from '@agentuity/server';
+
+export const downloadSubcommand = createCommand({
+	name: 'download',
+	aliases: ['dl'],
+	description: 'Download files from a sandbox as a compressed archive',
+	tags: ['slow', 'requires-auth'],
+	requires: { auth: true, region: true, org: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz'),
+			description: 'Download sandbox files as tar.gz archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.zip --format zip'),
+			description: 'Download sandbox files as zip archive',
+		},
+		{
+			command: getCommand('cloud sandbox download sbx_abc123 ./backup.tar.gz --path /subdir'),
+			description: 'Download only a specific directory',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('The sandbox ID'),
+			output: z.string().describe('Output file path for the archive'),
+		}),
+		options: z.object({
+			path: z.string().optional().describe('Path in sandbox to download (defaults to root)'),
+			format: z
+				.enum(['zip', 'tar.gz'])
+				.default('tar.gz')
+				.optional()
+				.describe('Archive format (zip or tar.gz)'),
+		}),
+		response: z.object({
+			success: z.boolean(),
+			output: z.string(),
+			bytes: z.number(),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, region, logger, orgId } = ctx;
+
+		const client = createSandboxClient(logger, auth, region);
+		const format = opts.format || 'tar.gz';
+
+		const stream = await sandboxDownloadArchive(client, {
+			sandboxId: args.sandboxId,
+			path: opts.path || '.',
+			format,
+			orgId,
+		});
+
+		const chunks: Uint8Array[] = [];
+		const reader = stream.getReader();
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+		}
+
+		const totalBytes = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+		const buffer = new Uint8Array(totalBytes);
+		let offset = 0;
+		for (const chunk of chunks) {
+			buffer.set(chunk, offset);
+			offset += chunk.length;
+		}
+
+		writeFileSync(args.output, buffer);
+
+		if (!options.json) {
+			tui.success(`Downloaded ${formatSize(totalBytes)} to ${args.output}`);
+		}
+
+		return { success: true, output: args.output, bytes: totalBytes };
+	},
+});
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} bytes`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+export default downloadSubcommand;