@agentuity/server 0.0.110 → 0.0.111

package/src/api/sandbox/create.ts

@@ -65,6 +65,10 @@ const SandboxCreateRequestSchema = z
 			.array(z.string())
 			.optional()
 			.describe('Apt packages to install when creating the sandbox'),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe('Optional user-defined metadata to associate with the sandbox'),
 	})
 	.describe('Request body for creating a new sandbox');
 
@@ -143,6 +147,9 @@ export async function sandboxCreate(
 	if (options.dependencies && options.dependencies.length > 0) {
 		body.dependencies = options.dependencies;
 	}
+	if (options.metadata) {
+		body.metadata = options.metadata;
+	}
 
 	const queryParams = new URLSearchParams();
 	if (orgId) {

package/src/api/sandbox/files.ts

@@ -136,3 +136,453 @@ export async function sandboxReadFile(
 
 	return response.body;
 }
+
+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', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+	}),
+]);
+
+export interface MkDirParams {
+	sandboxId: string;
+	path: string;
+	recursive?: boolean;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Creates a directory in a sandbox workspace.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID, path, and recursive flag
+ * @throws {SandboxResponseError} If the mkdir request fails
+ */
+export async function sandboxMkDir(client: APIClient, params: MkDirParams): Promise<void> {
+	const { sandboxId, path, recursive, orgId, signal } = params;
+
+	const body: z.infer<typeof MkDirRequestSchema> = {
+		path,
+		recursive: recursive ?? false,
+	};
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/mkdir/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof MkDirResponseSchema>>(
+		url,
+		body,
+		MkDirResponseSchema,
+		MkDirRequestSchema,
+		signal
+	);
+
+	if (!resp.success) {
+		throw new SandboxResponseError({ message: resp.message, sandboxId });
+	}
+}
+
+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', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+	}),
+]);
+
+export interface RmDirParams {
+	sandboxId: string;
+	path: string;
+	recursive?: boolean;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Removes a directory from a sandbox workspace.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID, path, and recursive flag
+ * @throws {SandboxResponseError} If the rmdir request fails
+ */
+export async function sandboxRmDir(client: APIClient, params: RmDirParams): Promise<void> {
+	const { sandboxId, path, recursive, orgId, signal } = params;
+
+	const body: z.infer<typeof RmDirRequestSchema> = {
+		path,
+		recursive: recursive ?? false,
+	};
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/rmdir/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof RmDirResponseSchema>>(
+		url,
+		body,
+		RmDirResponseSchema,
+		RmDirRequestSchema,
+		signal
+	);
+
+	if (!resp.success) {
+		throw new SandboxResponseError({ message: resp.message, sandboxId });
+	}
+}
+
+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', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+	}),
+]);
+
+export interface RmFileParams {
+	sandboxId: string;
+	path: string;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Removes a file from a sandbox workspace.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and path
+ * @throws {SandboxResponseError} If the rm request fails
+ */
+export async function sandboxRmFile(client: APIClient, params: RmFileParams): Promise<void> {
+	const { sandboxId, path, orgId, signal } = params;
+
+	const body: z.infer<typeof RmFileRequestSchema> = {
+		path,
+	};
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/rm/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof RmFileResponseSchema>>(
+		url,
+		body,
+		RmFileResponseSchema,
+		RmFileRequestSchema,
+		signal
+	);
+
+	if (!resp.success) {
+		throw new SandboxResponseError({ message: resp.message, sandboxId });
+	}
+}
+
+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'),
+	mode: z.string().describe('Unix permissions as octal string (e.g., "0644")'),
+	modTime: z.string().describe('Modification time in RFC3339 format'),
+});
+
+const ListFilesDataSchema = z.object({
+	files: z.array(FileInfoSchema).describe('Array of file information'),
+});
+
+const ListFilesResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		data: ListFilesDataSchema,
+	}),
+]);
+
+export interface FileInfo {
+	path: string;
+	size: number;
+	isDir: boolean;
+	mode: string;
+	modTime: string;
+}
+
+export interface ListFilesParams {
+	sandboxId: string;
+	path?: string;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+export interface ListFilesResult {
+	files: FileInfo[];
+}
+
+/**
+ * Lists files in a sandbox workspace directory.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and optional path
+ * @returns The list of files and directories
+ * @throws {SandboxResponseError} If the list request fails
+ */
+export async function sandboxListFiles(
+	client: APIClient,
+	params: ListFilesParams
+): Promise<ListFilesResult> {
+	const { sandboxId, path, orgId, signal } = params;
+
+	const queryParams = new URLSearchParams();
+	if (path) {
+		queryParams.set('path', path);
+	}
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/list/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ListFilesResponseSchema>>(
+		url,
+		ListFilesResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return {
+			files: resp.data.files,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}
+
+export type ArchiveFormat = 'zip' | 'tar.gz';
+
+export interface DownloadArchiveParams {
+	sandboxId: string;
+	path?: string;
+	format?: ArchiveFormat;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Downloads files from a sandbox as a compressed archive.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID, path, and format
+ * @returns A ReadableStream of the archive contents
+ * @throws {SandboxResponseError} If the download request fails
+ */
+export async function sandboxDownloadArchive(
+	client: APIClient,
+	params: DownloadArchiveParams
+): Promise<ReadableStream<Uint8Array>> {
+	const { sandboxId, path, format, orgId, signal } = params;
+
+	const queryParams = new URLSearchParams();
+	if (path) {
+		queryParams.set('path', path);
+	}
+	if (format) {
+		queryParams.set('format', format);
+	}
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/download/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const response = await client.rawGet(url, signal);
+
+	if (!response.ok) {
+		const text = await response.text().catch(() => 'Unknown error');
+		throw new SandboxResponseError({
+			message: `Failed to download archive: ${response.status} ${text}`,
+			sandboxId,
+		});
+	}
+
+	if (!response.body) {
+		throw new SandboxResponseError({
+			message: 'No response body',
+			sandboxId,
+		});
+	}
+
+	return response.body;
+}
+
+export interface UploadArchiveParams {
+	sandboxId: string;
+	archive: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+	path?: string;
+	format?: ArchiveFormat | '';
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+const UploadArchiveResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+	}),
+]);
+
+/**
+ * Uploads a compressed archive to a sandbox and extracts it.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID, archive data, path, and optional format
+ * @throws {SandboxResponseError} If the upload request fails
+ */
+export async function sandboxUploadArchive(
+	client: APIClient,
+	params: UploadArchiveParams
+): Promise<void> {
+	const { sandboxId, archive, path, format, orgId, signal } = params;
+
+	const queryParams = new URLSearchParams();
+	if (path) {
+		queryParams.set('path', path);
+	}
+	if (format) {
+		queryParams.set('format', format);
+	}
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/upload/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const response = await client.rawPost(url, archive, 'application/octet-stream', signal);
+
+	if (!response.ok) {
+		const text = await response.text().catch(() => 'Unknown error');
+		throw new SandboxResponseError({
+			message: `Failed to upload archive: ${response.status} ${text}`,
+			sandboxId,
+		});
+	}
+
+	const body = await response.json();
+	const result = UploadArchiveResponseSchema.parse(body);
+
+	if (!result.success) {
+		throw new SandboxResponseError({ message: result.message, sandboxId });
+	}
+}
+
+const SetEnvRequestSchema = z.object({
+	env: z
+		.record(z.string(), z.string().nullable())
+		.describe('Environment variables to set (null to delete)'),
+});
+
+const SetEnvDataSchema = z.object({
+	env: z.record(z.string(), z.string()).describe('Current environment variables after update'),
+});
+
+const SetEnvResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().describe('the error message'),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		data: SetEnvDataSchema,
+	}),
+]);
+
+export interface SetEnvParams {
+	sandboxId: string;
+	env: Record<string, string | null>;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+export interface SetEnvResult {
+	env: Record<string, string>;
+}
+
+/**
+ * Sets environment variables on a sandbox. Pass null to delete a variable.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and env key/value pairs
+ * @returns The current environment variables after the update
+ * @throws {SandboxResponseError} If the request fails
+ */
+export async function sandboxSetEnv(
+	client: APIClient,
+	params: SetEnvParams
+): Promise<SetEnvResult> {
+	const { sandboxId, env, orgId, signal } = params;
+
+	const body: z.infer<typeof SetEnvRequestSchema> = { env };
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/env/${API_VERSION}/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.patch<z.infer<typeof SetEnvResponseSchema>>(
+		url,
+		body,
+		SetEnvResponseSchema,
+		SetEnvRequestSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return {
+			env: resp.data.env,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}

package/src/api/sandbox/get.ts

@@ -20,6 +20,10 @@ const SandboxInfoDataSchema = z
 			.array(z.string())
 			.optional()
 			.describe('Apt packages installed in the sandbox'),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe('User-defined metadata associated with the sandbox'),
 	})
 	.describe('Detailed information about a sandbox');
 
@@ -67,6 +71,7 @@ export async function sandboxGet(
 			stdoutStreamUrl: resp.data.stdoutStreamUrl,
 			stderrStreamUrl: resp.data.stderrStreamUrl,
 			dependencies: resp.data.dependencies,
+			metadata: resp.data.metadata as Record<string, unknown> | undefined,
 		};
 	}
 

