@struktoai/mirage-core/dist/runtime/wasm/fs.d.ts

A Unified Virtual Filesystem For AI Agents

import type { OpenMode } from '../handles/mode.ts';
import type { VFSStat } from '../types.ts';
/**
 * One open file the run's view handed out, answered by the host: the
 * guest's twin of the `Descriptor` it holds there, each call made
 * synchronously across the bridge.
 */
export interface GuestFile {
    readonly mode: OpenMode;
    /** The path it was opened at. */
    readonly opened: string;
    /** Where the links on `opened` led as it opened, which names its inode. */
    readonly inode: string;
    /** The path its file has now; a rename moves it. */
    path(): string;
    position(): number;
    size(): number;
    read(size: number): Uint8Array;
    pread(offset: number, size: number): Uint8Array;
    write(data: Uint8Array): void;
    pwrite(offset: number, data: Uint8Array): void;
    seek(offset: number, whence: number): number | null;
    truncate(size: number): void;
    land(): void;
    close(): void;
    /** The core's row for it, the size it holds counted. */
    fstat(): VFSStat;
    /** Whether the name its file had went, so the file has no link left. */
    unlinked(): boolean;
}
/** The run's `WasmView`, answered synchronously across the bridge. */
export interface GuestView {
    stat(path: string): VFSStat;
    lstat(path: string): VFSStat;
    statOrNull(path: string, nofollow?: boolean): VFSStat | null;
    open(path: string, mode: OpenMode): GuestFile;
    unlink(path: string): void;
    mkdir(path: string): void;
    rmdir(path: string): void;
    rename(src: string, dst: string): void;
    symlink(path: string, target: string): void;
    walked(path: string, follow?: boolean): string;
    readlink(path: string): string;
    setattr(path: string, atime: string | null, mtime: string | null, nofollow: boolean): void;
    readdir(path: string): [string, number][];
}
/** What ends a guest from inside a host call: `proc_exit`, or a stop met
 * while the guest waited. The run's caller catches it out of `_start`. */
export declare class GuestExit extends Error {
    readonly code: number;
    constructor(code: number);
}
/**
 * Preview1 host functions over the run's view. One per run: it owns the
 * guest fd table (stdin, stdout and stderr plus one preopen at "/"),
 * keeps each open file's writes on the host until its close (or the
 * guest's exit), and translates the preview1 ABI (iovecs, filestats,
 * dirents) for the view. Mirrors Python's `WasiFs`, the args, environment
 * and clock calls included, which wasmtime serves natively there.
 *
 * @param fs - the files the guest sees.
 * @param stdin - reads the guest's input as a pipe does; null gives it none.
 * @param output - takes each stdout or stderr write as the guest makes it,
 *   the guest waiting until it is taken; false once its reader has gone.
 * @param wait - holds the guest for a poll's delay; true when the run was
 *   stopped while it waited.
 * @param argv - the guest's argv, its program name first.
 * @param env - its environment as `NAME=value` entries.
 */
export declare class WasiFs {
    private readonly fs;
    private readonly output;
    private readonly wait;
    private readonly argv;
    private readonly env;
    private readonly offset;
    exitCode: number | null;
    memory: WebAssembly.Memory | null;
    private readonly fds;
    constructor(fs: GuestView, stdin: ((size: number) => Uint8Array) | null, output: (fd: 1 | 2, bytes: Uint8Array) => boolean, wait: (ms: number) => boolean, argv: readonly string[], env: readonly string[], offset?: number);
    private bytes;
    private data;
    private load;
    private store;
    private storeU32;
    private storeU64;
    private iovs;
    private pathArg;
    /** The entry under `fd` when it reads: a file's, or stdin. */
    private readableEntry;
    /** The mount file under `fd` when its open asked to write. */
    private writer;
    proc_exit(code: number): never;
    private strings;
    private sizes;
    args_get(ptrs: number, buf: number): number;
    args_sizes_get(count: number, size: number): number;
    environ_get(ptrs: number, buf: number): number;
    environ_sizes_get(count: number, size: number): number;
    random_get(ptr: number, length: number): number;
    sched_yield(): number;
    clock_time_get(clock: number, _precision: bigint, result: number): number;
    private now;
    clock_res_get(clock: number, result: number): number;
    poll_oneoff(incoming: number, outgoing: number, count: number, nevents: number): number;
    fd_prestat_get(fd: number, buf: number): number;
    fd_prestat_dir_name(fd: number, ptr: number, length: number): number;
    path_open(dirfd: number, dirflags: number, ptr: number, length: number, oflags: number, rightsBase: bigint, _rightsInherit: bigint, fdflags: number, out: number): number;
    private openDir;
    fd_close(fd: number): number;
    /**
     * Send what every file the guest left open still owes the mount. A
     * process's writes are in its files whether or not it closed them, so
     * the guest's exit flushes each open file the way a close would. One
     * that fails does not stop the rest.
     *
     * @returns one line per file whose writes could not land.
     */
    closeAll(): string[];
    fd_renumber(fd: number, to: number): number;
    private scatter;
    fd_read(fd: number, iovs: number, count: number, nread: number): number;
    fd_pread(fd: number, iovs: number, count: number, offset: bigint, nread: number): number;
    fd_write(fd: number, iovs: number, count: number, nwritten: number): number;
    fd_pwrite(fd: number, iovs: number, count: number, offset: bigint, nwritten: number): number;
    fd_seek(fd: number, offset: bigint, whence: number, out: number): number;
    fd_tell(fd: number, out: number): number;
    fd_fdstat_get(fd: number, buf: number): number;
    fd_filestat_get(fd: number, buf: number): number;
    path_filestat_get(dirfd: number, flags: number, ptr: number, length: number, buf: number): number;
    fd_filestat_set_size(fd: number, size: bigint): number;
    fd_readdir(fd: number, buf: number, bufLen: number, cookie: bigint, used: number): number;
    path_unlink_file(dirfd: number, ptr: number, length: number): number;
    path_create_directory(dirfd: number, ptr: number, length: number): number;
    path_remove_directory(dirfd: number, ptr: number, length: number): number;
    path_rename(dirfd: number, ptr: number, length: number, dstDirfd: number, dstPtr: number, dstLength: number): number;
    fd_advise(): number;
    fd_datasync(fd: number): number;
    fd_sync(fd: number): number;
    fd_fdstat_set_flags(): number;
    /** Store the stamps a utimensat-shaped call selects. */
    private setTimes;
    fd_filestat_set_times(fd: number, atim: bigint, mtim: bigint, flags: number): number;
    path_filestat_set_times(dirfd: number, flags: number, ptr: number, length: number, atim: bigint, mtim: bigint, fstFlags: number): number;
    path_readlink(dirfd: number, ptr: number, length: number, buf: number, bufLen: number, used: number): number;
    path_link(): number;
    path_symlink(oldPtr: number, oldLength: number, dirfd: number, newPtr: number, newLength: number): number;
}
/**
 * The guest's preview1 imports over one run's `WasiFs`, each mapping a
 * failure to a guest errno. Filesystem-shaped errors get their own errno;
 * anything else, a backend's upstream error on one record most often, is
 * EIO: a syscall has no other channel to say it failed. A `GuestExit`
 * passes through, so it ends `_start`. Mirrors Python's `install_wasi_fs`.
 *
 * @param wasi - the run's host-function table.
 */
export declare function wasiImports(wasi: WasiFs): WebAssembly.Imports;
//# sourceMappingURL=fs.d.ts.map