File Operations

Utils

Read, write, list, and manage files on the device

Access file operations through agent.utils.files. Comprehensive file system access for automations.

AgentFiles Interface

TypeScript

interface AgentFiles {
  exists(path: string): boolean;
  getSize(filePath: string): number;
  readFullFileBase64(filePath: string): string;
  readFullFile(filePath: string): string;
  openStream(filePath: string): string;
  readChunk(streamId: string, chunkSize: number): number[];
  closeStream(streamId: string): void;
  list(dirPath: string): FileInfo[];
  getPathInfo(path: string): DirectoryInfo | FilePathInfo | PathNotFoundInfo;
  getStorageRoot(): string;
  getHashes(filePath: string): FileHashes | FileHashError;
  base64ToBytes(base64: string): Uint8Array;
  bytesToBlob(bytes: number[] | Uint8Array, mimeType?: string): Blob | null;
  readFileAsBlob(filePath: string, mimeType?: string): Blob | null;
}

Basic Operations

`exists()`

TypeScript

exists(path: string): boolean

Checks if a file or directory exists at the specified path.

Parameters

Name	Type	Description
`path`	`string`	Path to check

Returns

booleantrue if the path exists

Examples

TypeScript

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

`getSize()`

TypeScript

getSize(filePath: string): number

Gets the size of a file in bytes.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file

Returns

numberFile size in bytes, or -1 if not found

Examples

TypeScript

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

`getStorageRoot()`

TypeScript

getStorageRoot(): string

Gets the root storage path for the device (typically '/sdcard' or '/storage/emulated/0').

Returns

stringStorage root path

Examples

TypeScript

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

Reading Files

`readFullFile()`

TypeScript

readFullFile(filePath: string): string

Reads the entire file content as UTF-8 text.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file

Returns

stringFile content as text

Examples

TypeScript

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

`readFullFileBase64()`

TypeScript

readFullFileBase64(filePath: string): string

Reads the entire file content as a Base64-encoded string. Useful for binary files.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file

Returns

stringBase64-encoded file content

Examples

TypeScript

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

`readFileAsBlob()`

TypeScript

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

Reads a file directly as a Blob object.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file
`mimeType?`	`string`	MIME type for the blob

Returns

Blob | nullBlob object or null on failure

Examples

TypeScript

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

Streaming Large Files

`openStream()`

TypeScript

openStream(filePath: string): string

Opens a file stream for reading large files in chunks.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file

Returns

stringStream ID for use with readChunk and closeStream

Examples

TypeScript

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()`

TypeScript

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

Reads a chunk of data from an open file stream.

Parameters

Name	Type	Description
`streamId`	`string`	Stream ID from openStream()
`chunkSize`	`number`	Maximum bytes to read

Returns

number[]Array of byte values (empty if end of file)

`closeStream()`

TypeScript

closeStream(streamId: string): void

Closes an open file stream.

Parameters

Name	Type	Description
`streamId`	`string`	Stream ID from openStream()

Directory Operations

`list()`

TypeScript

list(dirPath: string): FileInfo[]

Lists all files and directories in the specified directory.

Parameters

Name	Type	Description
`dirPath`	`string`	Directory path

Returns

FileInfo[]Array of file/directory information

Examples

TypeScript

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

`getPathInfo()`

TypeScript

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

Gets detailed information about a path, including whether it's a file or directory.

Parameters

Name	Type	Description
`path`	`string`	Path to check

Returns

DirectoryInfo | FilePathInfo | PathNotFoundInfoDetailed path information based on path type

Examples

TypeScript

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

File Integrity

`getHashes()`

TypeScript

getHashes(filePath: string): FileHashes | FileHashError

Calculates MD5, SHA-1, and SHA-256 hashes for a file.

Parameters

Name	Type	Description
`filePath`	`string`	Path to the file

Returns

FileHashes | FileHashErrorHash values or error

Examples

TypeScript

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

Data Conversion

`base64ToBytes()`

TypeScript

base64ToBytes(base64: string): Uint8Array

Converts a Base64-encoded string to a Uint8Array.

Parameters

Name	Type	Description
`base64`	`string`	Base64-encoded string

Returns

Uint8ArrayDecoded byte array

`bytesToBlob()`

TypeScript

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

Converts a byte array to a Blob object.

Parameters

Name	Type	Description
`bytes`	`number[] \| Uint8Array`	Byte array
`mimeType?`	`string`	MIME type for the blob

Returns

Blob | nullBlob object or null on failure

Types

FileInfo

TypeScript

interface FileInfo {
  name: string;        // File or directory name
  path: string;        // Full path
  isDirectory: boolean;
  isFile: boolean;
  size: number;        // Size in bytes (0 for directories)
  lastModified: number; // Timestamp
}

DirectoryInfo

TypeScript

interface DirectoryInfo {
  exists: true;
  path: string;
  name: string;
  isDirectory: true;
  isFile: false;
  lastModified: number;
  canRead: boolean;
  canWrite: boolean;
  fileCount: number;      // Number of files
  directoryCount: number; // Number of subdirectories
  totalItems: number;     // Total items
}

FilePathInfo

TypeScript

interface FilePathInfo {
  exists: true;
  path: string;
  name: string;
  isDirectory: false;
  isFile: true;
  lastModified: number;
  canRead: boolean;
  canWrite: boolean;
  size: number;
}

PathNotFoundInfo

TypeScript

interface PathNotFoundInfo {
  exists: false;
  error?: string;
}

FileHashes

TypeScript

interface FileHashes {
  md5: string;
  sha1: string;
  sha256: string;
  size: number;
}