@agentuity/server 1.0.1 → 1.0.3

package/src/api/sandbox/cli-list.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError } from './util';
+
+export const SandboxInfoSchema = z.object({
+	id: z.string().describe('the sandbox id'),
+	name: z.string().nullable().describe('the sandbox name'),
+	description: z.string().nullable().describe('the sandbox description'),
+	status: z.string().describe('sandbox status'),
+	region: z.string().nullable().describe('cloud region'),
+	createdAt: z.string().nullable().describe('ISO 8601 creation timestamp'),
+	orgId: z.string().describe('the organization id'),
+	orgName: z.string().nullable().describe('the organization name'),
+	projectId: z.string().nullable().describe('the project id'),
+});
+
+export const SandboxListDataSchema = z.object({
+	sandboxes: z.array(SandboxInfoSchema).describe('list of sandboxes'),
+	total: z.number().describe('total count of matching sandboxes'),
+});
+
+export const SandboxListResponseSchema = APIResponseSchema(SandboxListDataSchema);
+
+export type CLISandboxListResponse = z.infer<typeof SandboxListResponseSchema>;
+export type CLISandboxListData = z.infer<typeof SandboxListDataSchema>;
+export type CLISandboxInfo = z.infer<typeof SandboxInfoSchema>;
+
+export interface CLISandboxListOptions {
+	/**
+	 * Filter by specific project ID
+	 */
+	projectId?: string;
+	/**
+	 * Filter by specific organization ID
+	 */
+	orgId?: string;
+	/**
+	 * Filter by sandbox status
+	 */
+	status?: 'creating' | 'idle' | 'running' | 'terminated' | 'failed';
+	/**
+	 * Maximum number of sandboxes to return (default: 50, max: 100)
+	 */
+	limit?: number;
+	/**
+	 * Number of sandboxes to skip for pagination
+	 */
+	offset?: number;
+}
+
+/**
+ * List sandboxes with optional filtering using the CLI API endpoint.
+ *
+ * This endpoint searches across all organizations the user is a member of,
+ * unlike the Catalyst API which requires an orgId.
+ *
+ * @param client - The API client
+ * @param options - Filtering and pagination options
+ * @returns A promise that resolves to the list of sandboxes
+ *
+ * @example
+ * // List all sandboxes across all orgs
+ * const result = await cliSandboxList(client);
+ * console.log(`Found ${result.total} sandboxes`);
+ *
+ * @example
+ * // List running sandboxes
+ * const result = await cliSandboxList(client, { status: 'running' });
+ *
+ * @example
+ * // List sandboxes for a specific project
+ * const result = await cliSandboxList(client, { projectId: 'proj_123' });
+ */
+export async function cliSandboxList(
+	client: APIClient,
+	options: CLISandboxListOptions = {}
+): Promise<CLISandboxListData> {
+	const { projectId, orgId, status, limit, offset } = options;
+	const params = new URLSearchParams();
+
+	if (projectId) params.set('projectId', projectId);
+	if (orgId) params.set('orgId', orgId);
+	if (status) params.set('status', status);
+	if (limit !== undefined) params.set('limit', limit.toString());
+	if (offset !== undefined) params.set('offset', offset.toString());
+
+	const queryString = params.toString();
+	const resp = await client.request<CLISandboxListResponse>(
+		'GET',
+		`/cli/sandbox${queryString ? `?${queryString}` : ''}`,
+		SandboxListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SandboxResponseError({ message: resp.message });
+}

package/src/api/sandbox/create.ts

@@ -1,9 +1,9 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type { SandboxCreateOptions, SandboxStatus } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const SandboxCreateRequestSchema = z
+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")'),
@@ -57,9 +57,7 @@ const SandboxCreateRequestSchema = z
 				files: z
 					.array(
 						z.object({
-							path: z
-								.string()
-								.describe('Path to the file relative to the sandbox workspace'),
+							path: z.string().describe('Path to the file relative to the sandbox workspace'),
 							content: z.string().describe('Base64-encoded file content'),
 						})
 					)
@@ -73,9 +71,14 @@ const SandboxCreateRequestSchema = z
 			.optional()
 			.describe('Initial command to run in the sandbox'),
 		files: z
-			.record(z.string(), z.string())
+			.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 (path -> base64 content)'),
+			.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())
@@ -101,7 +104,7 @@ const SandboxCreateRequestSchema = z
 	)
 	.describe('Request body for creating a new sandbox');
 
