@agentuity/server 0.0.105 → 0.0.106

package/src/api/sandbox/create.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import type { SandboxCreateOptions, SandboxStatus } from '@agentuity/core';
+
+const SandboxCreateRequestSchema = z
+	.object({
+		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'),
+			})
+			.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")'),
+			})
+			.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'),
+				mode: z
+					.enum(['oneshot', 'interactive'])
+					.optional()
+					.describe('Execution mode: oneshot runs once, interactive keeps running'),
+			})
+			.optional()
+			.describe('Initial command to run in the sandbox'),
+		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'),
+	})
+	.describe('Request body for creating a new sandbox');
+
+const SandboxCreateDataSchema = z
+	.object({
+		sandboxId: z.string().describe('Unique identifier for the created sandbox'),
+		status: z
+			.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+			.describe('Current status of the sandbox'),
+		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'),
+	})
+	.describe('Response data from sandbox creation');
+
+const SandboxCreateResponseSchema = APIResponseSchema(SandboxCreateDataSchema);
+
+export interface SandboxCreateResponse {
+	sandboxId: string;
+	status: SandboxStatus;
+	stdoutStreamId?: string;
+	stdoutStreamUrl?: string;
+	stderrStreamId?: string;
+	stderrStreamUrl?: string;
+}
+
+export interface SandboxCreateParams {
+	options?: SandboxCreateOptions;
+	orgId?: string;
+}
+
+/**
+ * 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.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: f.content.toString('base64'),
+			})),
+		};
+	}
+	if (options.snapshot) {
+		body.snapshot = options.snapshot;
+	}
+	if (options.dependencies && options.dependencies.length > 0) {
+		body.dependencies = options.dependencies;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof SandboxCreateResponseSchema>>(
+		url,
+		body,
+		SandboxCreateResponseSchema,
+		SandboxCreateRequestSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SandboxResponseError({ message: resp.message });
+}

package/src/api/sandbox/destroy.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchemaNoData } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+
+const DestroyResponseSchema = APIResponseSchemaNoData();
+
+export interface SandboxDestroyParams {
+	sandboxId: string;
+	orgId?: string;
+}
+
+/**
+ * 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/${API_VERSION}/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof DestroyResponseSchema>>(
+		url,
+		DestroyResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}

package/src/api/sandbox/execute.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import { FileToWriteSchema } from './files';
+import type { ExecuteOptions, Execution, ExecutionStatus } from '@agentuity/core';
+
+const ExecuteRequestSchema = z
+	.object({
+		command: z.array(z.string()).describe('Command and arguments to execute'),
+		files: z.array(FileToWriteSchema).optional().describe('Files to write before execution'),
+		timeout: z.string().optional().describe('Execution timeout (e.g., "30s", "5m")'),
+		stream: z
+			.object({
+				stdout: z.string().optional().describe('Stream ID for stdout output'),
+				stderr: z.string().optional().describe('Stream ID for stderr output'),
+				timestamps: z.boolean().optional().describe('Whether to include timestamps in output'),
+			})
+			.optional()
+			.describe('Stream configuration for output redirection'),
+	})
+	.describe('Request body for executing a command in a sandbox');
+
+const ExecuteDataSchema = z
+	.object({
+		executionId: z.string().describe('Unique identifier for the execution'),
+		status: z
+			.enum(['queued', 'running', 'completed', 'failed', 'timeout', 'cancelled'])
+			.describe('Current status of the execution'),
+		exitCode: z.number().optional().describe('Exit code of the executed command'),
+		durationMs: z.number().optional().describe('Execution duration in milliseconds'),
+		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
+		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+	})
+	.describe('Response data from command execution');
+
+const ExecuteResponseSchema = APIResponseSchema(ExecuteDataSchema);
+
+export interface SandboxExecuteParams {
+	sandboxId: string;
+	options: ExecuteOptions;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Executes a command in an existing sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and execution options
+ * @returns The execution result including status and stream URLs
+ * @throws {SandboxResponseError} If the execution request fails
+ */
+export async function sandboxExecute(
+	client: APIClient,
+	params: SandboxExecuteParams
+): Promise<Execution> {
+	const { sandboxId, options, orgId, signal } = params;
+	const body: z.infer<typeof ExecuteRequestSchema> = {
+		command: options.command,
+	};
+
+	if (options.files) {
+		body.files = options.files.map((f) => ({
+			path: f.path,
+			content: f.content.toString('base64'),
+		}));
+	}
+	if (options.timeout) {
+		body.timeout = options.timeout;
+	}
+	if (options.stream) {
+		body.stream = options.stream;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/${sandboxId}/execute${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof ExecuteResponseSchema>>(
+		url,
+		body,
+		ExecuteResponseSchema,
+		ExecuteRequestSchema,
+		signal ?? options.signal
+	);
+
+	if (resp.success) {
+		return {
+			executionId: resp.data.executionId,
+			status: resp.data.status as ExecutionStatus,
+			exitCode: resp.data.exitCode,
+			durationMs: resp.data.durationMs,
+			stdoutStreamUrl: resp.data.stdoutStreamUrl,
+			stderrStreamUrl: resp.data.stderrStreamUrl,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}

package/src/api/sandbox/execution.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import type { ExecutionStatus } from '@agentuity/core';
+
+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'),
+		status: z
+			.enum(['queued', 'running', 'completed', 'failed', 'timeout', 'cancelled'])
+			.describe('Current status of the execution'),
+		command: z.array(z.string()).optional().describe('Command that was executed'),
+		exitCode: z.number().optional().describe('Exit code of the executed command'),
+		durationMs: z.number().optional().describe('Execution duration in milliseconds'),
+		startedAt: z.string().optional().describe('ISO timestamp when execution started'),
+		completedAt: z.string().optional().describe('ISO timestamp when execution completed'),
+		error: z.string().optional().describe('Error message if execution failed'),
+		stdoutStreamUrl: z.string().optional().describe('URL to stream stdout output'),
+		stderrStreamUrl: z.string().optional().describe('URL to stream stderr output'),
+	})
+	.describe('Detailed information about a command execution');
+
+const ExecutionGetResponseSchema = APIResponseSchema(ExecutionInfoSchema);
+
+const ExecutionListDataSchema = z
+	.object({
+		executions: z.array(ExecutionInfoSchema).describe('List of executions'),
+	})
+	.describe('List of executions for a sandbox');
+
+const ExecutionListResponseSchema = APIResponseSchema(ExecutionListDataSchema);
+
+export interface ExecutionInfo {
+	executionId: string;
+	sandboxId: string;
+	status: ExecutionStatus;
+	command?: string[];
+	exitCode?: number;
+	durationMs?: number;
+	startedAt?: string;
+	completedAt?: string;
+	error?: string;
+	stdoutStreamUrl?: string;
+	stderrStreamUrl?: string;
+}
+
+export interface ExecutionGetParams {
+	executionId: string;
+	orgId?: string;
+}
+
+/**
+ * Retrieves detailed information about a specific execution.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the execution ID
+ * @returns Detailed execution information including status, timing, and errors
+ * @throws {SandboxResponseError} If the execution is not found or request fails
+ */
+export async function executionGet(
+	client: APIClient,
+	params: ExecutionGetParams
+): Promise<ExecutionInfo> {
+	const { executionId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/execution/${executionId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ExecutionGetResponseSchema>>(
+		url,
+		ExecutionGetResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			executionId: resp.data.executionId,
+			sandboxId: resp.data.sandboxId,
+			status: resp.data.status as ExecutionStatus,
+			command: resp.data.command,
+			exitCode: resp.data.exitCode,
+			durationMs: resp.data.durationMs,
+			startedAt: resp.data.startedAt,
+			completedAt: resp.data.completedAt,
+			error: resp.data.error,
+			stdoutStreamUrl: resp.data.stdoutStreamUrl,
+			stderrStreamUrl: resp.data.stderrStreamUrl,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, executionId });
+}
+
+export interface ExecutionListParams {
+	sandboxId: string;
+	orgId?: string;
+	limit?: number;
+}
+
+export interface ExecutionListResponse {
+	executions: ExecutionInfo[];
+}
+
+/**
+ * Lists all executions for a specific sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and optional limit
+ * @returns List of execution information for the sandbox
+ * @throws {SandboxResponseError} If the sandbox is not found or request fails
+ */
+export async function executionList(
+	client: APIClient,
+	params: ExecutionListParams
+): Promise<ExecutionListResponse> {
+	const { sandboxId, orgId, limit } = 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/${API_VERSION}/sandboxes/${sandboxId}/executions${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ExecutionListResponseSchema>>(
+		url,
+		ExecutionListResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			executions: resp.data.executions.map((exec) => ({
+				executionId: exec.executionId,
+				sandboxId: exec.sandboxId,
+				status: exec.status as ExecutionStatus,
+				command: exec.command,
+				exitCode: exec.exitCode,
+				durationMs: exec.durationMs,
+				startedAt: exec.startedAt,
+				completedAt: exec.completedAt,
+				error: exec.error,
+				stdoutStreamUrl: exec.stdoutStreamUrl,
+				stderrStreamUrl: exec.stderrStreamUrl,
+			})),
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}

package/src/api/sandbox/files.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { APIClient } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import type { FileToWrite } from '@agentuity/core';
+
+export const FileToWriteSchema = z.object({
+	path: z.string().describe('Path to the file relative to the sandbox workspace'),
+	content: z.string().describe('Base64-encoded file content'),
+});
+
+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
+	.object({
+		filesWritten: z.number().describe('Number of files successfully written'),
+	})
+	.describe('Response data from writing files');
+
+const WriteFilesResponseSchema = 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: WriteFilesDataSchema.optional(),
+		filesWritten: z.number().optional(),
+	}),
+]);
+
+export interface WriteFilesParams {
+	sandboxId: string;
+	files: FileToWrite[];
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+export interface WriteFilesResult {
+	filesWritten: number;
+}
+
+/**
+ * Writes files to a sandbox workspace.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and files to write
+ * @returns The result including number of files written
+ * @throws {SandboxResponseError} If the write request fails
+ */
+export async function sandboxWriteFiles(
+	client: APIClient,
+	params: WriteFilesParams
+): Promise<WriteFilesResult> {
+	const { sandboxId, files, orgId, signal } = params;
+
+	const body: z.infer<typeof WriteFilesRequestSchema> = {
+		files: files.map((f) => ({
+			path: f.path,
+			content: f.content.toString('base64'),
+		})),
+	};
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof WriteFilesResponseSchema>>(
+		url,
+		body,
+		WriteFilesResponseSchema,
+		WriteFilesRequestSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return {
+			filesWritten: resp.data?.filesWritten ?? resp.filesWritten ?? 0,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}
+
+export interface ReadFileParams {
+	sandboxId: string;
+	path: string;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Reads a file from a sandbox workspace.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and file path
+ * @returns A ReadableStream of the file contents
+ * @throws {SandboxResponseError} If the read request fails
+ */
+export async function sandboxReadFile(
+	client: APIClient,
+	params: ReadFileParams
+): Promise<ReadableStream<Uint8Array>> {
+	const { sandboxId, path, orgId, signal } = params;
+
+	const queryParams = new URLSearchParams();
+	queryParams.set('path', path);
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/fs/${API_VERSION}/${sandboxId}?${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 read file: ${response.status} ${text}`,
+			sandboxId,
+		});
+	}
+
+	if (!response.body) {
+		throw new SandboxResponseError({
+			message: 'No response body',
+			sandboxId,
+		});
+	}
+
+	return response.body;
+}

package/src/api/sandbox/get.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import type { SandboxInfo, SandboxStatus } from '@agentuity/core';
+
+const SandboxInfoDataSchema = z
+	.object({
+		sandboxId: z.string().describe('Unique identifier for the sandbox'),
+		status: z
+			.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+			.describe('Current status of the sandbox'),
+		createdAt: z.string().describe('ISO timestamp when the sandbox was created'),
+		region: z.string().optional().describe('Region where the sandbox is running'),
+		snapshotId: z.string().optional().describe('Snapshot ID this sandbox was created from'),
+		snapshotTag: z.string().optional().describe('Snapshot tag this sandbox was created from'),
+		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'),
+		dependencies: z
+			.array(z.string())
+			.optional()
+			.describe('Apt packages installed in the sandbox'),
+	})
+	.describe('Detailed information about a sandbox');
+
+const SandboxGetResponseSchema = APIResponseSchema(SandboxInfoDataSchema);
+
+export interface SandboxGetParams {
+	sandboxId: string;
+	orgId?: string;
+}
+
+/**
+ * Retrieves information about a specific sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID
+ * @returns Sandbox information including status, creation time, and execution count
+ * @throws {SandboxResponseError} If the sandbox is not found or request fails
+ */
+export async function sandboxGet(
+	client: APIClient,
+	params: SandboxGetParams
+): Promise<SandboxInfo> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof SandboxGetResponseSchema>>(
+		url,
+		SandboxGetResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			sandboxId: resp.data.sandboxId,
+			status: resp.data.status as SandboxStatus,
+			createdAt: resp.data.createdAt,
+			region: resp.data.region,
+			snapshotId: resp.data.snapshotId,
+			snapshotTag: resp.data.snapshotTag,
+			executions: resp.data.executions,
+			stdoutStreamUrl: resp.data.stdoutStreamUrl,
+			stderrStreamUrl: resp.data.stderrStreamUrl,
+			dependencies: resp.data.dependencies,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message, sandboxId });
+}