@temporalio/agent-harness 0.0.0-stage → 0.2.0

package/dist/src/harness/code-mode/vfs.d.ts

@@ -0,0 +1,209 @@
+import { ApplicationFailure } from "@temporalio/workflow";
+import { z } from "zod";
+import { type AnyHarnessTool } from "../agent.ts";
+import type { StateRef } from "../state/index.ts";
+/** What a backend reports about one path. */
+export interface FileStat {
+    is_dir: boolean;
+    size?: number;
+    /** Unix seconds. Absent until a stat says; `0` is treated as unknown by an index. */
+    mtime?: number;
+}
+/**
+ * Storage behind a `Mount`. Methods are awaited in workflow code, so their bodies must be
+ * workflow-safe. Paths are relative to the mount and normalized; the mount's root is ".". Throw
+ * `osError(...)` for failures; from an activity, throw an `ApplicationFailure` whose `type` is the
+ * built-in name (`FileNotFoundError`, ...), and the script sees the built-in exception.
+ * `write`, `mkdir`, `delete` and `rename` are only needed for a writable mount.
+ */
+export interface FileSystem {
+    stat(path: string): Promise<FileStat | null>;
+    read(path: string): Promise<Uint8Array>;
+    list(path: string): Promise<string[]>;
+    write?(path: string, data: Uint8Array): Promise<void>;
+    mkdir?(path: string): Promise<void>;
+    delete?(path: string): Promise<void>;
+    rename?(path: string, target: string): Promise<void>;
+}
+export declare const ROOT = ".";
+/** The Python `OSError` subclasses a failed file operation raises inside the script. */
+export type OsErrorType = "OSError" | "FileNotFoundError" | "FileExistsError" | "IsADirectoryError" | "NotADirectoryError" | "PermissionError";
+/** A failure the script sees as the built-in `type`, with Python's message for `errno` and `path`. */
+export declare function osError(type: OsErrorType, errno: number, path: string, strerror?: string): ApplicationFailure;
+/**
+ * An OS error thrown by activity filesystem code (disk, a walk). The activity wrapper turns it
+ * into an `ApplicationFailure` the script sees as the built-in of the same name.
+ */
+export declare class FsError extends Error {
+    readonly fsType: OsErrorType;
+    readonly errno: number;
+    readonly strerror: string;
+    readonly path: string;
+    constructor(fsType: OsErrorType, errno: number, strerror: string, path: string);
+}
+/**
+ * A `FileSystem` at a virtual path inside the sandbox. `path` is absolute and normalized
+ * (`/skills`, not `/skills/`). `readOnly` is enforced before any backend call. `description` is
+ * shown to the model next to the mount, so say what is there and how to use it.
+ */
+export declare class Mount {
+    readonly path: string;
+    readonly backend: FileSystem;
+    readonly readOnly: boolean;
+    readonly description: string;
+    /** Set for an activity-backed mount, so successful operations update its FileIndex. */
+    readonly tracked: IndexTrack | null;
+    constructor(path: string, backend: FileSystem, { readOnly, description, tracked, }?: {
+        readOnly?: boolean;
+        description?: string;
+        tracked?: IndexTrack | null;
+    });
+}
+/** Reject mounts that repeat or nest, so every path belongs to at most one mount. */
+export declare function validateMounts(mounts: readonly Mount[]): readonly Mount[];
+/** The mount `path` falls in and the path relative to it, matching whole segments; null outside every mount. */
+export declare function route(mounts: readonly Mount[], path: string): {
+    mount: Mount;
+    relative: string;
+} | null;
+/** Monty's file operations. Every other OS call (clock, entropy, environment) is not a file one. */
+export declare const FILE_OPERATIONS: Set<string>;
+/** Bytes as they cross an activity boundary. */
+export interface EncodedBytes {
+    __monty__: "bytes";
+    base64: string;
+}
+/** An `open` that succeeded: the worker answers it with a Monty file handle. */
+export interface OpenedFile {
+    __monty__: "handle";
+    path: string;
+    mode: string;
+}
+/** A file operation the workflow leaves to Monty's default: the error for an unavailable OS call. */
+export interface NotHandled {
+    __monty__: "not_handled";
+}
+export declare const encodeBytes: (data: Uint8Array) => EncodedBytes;
+/** The file operation a script's step stopped at, as the worker hands it over. */
+export interface FileOpCall {
+    call_id: number;
+    operation: string;
+    /** The script's absolute path. */
+    path: string;
+    /** The operation's remaining arguments: the data of a write, the mode of an `open`, a rename's destination. */
+    args: unknown[];
+    kwargs: Record<string, unknown>;
+}
+/** Runs one fs_* tool against a mount's backend, through the runner. */
+export type CallFsTool = (tool: AnyHarnessTool, input: Record<string, unknown>, backend: FileSystem) => Promise<unknown>;
+/**
+ * What the script's file operation returns (encoded for the worker), or the failure it raises.
+ * Routing, read-only mounts and renames across mounts are decided here, before any backend call.
+ * A backend's error that names a mount-relative path is raised naming the virtual path instead.
+ */
+export declare function performFileOp(mounts: readonly Mount[], op: FileOpCall, call: CallFsTool): Promise<unknown>;
+/**
+ * An `InMemoryFileSystem`'s files as agent state: `files` keyed by mount-relative path
+ * (`"notes/todo.md"`), and `directories` lists every directory except the mount's root. Declare
+ * it with `states: { workspace: state(FileTree) }` and pass the ref as
+ * `new InMemoryFileSystem({ state })`: the files then live in the state, and every change to them
+ * is published as a state patch.
+ */
+export declare const FileTree: z.ZodObject<{
+    files: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        content: z.ZodString;
+        encoding: z.ZodDefault<z.ZodEnum<{
+            base64: "base64";
+            "utf-8": "utf-8";
+        }>>;
+        size: z.ZodNumber;
+    }, z.core.$strip>>>;
+    directories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FileTree = z.output<typeof FileTree>;
+/** The initial files of an `InMemoryFileSystem`, as `{ mount-relative path: content }`. */
+export type Seed = () => Promise<Record<string, string | Uint8Array>>;
+/**
+ * A `FileSystem` held in workflow memory. Build it in `create`, so each workflow gets its own; its
+ * files then last across the run's scripts, and replay rebuilds them. A continue-as-new carries
+ * only declared states, so without `state` the next run starts empty and seeds again.
+ *
+ * `seed` runs in workflow code, once, before the first operation on the mount, and returns the
+ * initial files. Load files from disk inside an activity the seed awaits: the activity's result is
+ * recorded, so a running workflow keeps the files it seeded even after a deploy changes them.
+ * `maxBytes` caps the total size of the files, seeded ones included.
+ *
+ * `state` (opt-in) keeps the files in a declared `FileTree` state instead, so every change is
+ * published as a state patch the UI can show. A patch carries each written file whole, and anyone
+ * who can view the session sees the files, so track only filesystems whose files are worth
+ * streaming to every viewer.
+ */
+export declare class InMemoryFileSystem<T extends {
+    files: FileTree["files"];
+    directories: string[];
+} = FileTree> implements Required<FileSystem> {
+    #private;
+    constructor({ seed, maxBytes, state, }?: {
+        seed?: Seed;
+        maxBytes?: number;
+        state?: StateRef<T>;
+    });
+    get needsSeed(): boolean;
+    /** Run the seed and load its files, as one change. Called by the fs_seed tool. */
+    seedNow(): Promise<[count: number, bytes: number]>;
+    stat(path: string): Promise<FileStat | null>;
+    read(path: string): Promise<Uint8Array>;
+    list(path: string): Promise<string[]>;
+    write(path: string, data: Uint8Array): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    delete(path: string): Promise<void>;
+    rename(path: string, target: string): Promise<void>;
+}
+export declare const IndexEntry: z.ZodObject<{
+    is_dir: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
+    size: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    mtime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    writes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type IndexEntry = z.output<typeof IndexEntry>;
+export declare const IndexSource: z.ZodObject<{
+    filesystem: z.ZodString;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    task_queue: z.ZodString;
+}, z.core.$strip>;
+export type IndexSource = z.output<typeof IndexSource>;
+export declare const FileIndex: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodLiteral<"file_index">>;
+    mount: z.ZodDefault<z.ZodString>;
+    description: z.ZodDefault<z.ZodString>;
+    read_only: z.ZodDefault<z.ZodBoolean>;
+    okf_version: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        filesystem: z.ZodString;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        task_queue: z.ZodString;
+    }, z.core.$strip>>>;
+    entries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        is_dir: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
+        size: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        mtime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        writes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type FileIndex = z.output<typeof FileIndex>;
+/** Where an activity-backed mount's files live, before the task queue is known. */
+export interface FileSource {
+    filesystem: string;
+    config: Record<string, unknown>;
+}
+/** Records successful mount operations. A no-op change publishes nothing. */
+export interface IndexTrack {
+    noteStat(path: string, found: FileStat | null): void;
+    noteRead(path: string, size: number): void;
+    noteList(path: string, names: readonly string[]): void;
+    noteWrite(path: string, size: number): void;
+    noteMkdir(path: string): void;
+    noteRemove(path: string): void;
+    noteRename(path: string, target: string): void;
+}
+export declare function indexTrack(ref: StateRef<FileIndex>, source: FileSource): IndexTrack;