package/src/api/sandbox/index.ts

@@ -20,8 +20,33 @@ export type {
 export { SandboxResponseError, writeAndDrain } from './util';
 export { SandboxClient } from './client';
 export type { SandboxClientOptions, SandboxInstance, ExecuteOptions } from './client';
-export { sandboxWriteFiles, sandboxReadFile } from './files';
-export type { WriteFilesParams, WriteFilesResult, ReadFileParams } from './files';
+export {
+	sandboxWriteFiles,
+	sandboxReadFile,
+	sandboxMkDir,
+	sandboxRmDir,
+	sandboxRmFile,
+	sandboxListFiles,
+	sandboxDownloadArchive,
+	sandboxUploadArchive,
+	sandboxSetEnv,
+} from './files';
+export type {
+	WriteFilesParams,
+	WriteFilesResult,
+	ReadFileParams,
+	MkDirParams,
+	RmDirParams,
+	RmFileParams,
+	ListFilesParams,
+	ListFilesResult,
+	FileInfo,
+	ArchiveFormat,
+	DownloadArchiveParams,
+	UploadArchiveParams,
+	SetEnvParams,
+	SetEnvResult,
+} from './files';
 export { snapshotCreate, snapshotGet, snapshotList, snapshotDelete, snapshotTag } from './snapshot';
 export type {
 	SnapshotInfo,

package/src/api/sandbox/snapshot.ts

@@ -1,8 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
-import { SandboxResponseError } from './util';
-
-const SNAPSHOT_API_VERSION = '2025-06-26';
+import { SandboxResponseError, API_VERSION } from './util';
 
 const SnapshotFileInfoSchema = z
 	.object({
@@ -14,7 +12,6 @@ const SnapshotFileInfoSchema = z
 const SnapshotInfoSchema = z
 	.object({
 		snapshotId: z.string().describe('Unique identifier for the snapshot'),
-		sandboxId: z.string().describe('ID of the sandbox this snapshot was created from'),
 		tag: z.string().nullable().optional().describe('User-defined tag for the snapshot'),
 		sizeBytes: z.number().describe('Total size of the snapshot in bytes'),
 		fileCount: z.number().describe('Number of files in the snapshot'),
@@ -47,7 +44,6 @@ export interface SnapshotFileInfo {
 
 export interface SnapshotInfo {
 	snapshotId: string;
-	sandboxId: string;
 	tag?: string | null;
 	sizeBytes: number;
 	fileCount: number;
@@ -116,7 +112,7 @@ export async function snapshotCreate(
 ): Promise<SnapshotInfo> {
 	const { sandboxId, tag, orgId } = params;
 	const queryString = buildQueryString({ orgId });
-	const url = `/sandbox/${SNAPSHOT_API_VERSION}/${sandboxId}/snapshot${queryString}`;
+	const url = `/sandbox/${API_VERSION}/${sandboxId}/snapshot${queryString}`;
 
 	const body: Record<string, string> = {};
 	if (tag) {
@@ -150,7 +146,7 @@ export async function snapshotGet(
 ): Promise<SnapshotInfo> {
 	const { snapshotId, orgId } = params;
 	const queryString = buildQueryString({ orgId });
-	const url = `/sandbox/${SNAPSHOT_API_VERSION}/snapshots/${snapshotId}${queryString}`;
+	const url = `/sandbox/${API_VERSION}/snapshots/${snapshotId}${queryString}`;
 
 	const resp = await client.get<z.infer<typeof SnapshotGetResponseSchema>>(
 		url,
@@ -178,7 +174,7 @@ export async function snapshotList(
 ): Promise<SnapshotListResponse> {
 	const { sandboxId, limit, offset, orgId } = params;
 	const queryString = buildQueryString({ sandboxId, limit, offset, orgId });
-	const url = `/sandbox/${SNAPSHOT_API_VERSION}/snapshots${queryString}`;
+	const url = `/sandbox/${API_VERSION}/snapshots${queryString}`;
 
 	const resp = await client.get<z.infer<typeof SnapshotListResponseSchema>>(
 		url,
@@ -205,7 +201,7 @@ export async function snapshotDelete(
 ): Promise<void> {
 	const { snapshotId, orgId } = params;
 	const queryString = buildQueryString({ orgId });
-	const url = `/sandbox/${SNAPSHOT_API_VERSION}/snapshots/${snapshotId}${queryString}`;
+	const url = `/sandbox/${API_VERSION}/snapshots/${snapshotId}${queryString}`;
 
 	const resp = await client.delete<z.infer<typeof SnapshotDeleteResponseSchema>>(
 		url,
@@ -231,7 +227,7 @@ export async function snapshotTag(
 ): Promise<SnapshotInfo> {
 	const { snapshotId, tag, orgId } = params;
 	const queryString = buildQueryString({ orgId });
-	const url = `/sandbox/${SNAPSHOT_API_VERSION}/snapshots/${snapshotId}${queryString}`;
+	const url = `/sandbox/${API_VERSION}/snapshots/${snapshotId}${queryString}`;
 
 	const resp = await client.patch<z.infer<typeof SnapshotGetResponseSchema>>(
 		url,

package/src/schema.ts

@@ -13,7 +13,9 @@ export const toJSONSchema = (schema: any): JSONSchema => {
 		return agentuityToJSONSchema(schema);
 	}
 	// Check if it's a Zod schema
-	if (schema?._def?.typeName) {
+	// Zod 3 uses _def.typeName (e.g., "ZodObject")
+	// Zod 4 uses _def.type (e.g., "object")
+	if (schema?._def?.typeName || schema?._def?.type) {
 		try {
 			return z.toJSONSchema(schema) as JSONSchema;
 		} catch {