@theokit/sdk 2.27.0 → 2.29.0

package/dist/filesystem/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Filesystem backend protocol — a pluggable file *storage* provider for agent
+ * tools, the storage-side twin of {@link SandboxBackend} (execution-side).
+ *
+ * SE31 (Mastra Workspaces comparison). Mirrors `SandboxBackend`'s shape: a small
+ * set of abstract methods (`readFile` / `writeFile` / `stat` / `list`) with
+ * `exists()` derived on the base class, a boundary `basePath`, a `readOnly`
+ * flag, and typed errors. Unlike `SandboxBackend` (whose file ops shell out via
+ * `execute`, requiring command execution and giving NO structured `stat`), a
+ * `FilesystemBackend` serves a *filesystem-only* workspace with no sandbox and
+ * exposes a real `stat().mtimeMs` — the primitive SE32's read-before-write
+ * safety compares against. See ADR 0011.
+ *
+ * New backends (S3, GCS, in-memory) implement the four abstract methods; higher
+ * level helpers derive on the base. This is the backend *seam* — it does NOT
+ * ship agent-facing tools nor a bundled workspace (bring-your-own-tools stands).
+ *
+ * @public
+ */
+/** Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32). */
+export interface FileStat {
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+}
+/** Options a write may carry. SE32 adds `expectedMtime` (stale-write guard). */
+export interface WriteFileOptions {
+    /**
+     * SE32 — when set, the write fails with {@link StaleFileError} if the file's
+     * current `mtimeMs` differs (someone changed it since it was last read).
+     */
+    readonly expectedMtime?: number;
+}
+export interface FilesystemConfig {
+    /** Boundary root. Every path is resolved within it; escapes are rejected. */
+    readonly basePath?: string;
+    /** When true, every write throws {@link FilesystemReadOnlyError}. */
+    readonly readOnly?: boolean;
+}
+/** A path escaped the backend's `basePath` (traversal or symlink). */
+export declare class FilesystemSecurityError extends Error {
+    readonly code: "filesystem_security";
+    constructor(message: string);
+}
+/** A write was attempted on a read-only backend. */
+export declare class FilesystemReadOnlyError extends Error {
+    readonly code: "filesystem_readonly";
+    constructor(message: string);
+}
+/** A read/stat targeted a path that does not exist. */
+export declare class FileNotFoundError extends Error {
+    readonly path: string;
+    readonly code: "filesystem_not_found";
+    constructor(path: string);
+}
+/**
+ * A filesystem I/O operation failed for a reason other than not-found /
+ * read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or
+ * `EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,
+ * untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).
+ */
+export declare class FilesystemError extends Error {
+    readonly path: string;
+    readonly code: "filesystem_io";
+    constructor(path: string, cause: unknown);
+}
+/**
+ * SE32 — a write's `expectedMtime` did not match the file's current mtime: the
+ * file changed since it was last read, so the write would silently clobber.
+ */
+export declare class StaleFileError extends Error {
+    readonly path: string;
+    readonly expectedMtime: number;
+    readonly actualMtime: number;
+    readonly code: "filesystem_stale";
+    constructor(path: string, expectedMtime: number, actualMtime: number);
+}
+/**
+ * Pluggable filesystem backend. Implement the four abstract methods; `exists()`
+ * and the `readOnly`/`basePath` accessors derive on the base class.
+ *
+ * @public
+ */
+export declare abstract class FilesystemBackend {
+    protected readonly _basePath: string;
+    protected readonly _readOnly: boolean;
+    constructor(config?: FilesystemConfig);
+    /** Read a boundary-relative file as UTF-8. Throws {@link FileNotFoundError}. */
+    abstract readFile(path: string): Promise<string>;
+    /**
+     * Write UTF-8 content to a boundary-relative path (creating parents). Returns
+     * the new {@link FileStat}. Throws {@link FilesystemReadOnlyError} on a
+     * read-only backend and {@link StaleFileError} when `opts.expectedMtime`
+     * mismatches (SE32).
+     */
+    abstract writeFile(path: string, content: string, opts?: WriteFileOptions): Promise<FileStat>;
+    /** Structured metadata for a path. Throws {@link FileNotFoundError}. */
+    abstract stat(path: string): Promise<FileStat>;
+    /** Directory entry names (not recursive). Throws {@link FileNotFoundError}. */
+    abstract list(path: string): Promise<string[]>;
+    /** Derived — true iff `stat(path)` resolves (absent ⇒ false). */
+    exists(path: string): Promise<boolean>;
+    /** Throw {@link FilesystemReadOnlyError} when the backend is read-only. */
+    protected assertWritable(): void;
+    get readOnly(): boolean;
+    get basePath(): string;
+}
+/**
+ * A backend OR a per-request resolver of one. A resolver runs at tool-execution
+ * time (the request scope), so multi-tenant / multi-role agents get a distinct
+ * root or permission set per request without a shared mutable backend.
+ *
+ * @public
+ */
+export type FilesystemProvider<Ctx = unknown> = FilesystemBackend | ((ctx: Ctx) => FilesystemBackend | Promise<FilesystemBackend>);
+/** Resolve a {@link FilesystemProvider} to a concrete backend for `ctx`. */
+export declare function resolveFilesystem<Ctx>(provider: FilesystemProvider<Ctx>, ctx: Ctx): Promise<FilesystemBackend>;