@agentuity/sandbox 3.0.12 → 3.1.1

package/src/runtime.ts

@@ -0,0 +1,106 @@
+import {
+	ListRuntimesParamsSchema,
+	type ListRuntimesResponse,
+	type SandboxRuntime,
+} from './types.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export 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');
+
+export 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');
+
+export const ListRuntimesDataSchema = z
+	.object({
+		runtimes: z.array(RuntimeInfoSchema).describe('List of runtime entries'),
+		total: z.number().describe('Total number of runtimes'),
+	})
+	.describe('List of sandbox runtimes');
+
+export const ListRuntimesResponseSchema = APIResponseSchema(ListRuntimesDataSchema);
+
+export const RuntimeListParamsSchema = ListRuntimesParamsSchema.extend({
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type RuntimeListParams = z.infer<typeof RuntimeListParamsSchema>;
+
+/**
+ * Lists available sandbox runtimes with optional pagination.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Optional parameters for pagination
+ * @returns List of runtimes with total count
+ * @throws {SandboxResponseError} If the request fails
+ */
+export async function runtimeList(
+	client: APIClient,
+	params?: RuntimeListParams
+): Promise<ListRuntimesResponse> {
+	const queryParams = new URLSearchParams();
+
+	if (params?.orgId) {
+		queryParams.set('orgId', params.orgId);
+	}
+	if (params?.limit !== undefined) {
+		queryParams.set('limit', params.limit.toString());
+	}
+	if (params?.offset !== undefined) {
+		queryParams.set('offset', params.offset.toString());
+	}
+	if (params?.sort) {
+		queryParams.set('sort', params.sort);
+	}
+	if (params?.direction) {
+		queryParams.set('direction', params.direction);
+	}
+
+	const queryString = queryParams.toString();
+	const url = `/sandbox/runtimes${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ListRuntimesResponseSchema>>(
+		url,
+		ListRuntimesResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			runtimes: resp.data.runtimes.map(
+				(r): SandboxRuntime => ({
+					id: r.id,
+					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,
+		};
+	}
+
+	throwSandboxError(resp, {});
+}

package/src/snapshot-build.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+
+/**
+ * Regex pattern for validating npm/bun package specifiers.
+ * Uses a blocklist approach: rejects shell injection characters while allowing
+ * all legitimate specifier formats (names, scoped packages, URLs, git refs, etc.).
+ *
+ * Valid examples: "typescript", "@types/node", "opencode-ai@1.2.3",
+ *   "https://github.com/user/repo", "git+https://github.com/user/repo.git",
+ *   "github:user/repo", "file:../local-pkg"
+ * Invalid examples: "foo bar", "pkg;rm -rf", "pkg|cat /etc/passwd", "$(evil)"
+ */
+export const NPM_PACKAGE_NAME_PATTERN = /^[^\s;`|$]+$/;
+
+/**
+ * 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'),
+		dir: z
+			.string()
+			.optional()
+			.describe(
+				'Subdirectory to use as the build context for file resolution (relative to the CLI directory argument)'
+			),
+		dependencies: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'List of apt packages to install. Supports version pinning: package=version or package=version* for prefix matching'
+			),
+		packages: z
+			.array(
+				z
+					.string()
+					.regex(
+						NPM_PACKAGE_NAME_PATTERN,
+						'Invalid npm/bun package specifier: must not contain whitespace, semicolons, backticks, pipes, or dollar signs'
+					)
+			)
+			.optional()
+			.describe(
+				'List of npm/bun packages to install globally via bun install -g. Example: opencode-ai, typescript'
+			),
+		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(
+			// biome-ignore lint/suspicious/noTemplateCurlyInString: describes the ${VAR} substitution syntax for users
+			'Environment variables to set. Use ${VAR} syntax for build-time substitution via --env flag'
+		),
+		metadata: z.record(z.string(), z.string()).optional().describe(
+			// biome-ignore lint/suspicious/noTemplateCurlyInString: describes the ${VAR} substitution syntax for users
+			'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');
+
+/**
+ * Schema with validation refinement - use this for parsing/validation.
+ * Ensures at least one of dependencies, files, env, or packages 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;
+		const hasPackages = data.packages && data.packages.length > 0;
+		return hasDependencies || hasFiles || hasEnv || hasPackages;
+	},
+	{
+		message: 'At least one of dependencies, files, env, or packages must be specified',
+	}
+);
+
+export type SnapshotBuildFile = z.infer<typeof SnapshotBuildFileSchema>;