@agentuity/server 0.1.10 → 0.1.12

package/dist/api/session/get.js

@@ -12,7 +12,7 @@ const EvalRunSchema = z.object({
     pending: z.boolean().describe('pending status'),
     success: z.boolean().describe('success status'),
     error: z.string().nullable().describe('error message'),
-    result: z.string().nullable().describe('result JSON'),
+    result: z.record(z.string(), z.unknown()).nullable().describe('result object'),
 });
 const SpanNodeSchema = z.lazy(() => z.object({
     id: z.string().describe('span ID'),

package/dist/api/session/get.js.map

@@ -1 +1 @@
-{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/api/session/get.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/api/session/get.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAa,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAE9C,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;CACzC,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACrD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IACtD,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;CAC9E,CAAC,CAAC;AAWH,MAAM,cAAc,GAAwB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACvD,CAAC,CAAC,MAAM,CAAC;IACR,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IACzD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAChD,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACzE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IACpE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;CACtD,CAAC,CACF,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC;KACvB,MAAM,CAAC;IACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;CACvC,CAAC;KACD,QAAQ,EAAE,CAAC;AAEb,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;CACnD,CAAC,CAAC;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAC5D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACxE,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CACpD,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAAG,iBAAiB,CAAC,yBAAyB,CAAC,CAAC;AAyB9E,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,MAAiB,EACjB,OAA0B;IAE1B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAChC,KAAK,EACL,uBAAuB,OAAO,CAAC,EAAE,EAAE,EACnC,wBAAwB,CACxB,CAAC;IAEF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO;YACN,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO;YAC1B,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACxB,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS;YAC7B,QAAQ,EAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAqB,IAAI,IAAI;YAC1D,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;SACtB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,oBAAoB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/config.js

@@ -26,7 +26,7 @@ export function getServiceUrls(region) {
     };
 }
 function getDomainSuffix(region) {
-    if (region === 'local') {
+    if (region === 'local' || region === 'l') {
         return 'agentuity.io';
     }
     return 'agentuity.cloud';

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC5C,MAAM,QAAQ,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACxD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACd,mHAAmH,CACnH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC7C,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,YAAY,GACjB,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,gBAAgB,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAErF,OAAO;QACN,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,YAAY;QAC5D,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,gBAAgB,CAAC,cAAc,EAAE,SAAS,CAAC;QACvF,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,YAAY;QACxD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,YAAY;QAC5D,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC;QAChF,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,YAAY;KAC1D,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,MAAe;IACvC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACxB,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAe,EAAE,QAAiB;IAC3D,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC/B,OAAO,WAAW,QAAQ,IAAI,MAAM,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,WAAW,QAAQ,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;AAClD,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC5C,MAAM,QAAQ,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACxD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACd,mHAAmH,CACnH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC7C,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,YAAY,GACjB,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,gBAAgB,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAErF,OAAO;QACN,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,YAAY;QAC5D,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,gBAAgB,CAAC,cAAc,EAAE,SAAS,CAAC;QACvF,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,YAAY;QACxD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,YAAY;QAC5D,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC;QAChF,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,YAAY;KAC1D,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,MAAe;IACvC,IAAI,MAAM,KAAK,OAAO,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QAC1C,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAe,EAAE,QAAiB;IAC3D,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC/B,OAAO,WAAW,QAAQ,IAAI,MAAM,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,WAAW,QAAQ,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;AAClD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/server",
-	"version": "0.1.10",
+	"version": "0.1.12",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -25,12 +25,12 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.1.10",
-		"@agentuity/schema": "0.1.10",
+		"@agentuity/core": "0.1.12",
+		"@agentuity/schema": "0.1.12",
 		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "0.1.10",
+		"@agentuity/test-utils": "0.1.12",
 		"@types/bun": "latest",
 		"@types/node": "^22.0.0",
 		"bun-types": "latest",

package/src/api/org/resources.ts

@@ -13,6 +13,7 @@ const OrgS3Resource = z.object({
 
 const OrgDBResource = z.object({
 	name: z.string().describe('the database name'),
+	description: z.string().nullable().optional().describe('optional description of the database'),
 	username: z.string().nullable().optional().describe('the database username'),
 	password: z.string().nullable().optional().describe('the database password'),
 	url: z.string().nullable().optional().describe('the full database connection URL'),

package/src/api/project/deploy.ts

@@ -302,7 +302,9 @@ export async function projectDeploymentComplete(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new ProjectResponseError({ message: resp.message });
+	throw new ProjectResponseError({
+		message: resp.message || 'Deployment completion failed with unknown error',
+	});
 }
 
 /**

package/src/api/region/create.ts

@@ -2,9 +2,122 @@ import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
 import { RegionResponseError } from './util';
 
+/**
+ * Database name validation regex - must match catalyst server validation:
+ * - Must start with a letter or underscore
+ * - Can contain only lowercase letters, digits, and underscores
+ * - Must be lowercase
+ */
+const DATABASE_NAME_REGEX = /^[a-z_][a-z0-9_]*$/;
+const MAX_DATABASE_NAME_LENGTH = 63;
+const MIN_DATABASE_NAME_LENGTH = 1;
+
+/**
+ * S3 bucket name validation - must match catalyst server validation (AWS S3 rules):
+ * - Length [3, 63]
+ * - Only lowercase, numbers, dots, hyphens
+ * - No adjacent periods
+ * - Starts with lowercase or number
+ * - Ends with lowercase or number
+ * - No xn-- prefix
+ * - No -s3alias suffix
+ * - Not an IP address
+ */
+const BUCKET_NAME_REGEX = /^[a-z0-9.-]+$/;
+const MAX_BUCKET_NAME_LENGTH = 63;
+const MIN_BUCKET_NAME_LENGTH = 3;
+const IPV4_REGEX = /^(\d{1,3}\.){3}\d{1,3}$/;
+
+/**
+ * Validates a database name for PostgreSQL compatibility.
+ * Matches the server-side validation in catalyst.
+ */
+export function validateDatabaseName(name: string): { valid: boolean; error?: string } {
+	if (name.length < MIN_DATABASE_NAME_LENGTH) {
+		return { valid: false, error: 'database name is too short (minimum 1 character)' };
+	}
+	if (name.length > MAX_DATABASE_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `database name is too long (maximum ${MAX_DATABASE_NAME_LENGTH} characters)`,
+		};
+	}
+	if (name !== name.toLowerCase()) {
+		return { valid: false, error: 'database name must be lowercase' };
+	}
+	if (!DATABASE_NAME_REGEX.test(name)) {
+		return {
+			valid: false,
+			error: 'database name must start with a letter or underscore and contain only lowercase letters, digits, and underscores',
+		};
+	}
+	return { valid: true };
+}
+
+/**
+ * Validates an S3 bucket name according to AWS S3 naming rules.
+ * Matches the server-side validation in catalyst.
+ */
+export function validateBucketName(name: string): { valid: boolean; error?: string } {
+	if (name.length < MIN_BUCKET_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `bucket name is too short (minimum ${MIN_BUCKET_NAME_LENGTH} characters)`,
+		};
+	}
+	if (name.length > MAX_BUCKET_NAME_LENGTH) {
+		return {
+			valid: false,
+			error: `bucket name is too long (maximum ${MAX_BUCKET_NAME_LENGTH} characters)`,
+		};
+	}
+	if (!BUCKET_NAME_REGEX.test(name)) {
+		return {
+			valid: false,
+			error: 'bucket name can only contain lowercase letters, numbers, dots, and hyphens',
+		};
+	}
+	if (name.includes('..')) {
+		return { valid: false, error: 'bucket name cannot contain adjacent periods' };
+	}
+	const firstChar = name[0];
+	if (!((firstChar >= 'a' && firstChar <= 'z') || (firstChar >= '0' && firstChar <= '9'))) {
+		return { valid: false, error: 'bucket name must start with a lowercase letter or number' };
+	}
+	const lastChar = name[name.length - 1];
+	if (!((lastChar >= 'a' && lastChar <= 'z') || (lastChar >= '0' && lastChar <= '9'))) {
+		return { valid: false, error: 'bucket name must end with a lowercase letter or number' };
+	}
+	if (name.startsWith('xn--')) {
+		return { valid: false, error: 'bucket name cannot start with xn--' };
+	}
+	if (name.endsWith('-s3alias')) {
+		return { valid: false, error: 'bucket name cannot end with -s3alias' };
+	}
+	if (isIPv4Address(name)) {
+		return { valid: false, error: 'bucket name cannot be an IP address' };
+	}
+	return { valid: true };
+}
+
+function isIPv4Address(s: string): boolean {
+	if (!IPV4_REGEX.test(s)) {
+		return false;
+	}
+	const parts = s.split('.');
+	for (const part of parts) {
+		const num = parseInt(part, 10);
+		if (isNaN(num) || num < 0 || num > 255) {
+			return false;
+		}
+	}
+	return true;
+}
+
 const ResourceSpec = z.object({
 	type: z.enum(['db', 's3']).describe('the resource type'),
 	name: z.string().optional().describe('optional custom name for db'),
+	description: z.string().optional().describe('optional description for db'),
 });
 
 const CreateResourcesRequest = z.object({
@@ -41,8 +154,24 @@ export async function createResources(
 	client: APIClient,
 	orgId: string,
 	region: string,
-	resources: Array<{ type: 'db' | 's3'; name?: string }>
+	resources: Array<{ type: 'db' | 's3'; name?: string; description?: string }>
 ): Promise<CreatedResource[]> {
+	// Validate resource names before sending to server
+	for (const resource of resources) {
+		if (resource.type === 'db' && resource.name) {
+			const validation = validateDatabaseName(resource.name);
+			if (!validation.valid) {
+				throw new RegionResponseError({ message: validation.error! });
+			}
+		}
+		if (resource.type === 's3' && resource.name) {
+			const validation = validateBucketName(resource.name);
+			if (!validation.valid) {
+				throw new RegionResponseError({ message: validation.error! });
+			}
+		}
+	}
+
 	const resp = await client.request<CreateResourcesResponse, CreateResourcesRequest>(
 		'POST',
 		`/resource/2025-11-16/${orgId}/${region}`,

package/src/api/sandbox/create.ts

@@ -5,6 +5,7 @@ import type { SandboxCreateOptions, SandboxStatus } from '@agentuity/core';
 
 const SandboxCreateRequestSchema = z
 	.object({
+		projectId: z.string().optional().describe('Project ID to associate the sandbox with'),
 		runtime: z.string().optional().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
 		runtimeId: z.string().optional().describe('Runtime ID (e.g., "srt_xxx")'),
 		name: z.string().optional().describe('Optional sandbox name'),
@@ -24,6 +25,13 @@ const SandboxCreateRequestSchema = z
 		network: z
 			.object({
 				enabled: z.boolean().optional().describe('Whether network access is enabled'),
+				port: z
+					.number()
+					.int()
+					.min(1024)
+					.max(65535)
+					.optional()
+					.describe('Port to expose from the sandbox (1024-65535)'),
 			})
 			.optional()
 			.describe('Network configuration for the sandbox'),
@@ -120,6 +128,9 @@ export async function sandboxCreate(
 	const { options = {}, orgId } = params;
 	const body: z.infer<typeof SandboxCreateRequestSchema> = {};
 
+	if (options.projectId) {
+		body.projectId = options.projectId;
+	}
 	if (options.runtime) {
 		body.runtime = options.runtime;
 	}

package/src/api/sandbox/files.ts

@@ -118,12 +118,14 @@ export async function sandboxReadFile(
 	const url = `/fs/${API_VERSION}/${sandboxId}?${queryString}`;
 
 	const response = await client.rawGet(url, signal);
+	const sessionId = response.headers.get('x-session-id');
 
 	if (!response.ok) {
 		const text = await response.text().catch(() => 'Unknown error');
 		throw new SandboxResponseError({
 			message: `Failed to read file: ${response.status} ${text}`,
 			sandboxId,
+			sessionId,
 		});
 	}
 
@@ -131,6 +133,7 @@ export async function sandboxReadFile(
 		throw new SandboxResponseError({
 			message: 'No response body',
 			sandboxId,
+			sessionId,
 		});
 	}
 
@@ -433,12 +436,14 @@ export async function sandboxDownloadArchive(
 	const url = `/fs/${API_VERSION}/download/${sandboxId}${queryString ? `?${queryString}` : ''}`;
 
 	const response = await client.rawGet(url, signal);
+	const sessionId = response.headers.get('x-session-id');
 
 	if (!response.ok) {
 		const text = await response.text().catch(() => 'Unknown error');
 		throw new SandboxResponseError({
 			message: `Failed to download archive: ${response.status} ${text}`,
 			sandboxId,
+			sessionId,
 		});
 	}
 
@@ -446,6 +451,7 @@ export async function sandboxDownloadArchive(
 		throw new SandboxResponseError({
 			message: 'No response body',
 			sandboxId,
+			sessionId,
 		});
 	}
 
@@ -498,12 +504,14 @@ export async function sandboxUploadArchive(
 	const url = `/fs/${API_VERSION}/upload/${sandboxId}${queryString ? `?${queryString}` : ''}`;
 
 	const response = await client.rawPost(url, archive, 'application/octet-stream', signal);
+	const sessionId = response.headers.get('x-session-id');
 
 	if (!response.ok) {
 		const text = await response.text().catch(() => 'Unknown error');
 		throw new SandboxResponseError({
 			message: `Failed to upload archive: ${response.status} ${text}`,
 			sandboxId,
+			sessionId,
 		});
 	}
 
@@ -511,7 +519,7 @@ export async function sandboxUploadArchive(
 	const result = UploadArchiveResponseSchema.parse(body);
 
 	if (!result.success) {
-		throw new SandboxResponseError({ message: result.message, sandboxId });
+		throw new SandboxResponseError({ message: result.message, sandboxId, sessionId });
 	}
 }
 

package/src/api/sandbox/get.ts

@@ -43,6 +43,7 @@ const SandboxOrgInfoSchema = z
 const SandboxInfoDataSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
+		identifier: z.string().optional().describe('Short identifier for DNS hostname'),
 		name: z.string().optional().describe('Sandbox name'),
 		description: z.string().optional().describe('Sandbox description'),
 		status: z
@@ -72,6 +73,11 @@ const SandboxInfoDataSchema = z
 		memoryByteSec: z.number().optional().describe('Total memory usage in byte-seconds'),
 		networkEgressBytes: z.number().optional().describe('Total network egress in bytes'),
 		networkEnabled: z.boolean().optional().describe('Whether network access is enabled'),
+		networkPort: z.number().optional().describe('Network port exposed from the sandbox'),
+		url: z
+			.string()
+			.optional()
+			.describe('Public URL for the sandbox (only set if networkPort is configured)'),
 		user: SandboxUserInfoSchema.optional().describe('User who created the sandbox'),
 		agent: SandboxAgentInfoSchema.optional().describe('Agent associated with the sandbox'),
 		project: SandboxProjectInfoSchema.optional().describe('Project associated with the sandbox'),

package/src/api/sandbox/index.ts

@@ -49,7 +49,15 @@ export type {
 	SetEnvParams,
 	SetEnvResult,
 } from './files';
-export { snapshotCreate, snapshotGet, snapshotList, snapshotDelete, snapshotTag } from './snapshot';
+export {
+	snapshotCreate,
+	snapshotGet,
+	snapshotList,
+	snapshotDelete,
+	snapshotTag,
+	snapshotBuildInit,
+	snapshotBuildFinalize,
+} from './snapshot';
 export type {
 	SnapshotInfo,
 	SnapshotFileInfo,
@@ -59,4 +67,9 @@ export type {
 	SnapshotListResponse,
 	SnapshotDeleteParams,
 	SnapshotTagParams,
+	SnapshotBuildInitParams,
+	SnapshotBuildInitResponse,
+	SnapshotBuildFinalizeParams,
 } from './snapshot';
+export { SnapshotBuildFileSchema } from './snapshot-build';
+export type { SnapshotBuildFile } from './snapshot-build';

package/src/api/sandbox/list.ts

@@ -13,6 +13,7 @@ const SandboxOrgInfoSchema = z
 const SandboxInfoSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
+		identifier: z.string().optional().describe('Short identifier for DNS hostname'),
 		name: z.string().optional().describe('Sandbox name'),
 		description: z.string().optional().describe('Sandbox description'),
 		status: z
@@ -30,6 +31,11 @@ const SandboxInfoSchema = z
 		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
 		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
 		networkEnabled: z.boolean().optional().describe('Whether network access is enabled'),
+		networkPort: z.number().optional().describe('Network port exposed from the sandbox'),
+		url: z
+			.string()
+			.optional()
+			.describe('Public URL for the sandbox (only set if networkPort is configured)'),
 		org: SandboxOrgInfoSchema.describe('Organization associated with the sandbox'),
 	})
 	.describe('Summary information about a sandbox');
@@ -74,6 +80,9 @@ export async function sandboxList(
 	if (params?.status) {
 		queryParams.set('status', params.status);
 	}
+	if (params?.live !== undefined) {
+		queryParams.set('live', params.live.toString());
+	}
 	if (params?.limit !== undefined) {
 		queryParams.set('limit', params.limit.toString());
 	}

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

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+
+/**
+ * Base schema for snapshot build configuration file (agentuity-snapshot.yaml)
+ * This is the canonical schema - used for JSON Schema generation.
+ */
+export const SnapshotBuildFileBaseSchema = z
+	.object({
+		version: z.literal(1).describe('Schema version, must be 1'),
+		runtime: z
+			.string()
+			.describe('Runtime identifier (name:tag format, e.g., bun:1, node:20, python:3.12)'),
+		name: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]+$/)
+			.optional()
+			.describe('Snapshot name (alphanumeric, underscores, dashes only)'),
+		description: z.string().optional().describe('Human-readable description of the snapshot'),
+		dependencies: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'List of apt packages to install. Supports version pinning: package=version or package=version* for prefix matching'
+			),
+		files: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'Glob patterns for files to include from the build context. Supports negative patterns with ! prefix for exclusions'
+			),
+		env: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe(
+				'Environment variables to set. Use ${VAR} syntax for build-time substitution via --env flag'
+			),
+		metadata: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe(
+				'User-defined metadata key-value pairs. Use ${VAR} syntax for build-time substitution via --metadata flag'
+			),
+	})
+	.describe('Agentuity Snapshot Build File - defines a reproducible sandbox environment');
+
+/**
+ * Schema with validation refinement - use this for parsing/validation.
+ * Ensures at least one of dependencies, files, or env is specified.
+ */
+export const SnapshotBuildFileSchema = SnapshotBuildFileBaseSchema.refine(
+	(data) => {
+		const hasDependencies = data.dependencies && data.dependencies.length > 0;
+		const hasFiles = data.files && data.files.length > 0;
+		const hasEnv = data.env && Object.keys(data.env).length > 0;
+		return hasDependencies || hasFiles || hasEnv;
+	},
+	{
+		message: 'At least one of dependencies, files, or env must be specified',
+	}
+);
+
+export type SnapshotBuildFile = z.infer<typeof SnapshotBuildFileSchema>;