-const SandboxCreateDataSchema = z
+export const SandboxCreateDataSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the created sandbox'),
 		status: z
@@ -114,7 +117,7 @@ const SandboxCreateDataSchema = z
 	})
 	.describe('Response data from sandbox creation');
 
-const SandboxCreateResponseSchema = APIResponseSchema(SandboxCreateDataSchema);
+export const SandboxCreateResponseSchema = APIResponseSchema(SandboxCreateDataSchema);
 
 export interface SandboxCreateResponse {
 	sandboxId: string;
@@ -186,9 +189,10 @@ export async function sandboxCreate(
 		};
 	}
 	if (options.files && options.files.length > 0) {
-		body.files = Object.fromEntries(
-			options.files.map((f) => [f.path, f.content.toString('base64')])
-		);
+		body.files = options.files.map((f) => ({
+			path: f.path,
+			content: f.content.toString('base64'),
+		}));
 	}
 	if (options.snapshot) {
 		body.snapshot = options.snapshot;

package/src/api/sandbox/destroy.ts

@@ -1,8 +1,8 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchemaNoData } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
+import type { z } from 'zod';
+import { type APIClient, APIResponseSchemaNoData } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const DestroyResponseSchema = APIResponseSchemaNoData();
+export const DestroyResponseSchema = APIResponseSchemaNoData();
 
 export interface SandboxDestroyParams {
 	sandboxId: string;

package/src/api/sandbox/execute.ts

@@ -1,9 +1,9 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type { ExecuteOptions, Execution, ExecutionStatus } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const ExecuteRequestSchema = z
+export const ExecuteRequestSchema = z
 	.object({
 		command: z.array(z.string()).describe('Command and arguments to execute'),
 		files: z
@@ -22,7 +22,7 @@ const ExecuteRequestSchema = z
 	})
 	.describe('Request body for executing a command in a sandbox');
 
-const ExecuteDataSchema = z
+export const ExecuteDataSchema = z
 	.object({
 		executionId: z.string().describe('Unique identifier for the execution'),
 		status: z
@@ -35,7 +35,7 @@ const ExecuteDataSchema = z
 	})
 	.describe('Response data from command execution');
 
-const ExecuteResponseSchema = APIResponseSchema(ExecuteDataSchema);
+export const ExecuteResponseSchema = APIResponseSchema(ExecuteDataSchema);
 
 export interface SandboxExecuteParams {
 	sandboxId: string;

package/src/api/sandbox/execution.ts

@@ -1,9 +1,9 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type { ExecutionStatus } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const ExecutionInfoSchema = z
+export const ExecutionInfoSchema = z
 	.object({
 		executionId: z.string().describe('Unique identifier for the execution'),
 		sandboxId: z.string().describe('ID of the sandbox where the execution ran'),
@@ -25,15 +25,15 @@ const ExecutionInfoSchema = z
 	})
 	.describe('Detailed information about a command execution');
 
-const ExecutionGetResponseSchema = APIResponseSchema(ExecutionInfoSchema);
+export const ExecutionGetResponseSchema = APIResponseSchema(ExecutionInfoSchema);
 
-const ExecutionListDataSchema = z
+export const ExecutionListDataSchema = z
 	.object({
 		executions: z.array(ExecutionInfoSchema).describe('List of executions'),
 	})
 	.describe('List of executions for a sandbox');
 
-const ExecutionListResponseSchema = APIResponseSchema(ExecutionListDataSchema);
+export const ExecutionListResponseSchema = APIResponseSchema(ExecutionListDataSchema);
 
 export interface ExecutionInfo {
 	executionId: string;

package/src/api/sandbox/files.ts

@@ -8,19 +8,19 @@ export const FileToWriteSchema = z.object({
 	content: z.string().describe('Base64-encoded file content'),
 });
 
-const WriteFilesRequestSchema = z
+export const WriteFilesRequestSchema = z
 	.object({
 		files: z.array(FileToWriteSchema).describe('Array of files to write'),
 	})
 	.describe('Request body for writing files to a sandbox');
 
-const WriteFilesDataSchema = z
+export const WriteFilesDataSchema = z
 	.object({
 		filesWritten: z.number().describe('Number of files successfully written'),
 	})
 	.describe('Response data from writing files');
 
-const WriteFilesResponseSchema = z.discriminatedUnion('success', [
+export const WriteFilesResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -140,14 +140,14 @@ export async function sandboxReadFile(
 	return response.body;
 }
 
-const MkDirRequestSchema = z
+export const MkDirRequestSchema = z
 	.object({
 		path: z.string().describe('Path to the directory to create'),
 		recursive: z.boolean().optional().describe('Create parent directories if needed'),
 	})
 	.describe('Request body for creating a directory');
 
-const MkDirResponseSchema = z.discriminatedUnion('success', [
+export const MkDirResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -200,14 +200,14 @@ export async function sandboxMkDir(client: APIClient, params: MkDirParams): Prom
 	}
 }
 
-const RmDirRequestSchema = z
+export const RmDirRequestSchema = z
 	.object({
 		path: z.string().describe('Path to the directory to remove'),
 		recursive: z.boolean().optional().describe('Remove directory and all contents'),
 	})
 	.describe('Request body for removing a directory');
 
-const RmDirResponseSchema = z.discriminatedUnion('success', [
+export const RmDirResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -260,13 +260,13 @@ export async function sandboxRmDir(client: APIClient, params: RmDirParams): Prom
 	}
 }
 
-const RmFileRequestSchema = z
+export const RmFileRequestSchema = z
 	.object({
 		path: z.string().describe('Path to the file to remove'),
 	})
 	.describe('Request body for removing a file');
 
-const RmFileResponseSchema = z.discriminatedUnion('success', [
+export const RmFileResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -317,7 +317,7 @@ export async function sandboxRmFile(client: APIClient, params: RmFileParams): Pr
 	}
 }
 
-const FileInfoSchema = z.object({
+export const FileInfoSchema = z.object({
 	path: z.string().describe('File path relative to the listed directory'),
 	size: z.number().describe('File size in bytes'),
 	isDir: z.boolean().describe('Whether the entry is a directory'),
@@ -325,11 +325,11 @@ const FileInfoSchema = z.object({
 	modTime: z.string().describe('Modification time in RFC3339 format'),
 });
 
-const ListFilesDataSchema = z.object({
+export const ListFilesDataSchema = z.object({
 	files: z.array(FileInfoSchema).describe('Array of file information'),
 });
 
-const ListFilesResponseSchema = z.discriminatedUnion('success', [
+export const ListFilesResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -467,7 +467,7 @@ export interface UploadArchiveParams {
 	signal?: AbortSignal;
 }
 
-const UploadArchiveResponseSchema = z.discriminatedUnion('success', [
+export const UploadArchiveResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),
@@ -523,17 +523,17 @@ export async function sandboxUploadArchive(
 	}
 }
 
-const SetEnvRequestSchema = z.object({
+export const SetEnvRequestSchema = z.object({
 	env: z
 		.record(z.string(), z.string().nullable())
 		.describe('Environment variables to set (null to delete)'),
 });
 
-const SetEnvDataSchema = z.object({
+export const SetEnvDataSchema = z.object({
 	env: z.record(z.string(), z.string()).describe('Current environment variables after update'),
 });
 
-const SetEnvResponseSchema = z.discriminatedUnion('success', [
+export const SetEnvResponseSchema = z.discriminatedUnion('success', [
 	z.object({
 		success: z.literal<false>(false),
 		message: z.string().describe('the error message'),

package/src/api/sandbox/get.ts

@@ -1,14 +1,14 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type {
 	SandboxInfo,
-	SandboxStatus,
 	SandboxRuntimeInfo,
 	SandboxSnapshotInfo,
+	SandboxStatus,
 } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const SandboxResourcesSchema = z
+export const SandboxResourcesSchema = z
 	.object({
 		memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
 		cpu: z.string().optional().describe('CPU limit in millicores (e.g., "500m", "1000m")'),
@@ -16,7 +16,7 @@ const SandboxResourcesSchema = z
 	})
 	.describe('Resource limits for the sandbox');
 
-const SandboxUserInfoSchema = z
+export const SandboxUserInfoSchema = z
 	.object({
 		id: z.string().describe('User ID'),
 		firstName: z.string().optional().describe("User's first name"),
@@ -24,28 +24,28 @@ const SandboxUserInfoSchema = z
 	})
 	.describe('User who created the sandbox');
 
-const SandboxAgentInfoSchema = z
+export const SandboxAgentInfoSchema = z
 	.object({
 		id: z.string().describe('Agent ID'),
 		name: z.string().describe('Agent name'),
 	})
 	.describe('Agent associated with the sandbox');
 
-const SandboxProjectInfoSchema = z
+export const SandboxProjectInfoSchema = z
 	.object({
 		id: z.string().describe('Project ID'),
 		name: z.string().describe('Project name'),
 	})
 	.describe('Project associated with the sandbox');
 
-const SandboxOrgInfoSchema = z
+export const SandboxOrgInfoSchema = z
 	.object({
 		id: z.string().describe('Organization ID'),
 		name: z.string().describe('Organization name'),
 	})
 	.describe('Organization associated with the sandbox');
 
-const SandboxRuntimeInfoSchema = z
+export const SandboxRuntimeInfoSchema = z
 	.object({
 		id: z.string().describe('Runtime ID'),
 		name: z.string().describe('Runtime name (e.g., "bun:1")'),
@@ -55,7 +55,7 @@ const SandboxRuntimeInfoSchema = z
 	})
 	.describe('Runtime information');
 
-const SandboxSnapshotUserInfoSchema = z
+export const SandboxSnapshotUserInfoSchema = z
 	.object({
 		id: z.string().describe('User ID'),
 		firstName: z.string().optional().describe("User's first name"),
@@ -63,7 +63,7 @@ const SandboxSnapshotUserInfoSchema = z
 	})
 	.describe('Snapshot user information');
 
-const SandboxSnapshotOrgInfoSchema = z
+export const SandboxSnapshotOrgInfoSchema = z
 	.object({
 		id: z.string().describe('Organization ID'),
 		name: z.string().describe('Organization name'),
@@ -71,7 +71,7 @@ const SandboxSnapshotOrgInfoSchema = z
 	})
 	.describe('Snapshot organization information');
 
-const SandboxSnapshotInfoSchema = z
+export const SandboxSnapshotInfoSchema = z
 	.union([
 		z
 			.object({
@@ -98,7 +98,7 @@ const SandboxSnapshotInfoSchema = z
 	])
 	.describe('Snapshot information (discriminated union)');
 
-const SandboxInfoDataSchema = z
+export const SandboxInfoDataSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
 		identifier: z.string().optional().describe('Short identifier for DNS hostname'),
@@ -144,7 +144,7 @@ const SandboxInfoDataSchema = z
 	})
 	.describe('Detailed information about a sandbox');
 
-const SandboxGetResponseSchema = APIResponseSchema(SandboxInfoDataSchema);
+export const SandboxGetResponseSchema = APIResponseSchema(SandboxInfoDataSchema);
 
 export interface SandboxGetParams {
 	sandboxId: string;