agent.utils.files

exists(path: string): boolean

if (agent.utils.files.exists("/sdcard/Download/data.json")) {
  const content = agent.utils.files.readFullFile("/sdcard/Download/data.json");
}

getSize(filePath: string): number

const size = agent.utils.files.getSize("/sdcard/video.mp4");

getStorageRoot(): string

const root = agent.utils.files.getStorageRoot();
const downloadPath = root + "/Download";

readFullFile(filePath: string): string

const config = agent.utils.files.readFullFile("/sdcard/config.json");
const data = JSON.parse(config);

readFullFileBase64(filePath: string): string

const imageBase64 = agent.utils.files.readFullFileBase64("/sdcard/DCIM/photo.jpg");
const ocrResult = await agent.actions.recognizeText(imageBase64);

readFileAsBlob(filePath: string, mimeType?: string): Blob | null

const imageBlob = agent.utils.files.readFileAsBlob("/sdcard/image.png", "image/png");

openStream(filePath: string): string

const streamId = agent.utils.files.openStream("/sdcard/large_file.bin");
let chunk;
while ((chunk = agent.utils.files.readChunk(streamId, 1024 * 1024)).length > 0) {
  // Process chunk...
}
agent.utils.files.closeStream(streamId);

readChunk(streamId: string, chunkSize: number): number[]

closeStream(streamId: string): void

list(dirPath: string): FileInfo[]

const files = agent.utils.files.list("/sdcard/Download");
for (const file of files) {
  console.log(file.name, file.isDirectory ? "(dir)" : file.size + " bytes");
}

getPathInfo(path: string): DirectoryInfo | FilePathInfo | PathNotFoundInfo

const info = agent.utils.files.getPathInfo("/sdcard/Download");
if (info.exists && info.isDirectory) {
  console.log("Contains", info.totalItems, "items");
}

deleteFile(path: string): boolean

const deleted = agent.utils.files.deleteFile("/sdcard/Download/temp.txt");
if (deleted) console.log("File deleted");

deleteDir(path: string): boolean

const deleted = agent.utils.files.deleteDir("/sdcard/Download/temp_folder");
if (deleted) console.log("Directory and all contents deleted");

rename(oldPath: string, newPath: string): boolean

// Rename a file
agent.utils.files.rename("/sdcard/Download/old.txt", "/sdcard/Download/new.txt");

// Move a file to another directory
agent.utils.files.rename("/sdcard/Download/photo.jpg", "/sdcard/Pictures/photo.jpg");

// Rename a directory
agent.utils.files.rename("/sdcard/Download/old_folder", "/sdcard/Download/new_folder");

getDirPath(type: "Download" | "Movies" | "Music" | "Pictures" | "DCIM" | "Documents" | "Ringtones" | "Alarms" | "Notifications" | "Podcasts"): string

const downloadDir = agent.utils.files.getDirPath("Download");
const files = agent.utils.files.list(downloadDir);
const musicDir = agent.utils.files.getDirPath("Music");

startDownload(url: string, localPath: string, options?: DownloadRequestOptions): string

const downloadDir = agent.utils.files.getDirPath("Download");
const id = agent.utils.files.startDownload(
  "https://example.com/large-file.zip",
  downloadDir + "/large-file.zip"
);

let status;
do {
  await sleep(1000);
  status = agent.utils.files.getDownloadStatus(id);
  if (status.totalBytes > 0) {
    const percent = Math.round((status.bytesDownloaded / status.totalBytes) * 100);
    console.log("Progress:", percent + "%");
  }
} while (status.status === "downloading");

if (status.status === "success") {
  console.log("Downloaded to:", status.filePath, "Size:", status.fileSize);
} else {
  console.error("Failed:", status.error);
}

const id = agent.utils.files.startDownload(
  "https://api.example.com/export",
  "/sdcard/Download/export.csv",
  {
    method: "POST",
    headers: { "Authorization": "Bearer my-token", "Content-Type": "application/json" },
    body: JSON.stringify({ format: "csv", dateRange: "last30days" }),
  }
);

getDownloadStatus(id: string): DownloadStatusInfo

const status = agent.utils.files.getDownloadStatus(downloadId);
console.log("Status:", status.status);
console.log("Progress:", status.bytesDownloaded, "/", status.totalBytes);

retryDownload(id: string): boolean

const status = agent.utils.files.getDownloadStatus(downloadId);
if (status.status === "failed") {
  const retried = agent.utils.files.retryDownload(downloadId);
  if (retried) console.log("Retrying...");
}

fetch2(url: string, options?: Fetch2Options): Promise<{ success: true; content: string | Blob | Uint8Array; size: number } | { success: false; error: string }>

const result = await agent.utils.fetch2("https://example.com/data.json");
if (result.success) {
  const data = JSON.parse(result.content as string);
  console.log("Downloaded", result.size, "bytes");
}

const result = await agent.utils.fetch2("https://example.com/image.png", { readAs: "base64" });
if (result.success) {
  await agent.utils.uploadTempFile("image.png", result.content as string);
}

const result = await agent.utils.fetch2("https://api.example.com/export", {
  readAs: "text",
  method: "POST",
  headers: { "Authorization": "Bearer my-token" },
  body: JSON.stringify({ format: "csv" }),
  timeoutMs: 60_000,
  maxRetries: 3,
});
if (!result.success) console.error("Download failed:", result.error);

getHashes(filePath: string): FileHashes | FileHashError

const hashes = agent.utils.files.getHashes("/sdcard/download.apk");
if (!("error" in hashes)) {
  console.log("MD5:", hashes.md5);
  console.log("SHA-256:", hashes.sha256);
}

uploadTempFile(filename: string, base64Data: string): Promise<UploadTempFileResult | { success: false; error: string }>

const screenshot = await agent.actions.screenshot(1080, 1920, 80);
if (screenshot.screenshot) {
  const result = await agent.utils.uploadTempFile("screenshot.jpg", screenshot.screenshot);
  if (result.success) {
    console.log("File URL:", result.data.url);
    console.log("Expires at:", result.data.expiresAt);
  } else {
    console.error("Upload failed:", result.error);
  }
}

const jsonData = JSON.stringify({ results: [1, 2, 3] });
const base64 = btoa(jsonData);

const result = await agent.utils.uploadTempFile("results.json", base64);
if (result.success) console.log("Uploaded to:", result.data.url);

uploadTempFile(localFilePath: string): Promise<UploadTempFileResult | { success: false; error: string }>

const result = await agent.utils.uploadTempFile("/sdcard/Download/report.pdf");

if (result.success) {
  console.log("Uploaded:", result.data.originalName);
  console.log("Size:", result.data.size, "bytes");
  console.log("URL:", result.data.url);
} else {
  console.error("Upload failed:", result.error);
}

const imagePath = "/sdcard/DCIM/Camera/photo.jpg";

if (agent.utils.files.exists(imagePath)) {
  const result = await agent.utils.uploadTempFile(imagePath);
  if (result.success) {
    await agent.utils.job.submitTask("success", { imageUrl: result.data.url }, true, []);
  }
}

base64ToBytes(base64: string): Uint8Array

bytesToBlob(bytes: number[] | Uint8Array, mimeType?: string): Blob | null