Reference

import { fs, QuotaExceeded, WorkspaceLost, NoWorkspace } from "urai:fs";

Methods

Every method that touches a file returns a promise. When no filesystem is attached, these methods throw NoWorkspace.

Workspace

Method	Returns	Notes
`available()`	`boolean`	Whether this execution has a filesystem. Never throws.
`workspace()`	`string \| null`	The id of the attached workspace, which is the thread id.
`usage()`	`Usage \| null`	Current usage and limits. `null` when no filesystem is attached.
`flush()`	`Promise<void>`	Saves all writes to durable storage, and confirms that this execution still owns the workspace.

Read

Method	Returns	Notes
`read(path)`	`Promise<Uint8Array>`	Raw bytes. Use it for images and other binary files.
`readText(path)`	`Promise<string>`	UTF-8. Invalid bytes become U+FFFD.
`readJSON<T>(path)`	`Promise<T>`	Parses the file. The parse error names the file.
`decode(bytes)`	`string`	Decodes a `Uint8Array` as UTF-8. It does not touch the filesystem.

Write

Method	Returns	Notes
`write(path, data)`	`Promise<void>`	`data` is a `Uint8Array`. Creates parent folders and replaces the file.
`writeText(path, text)`	`Promise<void>`	Writes UTF-8.
`writeJSON(path, value)`	`Promise<void>`	Writes JSON with an indent of 2 spaces.
`append(path, data)`	`Promise<void>`	`data` is a `string` or a `Uint8Array`. Creates the file when it does not exist.
`appendLine(path, line)`	`Promise<void>`	Adds `\n` when `line` does not end with one.

Files and folders

Method	Returns	Notes
`exists(path)`	`Promise<boolean>`	`true` for a file, a folder, or a symlink.
`stat(path)`	`Promise<FileInfo>`	Throws when the path does not exist.
`list(path)`	`Promise<DirEntry[]>`	Direct children of a folder, sorted by name.
`glob(pattern)`	`Promise<GlobHit[]>`	Files that match a gitignore-style pattern, such as `*/.json` or `/uploads/*.csv`. Folders are not returned.
`mkdir(path)`	`Promise<void>`	Creates the folder and its parents. Does nothing when the folder exists. Throws when a file has that path.
`remove(path, opts?)`	`Promise<void>`	Removes one file. Pass `{ recursive: true }` to remove a folder and its contents. Refuses the root folder.

Types

FileInfo

Field	Type	Notes
`size`	`number`	Size in bytes.
`kind`	`"file" \| "dir" \| "symlink"`
`mtime`	`number`	Modification time, in milliseconds since the epoch. Pass it to `new Date()`.
`mode`	`number`	Unix permission bits.

DirEntry

Field	Type
`name`	`string`
`kind`	`"file" \| "dir" \| "symlink"`

GlobHit

Field	Type	Notes
`path`	`string`	Full path from the workspace root.
`size`	`number`	Size in bytes.
`mtime`	`number`	Milliseconds since the epoch.

Usage

Field	Type	Notes
`bytes`	`number`	Bytes used by all files.
`files`	`number`	Number of files.
`maxBytes`	`number`	Limit on `bytes`.
`maxFileBytes`	`number`	Limit on the size of one file.
`maxFiles`	`number`	Limit on `files`.

Errors

Class	Thrown when	Retry
`NoWorkspace`	No filesystem is attached to this execution.	No. Check `available()`.
`QuotaExceeded`	A write goes over the total size, the file size, or the file count. Nothing was written.	After you write less or remove files.
`WorkspaceLost`	Another process owns the workspace, and Urai is stopping this execution.	No.

All other failures throw a plain Error with a message. Examples are a missing file, a path that contains .., remove on a folder without recursive, and a pattern that glob cannot parse.

Paths

Rule	Value
Root	The workspace root. A path without a leading `/` starts at the root.
`..`	Refused.
Length of one path part	255 bytes

Limits

Limit	Default
Total size of files	512 MiB
Size of one file	64 MiB
Number of files	20,000

Where the filesystem is attached

Execution	Filesystem
A script that an advanced agent runs with `execute`, in the Urai interface, the chat widget, or the Agents API	The thread’s workspace
A library imported by that script	The thread’s workspace
A tool called through the Chat Completions API	None
A workflow step	None
`uraijs eval`	A local workspace in `.urai/workspace/`
`uraijs call`, `dev`, `test`, `workflow run`	None

CLI

Flag on `uraijs eval`	Purpose
`--workspace <name>`	The local workspace to use. The default is `local`.
`-d`, `--work-dir <path>`	The directory that holds `.urai/workspace/`. The default is the current directory.

The CLI reads these environment variables to set the local limits:

Variable	Default
`URAIJS_FS_MAX_WORKSPACE_BYTES`	`536870912`
`URAIJS_FS_MAX_FILE_BYTES`	`67108864`
`URAIJS_FS_MAX_FILES`	`20000`