@agentuity/sandbox 3.0.12 → 3.1.1

package/src/create.ts

@@ -0,0 +1,273 @@
+import type { SandboxCreateOptions } from './types.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { NPM_PACKAGE_NAME_PATTERN } from './snapshot-build.ts';
+import { throwSandboxError } from './util.ts';
+import { base64Encode } from './base64.ts';
+
+export 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'),
+		description: z.string().optional().describe('Optional sandbox description'),
+		resources: z
+			.object({
+				memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
+				cpu: z.string().optional().describe('CPU limit (e.g., "0.5", "1")'),
+				disk: z.string().optional().describe('Disk size limit (e.g., "1Gi", "10Gi")'),
+			})
+			.optional()
+			.describe('Resource constraints for the sandbox'),
+		env: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe('Environment variables to set in the sandbox'),
+		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'),
+		stream: z
+			.object({
+				stdout: z.string().optional().describe('Stream ID for stdout output'),
+				stderr: z.string().optional().describe('Stream ID for stderr output'),
+				stdin: z.string().optional().describe('Stream ID for stdin input'),
+				timestamps: z.boolean().optional().describe('Whether to include timestamps in output'),
+			})
+			.optional()
+			.describe('Stream configuration for I/O redirection'),
+		timeout: z
+			.object({
+				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h")'),
+				execution: z.string().optional().describe('Maximum execution time (e.g., "30m", "2h")'),
+				paused: z
+					.string()
+					.optional()
+					.describe(
+						'Maximum time sandbox can remain paused before termination (e.g., "24h", "0s" for infinite)'
+					),
+			})
+			.optional()
+			.describe('Timeout settings for the sandbox'),
+		command: z
+			.object({
+				exec: z.array(z.string()).describe('Command and arguments to execute'),
+				files: z
+					.array(
+						z.object({
+							path: z
+								.string()
+								.describe('Path to the file relative to the sandbox workspace'),
+							content: z.string().describe('Base64-encoded file content'),
+						})
+					)
+					.optional()
+					.describe('Files to write before execution (deprecated: use top-level files)'),
+				mode: z
+					.enum(['oneshot', 'interactive'])
+					.optional()
+					.describe('Execution mode: oneshot runs once, interactive keeps running'),
+			})
+			.optional()
+			.describe('Initial command to run in the sandbox'),
+		files: z
+			.array(
+				z.object({
+					path: z.string().describe('Path to the file relative to the sandbox workspace'),
+					content: z.string().describe('Base64-encoded file content'),
+				})
+			)
+			.optional()
+			.describe('Files to write to sandbox on creation'),
+		snapshot: z.string().optional().describe('Snapshot ID to restore the sandbox from'),
+		dependencies: z
+			.array(z.string())
+			.optional()
+			.describe('Apt packages to install when creating the sandbox'),
+		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('npm/bun packages to install globally when creating the sandbox'),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe('Optional user-defined metadata to associate with the sandbox'),
+		scopes: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'Permission scopes for automatic service access (e.g., "services:read", "services:write").'
+			),
+	})
+	.refine(
+		(data) => {
+			// If snapshot is provided, runtime and runtimeId must not be provided
+			if (data.snapshot) {
+				return !data.runtime && !data.runtimeId;
+			}
+			return true;
+		},
+		{
+			message: 'cannot specify both snapshot and runtime; snapshot includes its own runtime',
+			path: ['snapshot'],
+		}
+	)
+	.describe('Request body for creating a new sandbox');
+
+export const SandboxCreateDataSchema = z
+	.object({
+		sandboxId: z.string().describe('Unique identifier for the created sandbox'),
+		status: z
+			.enum([
+				'creating',
+				'idle',
+				'running',
+				'paused',
+				'stopping',
+				'suspended',
+				'terminated',
+				'failed',
+			])
+			.describe('Current status of the sandbox'),
+		executionId: z
+			.string()
+			.optional()
+			.describe('Initial execution identifier for oneshot sandbox creation'),
+		url: z
+			.string()
+			.optional()
+			.describe('Public URL for the sandbox (only set when a network port is configured)'),
+		stdoutStreamId: z.string().optional().describe('Stream ID for reading stdout'),
+		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
+		stderrStreamId: z.string().optional().describe('Stream ID for reading stderr'),
+		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+		auditStreamId: z.string().optional().describe('Stream ID for reading audit events'),
+		auditStreamUrl: z.string().optional().describe('URL for streaming audit events'),
+	})
+	.describe('Response data from sandbox creation');
+
+export const SandboxCreateResponseSchema = APIResponseSchema(SandboxCreateDataSchema);
+
+export type SandboxCreateResponse = z.infer<typeof SandboxCreateDataSchema>;
+
+export const SandboxCreateParamsSchema = z.object({
+	options: z.custom<SandboxCreateOptions>().optional().describe('Optional sandbox create options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type SandboxCreateParams = z.infer<typeof SandboxCreateParamsSchema>;
+
+/**
+ * Creates a new sandbox instance.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters for creating the sandbox
+ * @returns The created sandbox response including sandbox ID and stream URLs
+ * @throws {SandboxResponseError} If the sandbox creation fails
+ */
+export async function sandboxCreate(
+	client: APIClient,
+	params: SandboxCreateParams = {}
+): Promise<SandboxCreateResponse> {
+	const { options = {}, orgId } = params;
+	const body: z.infer<typeof SandboxCreateRequestSchema> = {};
+
+	if (options.projectId) {
+		body.projectId = options.projectId;
+	}
+	if (options.runtime) {
+		body.runtime = options.runtime;
+	}
+	if (options.runtimeId) {
+		body.runtimeId = options.runtimeId;
+	}
+	if (options.name) {
+		body.name = options.name;
+	}
+	if (options.description) {
+		body.description = options.description;
+	}
+	if (options.resources) {
+		body.resources = options.resources;
+	}
+	if (options.env) {
+		body.env = options.env;
+	}
+	if (options.network) {
+		body.network = options.network;
+	}
+	if (options.stream) {
+		body.stream = options.stream;
+	}
+	if (options.timeout) {
+		body.timeout = options.timeout;
+	}
+	if (options.command) {
+		body.command = {
+			exec: options.command.exec,
+			mode: options.command.mode,
+			files: options.command.files?.map((f) => ({
+				path: f.path,
+				content: base64Encode(f.content),
+			})),
+		};
+	}
+	if (options.files && options.files.length > 0) {
+		body.files = options.files.map((f) => ({
+			path: f.path,
+			content: base64Encode(f.content),
+		}));
+	}
+	if (options.snapshot) {
+		body.snapshot = options.snapshot;
+	}
+	if (options.dependencies && options.dependencies.length > 0) {
+		body.dependencies = options.dependencies;
+	}
+	if (options.packages && options.packages.length > 0) {
+		body.packages = options.packages;
+	}
+	if (options.metadata) {
+		body.metadata = options.metadata;
+	}
+	if (options.scopes && options.scopes.length > 0) {
+		body.scopes = options.scopes;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof SandboxCreateResponseSchema>>(
+		url,
+		body,
+		SandboxCreateResponseSchema,
+		SandboxCreateRequestSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, {});
+}

package/src/destroy.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchemaNoData } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export const DestroyResponseSchema = APIResponseSchemaNoData();
+
+export const SandboxDestroyParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID to destroy'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type SandboxDestroyParams = z.infer<typeof SandboxDestroyParamsSchema>;
+
+/**
+ * Destroys a sandbox and releases all associated resources.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to destroy
+ * @throws {SandboxResponseError} If the sandbox is not found or destruction fails
+ */
+export async function sandboxDestroy(
+	client: APIClient,
+	params: SandboxDestroyParams
+): Promise<void> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof DestroyResponseSchema>>(
+		url,
+		DestroyResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/disk-checkpoint.ts

@@ -0,0 +1,184 @@
+import type { z as zType } from 'zod';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+// --- Schemas ---
+
+export const DiskCheckpointInfoSchema = z.object({
+	id: z.string().describe('Globally unique checkpoint ID (ckpt_xxx)'),
+	name: z.string().describe('User-provided checkpoint name'),
+	createdAt: z.string().describe('ISO timestamp of creation'),
+	parent: z.string().describe('Parent checkpoint name (empty for base)'),
+});
+
+export type DiskCheckpointInfo = z.infer<typeof DiskCheckpointInfoSchema>;
+
+const CreateDiskCheckpointDataSchema = DiskCheckpointInfoSchema;
+export const CreateDiskCheckpointResponseSchema = APIResponseSchema(CreateDiskCheckpointDataSchema);
+
+const ListDiskCheckpointsDataSchema = z.object({
+	checkpoints: z.array(DiskCheckpointInfoSchema),
+});
+export const ListDiskCheckpointsResponseSchema = APIResponseSchema(ListDiskCheckpointsDataSchema);
+
+export const RestoreDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+export const DeleteDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+
+// --- Params ---
+
+export const DiskCheckpointCreateParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID for checkpoint creation'),
+	name: z.string().describe('Name to assign to the new checkpoint'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export const DiskCheckpointListParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID to list checkpoints for'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export const DiskCheckpointRestoreParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID to restore'),
+	checkpointId: z.string().describe('Checkpoint ID to restore from'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export const DiskCheckpointDeleteParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID containing the checkpoint'),
+	checkpointId: z.string().describe('Checkpoint ID to delete'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type DiskCheckpointCreateParams = z.infer<typeof DiskCheckpointCreateParamsSchema>;
+export type DiskCheckpointListParams = z.infer<typeof DiskCheckpointListParamsSchema>;
+export type DiskCheckpointRestoreParams = z.infer<typeof DiskCheckpointRestoreParamsSchema>;
+export type DiskCheckpointDeleteParams = z.infer<typeof DiskCheckpointDeleteParamsSchema>;
+
+// --- API Functions ---
+
+/**
+ * Creates a new disk checkpoint for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint name
+ * @throws {SandboxResponseError} If the sandbox is not found or checkpoint creation fails
+ */
+export async function diskCheckpointCreate(
+	client: APIClient,
+	params: DiskCheckpointCreateParams
+): Promise<DiskCheckpointInfo> {
+	const { sandboxId, name, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof CreateDiskCheckpointResponseSchema>>(
+		url,
+		{ name },
+		CreateDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Lists all disk checkpoints for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID
+ * @throws {SandboxResponseError} If the sandbox is not found or listing fails
+ */
+export async function diskCheckpointList(
+	client: APIClient,
+	params: DiskCheckpointListParams
+): Promise<DiskCheckpointInfo[]> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/checkpoints/${encodeURIComponent(sandboxId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<zType.infer<typeof ListDiskCheckpointsResponseSchema>>(
+		url,
+		ListDiskCheckpointsResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data.checkpoints;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Restores a sandbox to a specific disk checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or restore fails
+ */
+export async function diskCheckpointRestore(
+	client: APIClient,
+	params: DiskCheckpointRestoreParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}/restore${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof RestoreDiskCheckpointResponseSchema>>(
+		url,
+		undefined,
+		RestoreDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Deletes a disk checkpoint from a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or deletion fails
+ */
+export async function diskCheckpointDelete(
+	client: APIClient,
+	params: DiskCheckpointDeleteParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<zType.infer<typeof DeleteDiskCheckpointResponseSchema>>(
+		url,
+		DeleteDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/events.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { SortDirectionSchema } from '@agentuity/client';
+import { throwSandboxError } from './util.ts';
+
+export const SandboxEventInfoSchema = z
+	.object({
+		eventId: z.string().describe('Unique identifier for the event'),
+		sandboxId: z.string().describe('ID of the sandbox this event belongs to'),
+		type: z.string().describe('Type of event (e.g., create, destroy, lifecycle:started)'),
+		event: z.record(z.string(), z.unknown()).describe('Event data payload'),
+		createdAt: z.string().describe('ISO timestamp when the event was recorded'),
+	})
+	.describe('Information about a sandbox event');
+
+export const SandboxEventListDataSchema = z
+	.object({
+		events: z.array(SandboxEventInfoSchema).describe('List of sandbox events'),
+	})
+	.describe('List of events for a sandbox');
+
+export const SandboxEventListResponseSchema = APIResponseSchema(SandboxEventListDataSchema);
+
+export type SandboxEventInfo = z.infer<typeof SandboxEventInfoSchema>;
+
+export const SandboxEventListParamsSchema = z.object({
+	sandboxId: z.string().describe('sandbox id'),
+	orgId: z.string().optional().describe('organization id'),
+	limit: z.number().optional().describe('limit'),
+	direction: SortDirectionSchema.optional().describe('sort direction (default: asc)'),
+});
+export type SandboxEventListParams = z.infer<typeof SandboxEventListParamsSchema>;
+
+export type SandboxEventListResponse = z.infer<typeof SandboxEventListDataSchema>;
+
+/**
+ * Lists all events for a specific sandbox, ordered by creation time (oldest first by default).
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID, optional limit, and sort direction
+ * @returns List of event information for the sandbox
+ * @throws {SandboxResponseError} If the sandbox is not found or request fails
+ */
+export async function sandboxEventList(
+	client: APIClient,
+	params: SandboxEventListParams
+): Promise<SandboxEventListResponse> {
+	const { sandboxId, orgId, limit, direction } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (limit !== undefined) {
+		queryParams.set('limit', String(limit));
+	}
+	if (direction) {
+		queryParams.set('direction', direction);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/events${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof SandboxEventListResponseSchema>>(
+		url,
+		SandboxEventListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}