@agentuity/server 0.1.15 → 0.1.17

package/src/api/sandbox/index.ts

@@ -21,7 +21,12 @@ export type {
 } from './execution';
 export { SandboxResponseError, writeAndDrain } from './util';
 export { SandboxClient } from './client';
-export type { SandboxClientOptions, SandboxInstance, ExecuteOptions } from './client';
+export type {
+	SandboxClientOptions,
+	SandboxClientRunIO,
+	SandboxInstance,
+	ExecuteOptions,
+} from './client';
 export {
 	sandboxWriteFiles,
 	sandboxReadFile,
@@ -57,6 +62,7 @@ export {
 	snapshotTag,
 	snapshotBuildInit,
 	snapshotBuildFinalize,
+	snapshotUpload,
 } from './snapshot';
 export type {
 	SnapshotInfo,
@@ -70,6 +76,8 @@ export type {
 	SnapshotBuildInitParams,
 	SnapshotBuildInitResponse,
 	SnapshotBuildFinalizeParams,
+	SnapshotUploadParams,
+	SnapshotUploadResponse,
 } from './snapshot';
 export { SnapshotBuildFileSchema } from './snapshot-build';
 export type { SnapshotBuildFile } from './snapshot-build';

package/src/api/sandbox/run.ts

@@ -138,6 +138,7 @@ export async function sandboxRun(
 		// Poll for sandbox completion in parallel with streaming
 		let attempts = 0;
 		let finalStatus: 'terminated' | 'failed' | null = null;
+		let finalExitCode: number | undefined;
 
 		while (attempts < MAX_POLL_ATTEMPTS) {
 			if (signal?.aborted) {
@@ -156,11 +157,13 @@ export async function sandboxRun(
 
 				if (sandboxInfo.status === 'terminated') {
 					finalStatus = 'terminated';
+					finalExitCode = sandboxInfo.exitCode;
 					break;
 				}
 
 				if (sandboxInfo.status === 'failed') {
 					finalStatus = 'failed';
+					finalExitCode = sandboxInfo.exitCode;
 					break;
 				}
 			} catch {
@@ -179,7 +182,7 @@ export async function sandboxRun(
 		if (finalStatus === 'terminated') {
 			return {
 				sandboxId,
-				exitCode: 0,
+				exitCode: finalExitCode ?? 0,
 				durationMs: Date.now() - started,
 			};
 		}
@@ -187,7 +190,7 @@ export async function sandboxRun(
 		if (finalStatus === 'failed') {
 			return {
 				sandboxId,
-				exitCode: 1,
+				exitCode: finalExitCode ?? 1,
 				durationMs: Date.now() - started,
 			};
 		}

package/src/api/sandbox/runtime.ts

@@ -3,14 +3,26 @@ import { APIClient, APIResponseSchema } from '../api';
 import { SandboxResponseError, API_VERSION } from './util';
 import type { ListRuntimesParams, ListRuntimesResponse, SandboxRuntime } from '@agentuity/core';
 
+const RuntimeRequirementsSchema = z
+	.object({
+		memory: z.string().optional().describe('Memory requirement (e.g., "1Gi")'),
+		cpu: z.string().optional().describe('CPU requirement (e.g., "1")'),
+		disk: z.string().optional().describe('Disk requirement (e.g., "500Mi")'),
+		networkEnabled: z.boolean().describe('Whether network access is enabled'),
+	})
+	.describe('Runtime resource requirements');
+
 const RuntimeInfoSchema = z
 	.object({
 		id: z.string().describe('Unique runtime identifier'),
 		name: z.string().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
 		description: z.string().optional().describe('Optional description'),
 		iconUrl: z.string().optional().describe('URL for runtime icon'),
+		brandColor: z.string().optional().describe('Brand color for the runtime (hex color code)'),
 		url: z.string().optional().describe('URL for runtime documentation or homepage'),
 		tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
+		requirements: RuntimeRequirementsSchema.optional().describe('Runtime resource requirements'),
+		readme: z.string().optional().describe('Readme content in markdown format'),
 	})
 	.describe('Information about a sandbox runtime');
 
@@ -67,8 +79,11 @@ export async function runtimeList(
 					name: r.name,
 					description: r.description,
 					iconUrl: r.iconUrl,
+					brandColor: r.brandColor,
 					url: r.url,
 					tags: r.tags,
+					requirements: r.requirements,
+					readme: r.readme,
 				})
 			),
 			total: resp.data.total,

package/src/api/sandbox/snapshot-build.ts

@@ -40,6 +40,10 @@ export const SnapshotBuildFileBaseSchema = z
 			.describe(
 				'User-defined metadata key-value pairs. Use ${VAR} syntax for build-time substitution via --metadata flag'
 			),
+		public: z
+			.boolean()
+			.optional()
+			.describe('Whether to make the snapshot publicly accessible (default: false)'),
 	})
 	.describe('Agentuity Snapshot Build File - defines a reproducible sandbox environment');
 

package/src/api/sandbox/snapshot.ts

@@ -6,6 +6,9 @@ const SnapshotFileInfoSchema = z
 	.object({
 		path: z.string().describe('File path within the snapshot'),
 		size: z.number().describe('File size in bytes'),
+		sha256: z.string().describe('SHA256 hash of the file contents'),
+		contentType: z.string().describe('MIME type of the file'),
+		mode: z.number().describe('Unix file mode/permissions (e.g., 0o644)'),
 	})
 	.describe('Information about a file in a snapshot');
 
@@ -22,6 +25,10 @@ const SnapshotInfoSchema = z
 			.describe(
 				'Display name for the snapshot (URL-safe: letters, numbers, underscores, dashes)'
 			),
+		fullName: z
+			.string()
+			.optional()
+			.describe('Full name with org slug for public snapshots (@slug/name:tag)'),
 		description: z.string().nullable().optional().describe('Description of the snapshot'),
 		tag: z.string().nullable().optional().describe('Tag for the snapshot (defaults to "latest")'),
 		sizeBytes: z.number().describe('Total size of the snapshot in bytes'),
@@ -31,6 +38,9 @@ const SnapshotInfoSchema = z
 			.nullable()
 			.optional()
 			.describe('ID of the parent snapshot (for incremental snapshots)'),
+		public: z.boolean().optional().describe('Whether the snapshot is publicly accessible'),
+		orgName: z.string().optional().describe('Organization name (for public snapshots)'),
+		orgSlug: z.string().optional().describe('Organization slug (for public snapshots)'),
 		createdAt: z.string().describe('ISO timestamp when the snapshot was created'),
 		downloadUrl: z.string().optional().describe('URL to download the snapshot archive'),
 		files: z
@@ -67,6 +77,10 @@ const _SnapshotCreateParamsSchema = z
 		name: z.string().optional().describe('Display name for the snapshot'),
 		description: z.string().optional().describe('Description of the snapshot'),
 		tag: z.string().optional().describe('Tag for the snapshot'),
+		public: z
+			.boolean()
+			.optional()
+			.describe('Whether to make the snapshot publicly accessible (default: false)'),
 		orgId: z.string().optional().describe('Organization ID'),
 	})
 	.describe('Parameters for creating a snapshot');
@@ -131,11 +145,11 @@ export async function snapshotCreate(
 	client: APIClient,
 	params: SnapshotCreateParams
 ): Promise<SnapshotInfo> {
-	const { sandboxId, name, description, tag, orgId } = params;
+	const { sandboxId, name, description, tag, public: isPublic, orgId } = params;
 	const queryString = buildQueryString({ orgId });
 	const url = `/sandbox/${API_VERSION}/${sandboxId}/snapshot${queryString}`;
 
-	const body: Record<string, string> = {};
+	const body: Record<string, string | boolean> = {};
 	if (name) {
 		body.name = name;
 	}
@@ -145,6 +159,9 @@ export async function snapshotCreate(
 	if (tag) {
 		body.tag = tag;
 	}
+	if (isPublic !== undefined) {
+		body.public = isPublic;
+	}
 
 	const resp = await client.post<z.infer<typeof SnapshotCreateResponseSchema>>(
 		url,
@@ -283,6 +300,10 @@ const _SnapshotBuildInitParamsSchema = z
 			.describe('SHA-256 hash of snapshot content for change detection'),
 		force: z.boolean().optional().describe('Force rebuild even if content is unchanged'),
 		encrypt: z.boolean().optional().describe('Request encryption for the snapshot archive'),
+		public: z
+			.boolean()
+			.optional()
+			.describe('Make snapshot public (enables virus scanning, disables encryption)'),
 		orgId: z.string().optional().describe('Organization ID'),
 	})
 	.describe('Parameters for initializing a snapshot build');
@@ -293,8 +314,7 @@ const SnapshotBuildInitResponseSchema = z
 		uploadUrl: z
 			.string()
 			.optional()
-			.describe('Pre-signed URL for uploading the snapshot archive'),
-		s3Key: z.string().optional().describe('S3 key where the snapshot will be stored'),
+			.describe('Pre-signed URL for uploading the snapshot archive (private snapshots only)'),
 		publicKey: z
 			.string()
 			.optional()
@@ -340,7 +360,8 @@ export async function snapshotBuildInit(
 	client: APIClient,
 	params: SnapshotBuildInitParams
 ): Promise<SnapshotBuildInitResponse> {
-	const { runtime, name, description, tag, contentHash, force, encrypt, orgId } = params;
+	const { runtime, name, description, tag, contentHash, force, encrypt, public: isPublic, orgId } =
+		params;
 	const queryString = buildQueryString({ orgId });
 	const url = `/sandbox/${API_VERSION}/snapshots/build${queryString}`;
 
@@ -351,6 +372,7 @@ export async function snapshotBuildInit(
 	if (contentHash) body.contentHash = contentHash;
 	if (force) body.force = force;
 	if (encrypt) body.encrypt = encrypt;
+	if (isPublic !== undefined) body.public = isPublic;
 
 	const resp = await client.post<z.infer<typeof SnapshotBuildInitAPIResponseSchema>>(
 		url,
@@ -402,3 +424,72 @@ export async function snapshotBuildFinalize(
 
 	throw new SandboxResponseError({ message: resp.message });
 }
+
+// ===== Snapshot Upload API (for public snapshots) =====
+
+const SnapshotUploadResponseSchema = z
+	.object({
+		success: z.boolean().describe('Whether the upload was successful'),
+		scanned: z.boolean().describe('Whether the upload was virus scanned'),
+		message: z.string().optional().describe('Optional message'),
+	})
+	.describe('Response from snapshot upload API');
+
+const _SnapshotUploadAPIResponseSchema = APIResponseSchema(SnapshotUploadResponseSchema);
+
+export type SnapshotUploadResponse = z.infer<typeof SnapshotUploadResponseSchema>;
+
+export interface SnapshotUploadParams {
+	snapshotId: string;
+	body: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | string | Blob;
+	contentLength: number;
+	orgId?: string;
+}
+
+/**
+ * Upload a public snapshot archive via Catalyst (with virus scanning).
+ * This should only be used when snapshotBuildInit returns no uploadUrl.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including snapshotId and the archive body
+ * @returns Upload result with scan status
+ * @throws {SandboxResponseError} If the upload fails or malware is detected
+ */
+export async function snapshotUpload(
+	client: APIClient,
+	params: SnapshotUploadParams
+): Promise<SnapshotUploadResponse> {
+	const { snapshotId, body, contentLength, orgId } = params;
+	const queryString = buildQueryString({ orgId });
+	const url = `/sandbox/${API_VERSION}/snapshots/${snapshotId}/upload${queryString}`;
+
+	const response = await client.rawPut(url, body, 'application/gzip', undefined, {
+		'Content-Length': String(contentLength),
+		Accept: 'application/json',
+	});
+
+	if (!response.ok) {
+		const text = await response.text();
+		let message = `Upload failed: ${response.status} ${response.statusText}`;
+		try {
+			const json = JSON.parse(text);
+			if (json.message) {
+				message = json.message;
+			} else if (json.error) {
+				message = typeof json.error === 'string' ? json.error : JSON.stringify(json.error);
+			}
+		} catch {
+			if (text) {
+				message = text;
+			}
+		}
+		throw new SandboxResponseError({ message });
+	}
+
+	const data = (await response.json()) as z.infer<typeof _SnapshotUploadAPIResponseSchema>;
+	if (data.success) {
+		return data.data;
+	}
+
+	throw new SandboxResponseError({ message: data.message });
+}