@agentuity/sandbox 3.0.12 → 3.1.1

package/src/job.ts

@@ -0,0 +1,161 @@
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { CreateJobOptionsSchema, JobSchema, type Job } from './types.ts';
+import { throwSandboxError } from './util.ts';
+import { z } from 'zod';
+
+export const CreateJobRequestSchema = CreateJobOptionsSchema;
+
+export const CreateJobDataSchema = JobSchema;
+
+export const CreateJobResponseSchema = APIResponseSchema(CreateJobDataSchema);
+
+export const JobCreateParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID where the job should run'),
+	options: CreateJobOptionsSchema.describe('Job creation options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	signal: z.custom<AbortSignal>().optional().describe('Optional abort signal for cancellation'),
+});
+export type JobCreateParams = z.infer<typeof JobCreateParamsSchema>;
+
+export async function jobCreate(client: APIClient, params: JobCreateParams): Promise<Job> {
+	const { sandboxId, options, orgId, signal } = params;
+	const body: z.infer<typeof CreateJobRequestSchema> = {
+		command: options.command,
+	};
+	if (options.streams) {
+		body.streams = options.streams;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof CreateJobResponseSchema>>(
+		url,
+		body,
+		CreateJobResponseSchema,
+		CreateJobRequestSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobGetDataSchema = JobSchema;
+
+export const JobGetResponseSchema = APIResponseSchema(JobGetDataSchema);
+
+export const JobGetParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobGetParams = z.infer<typeof JobGetParamsSchema>;
+
+export async function jobGet(client: APIClient, params: JobGetParams): Promise<Job> {
+	const { sandboxId, jobId, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobGetResponseSchema>>(
+		url,
+		JobGetResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}
+
+export const JobListDataSchema = z.object({
+	jobs: z.array(JobSchema).describe('List of jobs'),
+});
+export type JobListResponse = z.infer<typeof JobListDataSchema>;
+
+export const JobListResponseSchema = APIResponseSchema(JobListDataSchema);
+
+export const JobListParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	limit: z.number().optional().describe('Maximum number of results'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobListParams = z.infer<typeof JobListParamsSchema>;
+
+export async function jobList(client: APIClient, params: JobListParams): Promise<JobListResponse> {
+	const { sandboxId, orgId, limit, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (limit !== undefined) {
+		queryParams.set('limit', String(limit));
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobListResponseSchema>>(
+		url,
+		JobListResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobStopDataSchema = JobSchema;
+
+export const JobStopResponseSchema = APIResponseSchema(JobStopDataSchema);
+
+export const JobStopParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	force: z.boolean().optional().describe('Force termination (SIGKILL)'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobStopParams = z.infer<typeof JobStopParamsSchema>;
+
+export async function jobStop(client: APIClient, params: JobStopParams): Promise<Job> {
+	const { sandboxId, jobId, force, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (force) {
+		queryParams.set('force', 'true');
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof JobStopResponseSchema>>(
+		url,
+		JobStopResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}

package/src/list.ts

@@ -0,0 +1,239 @@
+import type {
+	ListSandboxesResponse,
+	SandboxRuntimeInfo,
+	SandboxSnapshotInfo,
+	SandboxStatus,
+} from './types.ts';
+import { ListSandboxesParamsSchema } from './types.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export const SandboxOrgInfoSchema = z
+	.object({
+		id: z.string().describe('Organization ID'),
+		name: z.string().describe('Organization name'),
+	})
+	.describe('Organization associated with the sandbox');
+
+export const SandboxRuntimeInfoSchema = z
+	.object({
+		id: z.string().describe('Runtime ID'),
+		name: z.string().describe('Runtime name (e.g., "bun:1")'),
+		iconUrl: z.string().optional().describe('URL for runtime icon'),
+		brandColor: z.string().optional().describe('Brand color for the runtime (hex color code)'),
+		tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
+	})
+	.describe('Runtime information');
+
+export const SandboxSnapshotUserInfoSchema = z
+	.object({
+		id: z.string().describe('User ID'),
+		firstName: z.string().optional().describe("User's first name"),
+		lastName: z.string().optional().describe("User's last name"),
+	})
+	.describe('Snapshot user information');
+
+export const SandboxSnapshotOrgInfoSchema = z
+	.object({
+		id: z.string().describe('Organization ID'),
+		name: z.string().describe('Organization name'),
+		slug: z.string().optional().describe('Organization slug'),
+	})
+	.describe('Snapshot organization information');
+
+export const SandboxSnapshotInfoSchema = z
+	.union([
+		z
+			.object({
+				id: z.string().describe('Snapshot ID'),
+				name: z.string().optional().describe('Snapshot name'),
+				tag: z.string().optional().describe('Snapshot tag'),
+				fullName: z.string().optional().describe('Full name with org slug (@slug/name:tag)'),
+				public: z.literal(true).describe('Public snapshot'),
+				org: SandboxSnapshotOrgInfoSchema.describe(
+					'Organization that owns the public snapshot'
+				),
+			})
+			.describe('Public snapshot'),
+		z
+			.object({
+				id: z.string().describe('Snapshot ID'),
+				name: z.string().optional().describe('Snapshot name'),
+				tag: z.string().optional().describe('Snapshot tag'),
+				fullName: z.string().optional().describe('Full name with org slug (@slug/name:tag)'),
+				public: z.literal(false).describe('Private snapshot'),
+				user: SandboxSnapshotUserInfoSchema.describe('User who created the private snapshot'),
+			})
+			.describe('Private snapshot'),
+	])
+	.describe('Snapshot information (discriminated union)');
+
+export 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
+			.enum([
+				'creating',
+				'idle',
+				'running',
+				'paused',
+				'stopping',
+				'suspended',
+				'terminated',
+				'failed',
+				'deleted',
+			])
+			.describe('Current status of the sandbox'),
+		mode: z.string().optional().describe('Sandbox mode (interactive or oneshot)'),
+		createdAt: z.string().describe('ISO timestamp when the sandbox was created'),
+		region: z.string().optional().describe('Region where the sandbox is running'),
+		runtime: SandboxRuntimeInfoSchema.optional().describe('Runtime information'),
+		snapshot: SandboxSnapshotInfoSchema.optional().describe('Snapshot information'),
+		executions: z.number().describe('Total number of executions in this sandbox'),
+		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
+		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+		auditStreamId: z.string().optional().describe('ID of the audit event stream'),
+		auditStreamUrl: z.string().optional().describe('URL for streaming audit events'),
+		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'),
+		timeout: z
+			.object({
+				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h").'),
+				execution: z
+					.string()
+					.optional()
+					.describe('Execution timeout duration (e.g., "30m", "2h").'),
+				paused: z
+					.string()
+					.optional()
+					.describe('Paused timeout duration (e.g., "24h", "0s" for infinite).'),
+			})
+			.optional()
+			.describe('Timeout configuration for the sandbox.'),
+		command: z
+			.object({
+				exec: z.array(z.string()).describe('Command and arguments to execute.'),
+				mode: z
+					.enum(['oneshot', 'interactive'])
+					.optional()
+					.describe('Execution mode for the command.'),
+			})
+			.optional()
+			.describe('Command configuration for the sandbox.'),
+	})
+	.describe('Summary information about a sandbox');
+
+export const ListSandboxesDataSchema = z
+	.object({
+		sandboxes: z.array(SandboxInfoSchema).describe('List of sandbox entries'),
+		total: z.number().describe('Total number of sandboxes matching the query'),
+	})
+	.describe('Paginated list of sandboxes');
+
+export const ListSandboxesResponseSchema = APIResponseSchema(ListSandboxesDataSchema);
+
+export const SandboxListParamsSchema = ListSandboxesParamsSchema.extend({
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	deletedOnly: z.boolean().optional().describe('Whether to return only deleted sandboxes'),
+});
+
+export type SandboxListParams = z.infer<typeof SandboxListParamsSchema>;
+
+/**
+ * Lists sandboxes with optional filtering and pagination.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Optional parameters for filtering by project, status, and pagination
+ * @returns Paginated list of sandboxes with total count
+ * @throws {SandboxResponseError} If the request fails
+ */
+export async function sandboxList(
+	client: APIClient,
+	params?: SandboxListParams
+): Promise<ListSandboxesResponse> {
+	const queryParams = new URLSearchParams();
+
+	if (params?.orgId) {
+		queryParams.set('orgId', params.orgId);
+	}
+	if (params?.name) {
+		queryParams.set('name', params.name);
+	}
+	if (params?.mode) {
+		queryParams.set('mode', params.mode);
+	}
+	if (params?.projectId) {
+		queryParams.set('projectId', params.projectId);
+	}
+	if (params?.snapshotId) {
+		queryParams.set('snapshotId', params.snapshotId);
+	}
+	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());
+	}
+	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);
+	}
+	if (params?.deletedOnly) {
+		queryParams.set('deletedOnly', 'true');
+	}
+
+	const queryString = queryParams.toString();
+	const url = `/sandbox${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ListSandboxesResponseSchema>>(
+		url,
+		ListSandboxesResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			sandboxes: resp.data.sandboxes.map((s) => ({
+				sandboxId: s.sandboxId,
+				identifier: s.identifier,
+				name: s.name,
+				description: s.description,
+				status: s.status as SandboxStatus,
+				mode: s.mode,
+				createdAt: s.createdAt,
+				region: s.region,
+				runtime: s.runtime as SandboxRuntimeInfo | undefined,
+				snapshot: s.snapshot as SandboxSnapshotInfo | undefined,
+				executions: s.executions,
+				stdoutStreamUrl: s.stdoutStreamUrl,
+				stderrStreamUrl: s.stderrStreamUrl,
+				auditStreamId: s.auditStreamId,
+				auditStreamUrl: s.auditStreamUrl,
+				networkEnabled: s.networkEnabled,
+				networkPort: s.networkPort,
+				url: s.url,
+				org: s.org,
+				timeout: s.timeout,
+			})),
+			total: resp.data.total,
+		};
+	}
+
+	throwSandboxError(resp, {});
+}

package/src/pause.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { type APIClient } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export const PauseResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string(),
+		code: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		sandboxId: z.string(),
+		status: z.string(),
+		checkpointId: z.string().optional(),
+		terminatesAt: z.string().optional(),
+	}),
+]);
+
+export const SandboxPauseParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID to pause'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type SandboxPauseParams = z.infer<typeof SandboxPauseParamsSchema>;
+
+/** Result returned from pausing a sandbox */
+export interface SandboxPauseResult {
+	/** The sandbox ID that was paused */
+	sandboxId: string;
+	/** New status (typically "suspended") */
+	status: string;
+	/** Checkpoint ID created during pause */
+	checkpointId?: string;
+	/** ISO 8601 timestamp when sandbox will auto-terminate if not resumed (omitted if no paused timeout) */
+	terminatesAt?: string;
+}
+
+/**
+ * Pauses a running sandbox, creating a checkpoint of its current state.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to pause
+ * @returns Pause result including terminatesAt if a paused timeout is configured
+ * @throws {SandboxResponseError} If the sandbox is not found or pause fails
+ */
+export async function sandboxPause(
+	client: APIClient,
+	params: SandboxPauseParams
+): Promise<SandboxPauseResult> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/pause${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof PauseResponseSchema>>(
+		url,
+		undefined,
+		PauseResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			sandboxId: resp.sandboxId,
+			status: resp.status,
+			checkpointId: resp.checkpointId,
+			terminatesAt: resp.terminatesAt,
+		};
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/resolve.ts

@@ -0,0 +1,96 @@
+import { StructuredError } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchemaOptionalData } from '@agentuity/api';
+
+/**
+ * Data schema for sandbox resolve endpoint
+ */
+export const SandboxResolveDataSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the sandbox.'),
+		name: z.string().nullable().describe('Sandbox name, or null if unnamed.'),
+		region: z.string().describe('Cloud region where the sandbox is running.'),
+		status: z.string().describe('Current status of the sandbox.'),
+		orgId: z.string().describe('Organization ID that owns the sandbox.'),
+		projectId: z
+			.string()
+			.nullable()
+			.describe('Project ID the sandbox belongs to, or null if unassigned.'),
+	})
+	.describe('Resolved sandbox information from cross-organization lookup.');
+
+/**
+ * Response schema for sandbox resolve endpoint using standardized discriminated union
+ */
+export const SandboxResolveResponseSchema = APIResponseSchemaOptionalData(SandboxResolveDataSchema);
+
+/**
+ * Resolved sandbox info returned from the CLI API
+ */
+export type ResolvedSandboxInfo = z.infer<typeof SandboxResolveDataSchema>;
+
+/**
+ * Error thrown when sandbox resolution fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxResolve(client, 'sbx_123');
+ * } catch (error) {
+ *   if (error._tag === 'SandboxResolveError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxResolveError = StructuredError('SandboxResolveError')<{
+	sandboxId?: string;
+	statusCode?: number;
+}>();
+
+/**
+ * Resolve a sandbox by ID across all organizations the user has access to.
+ * Uses the CLI API endpoint which searches across all user's orgs.
+ *
+ * @param client - API client configured for CLI endpoints
+ * @param sandboxId - The sandbox ID to resolve
+ * @returns Resolved sandbox info including region and orgId
+ * @throws {SandboxResolveError} If sandbox not found or request fails
+ */
+export async function sandboxResolve(
+	client: APIClient,
+	sandboxId: string
+): Promise<ResolvedSandboxInfo> {
+	const response = await client.get<z.infer<typeof SandboxResolveResponseSchema>>(
+		`/cli/sandbox/${sandboxId}`,
+		SandboxResolveResponseSchema
+	);
+
+	if (!response.success) {
+		// Extract status code from error code if present (e.g., "NOT_FOUND" -> 404)
+		// Fall back to 404 if no code is provided
+		const statusCode = response.code === 'NOT_FOUND' ? 404 : response.code ? 400 : 404;
+		throw new SandboxResolveError({
+			message: response.message || 'Sandbox not found',
+			sandboxId,
+			statusCode,
+		});
+	}
+
+	if (!response.data) {
+		throw new SandboxResolveError({
+			message: 'Sandbox not found',
+			sandboxId,
+			statusCode: 404,
+		});
+	}
+
+	return {
+		id: response.data.id,
+		name: response.data.name,
+		region: response.data.region,
+		status: response.data.status,
+		orgId: response.data.orgId,
+		projectId: response.data.projectId,
+	};
+}

package/src/resume.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchemaNoData } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export const ResumeResponseSchema = APIResponseSchemaNoData();
+
+export const SandboxResumeParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID to resume'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type SandboxResumeParams = z.infer<typeof SandboxResumeParamsSchema>;
+
+/**
+ * Resumes a paused sandbox from its checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to resume
+ * @throws {SandboxResponseError} If the sandbox is not found or resume fails
+ */
+export async function sandboxResume(client: APIClient, params: SandboxResumeParams): Promise<void> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/resume${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof ResumeResponseSchema>>(
+		url,
+		undefined,
+		ResumeResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}