zeitlich 0.2.13 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,14 +27,54 @@
         "default": "./dist/workflow.js"
       }
     },
-    "./adapters/langchain": {
+    "./adapters/thread/langchain": {
       "import": {
-        "types": "./dist/adapters/langchain/index.d.ts",
-        "default": "./dist/adapters/langchain/index.js"
+        "types": "./dist/adapters/thread/langchain/index.d.ts",
+        "default": "./dist/adapters/thread/langchain/index.js"
       },
       "require": {
-        "types": "./dist/adapters/langchain/index.d.ts",
-        "default": "./dist/adapters/langchain/index.js"
+        "types": "./dist/adapters/thread/langchain/index.d.ts",
+        "default": "./dist/adapters/thread/langchain/index.js"
+      }
+    },
+    "./adapters/thread/google-genai": {
+      "import": {
+        "types": "./dist/adapters/thread/google-genai/index.d.ts",
+        "default": "./dist/adapters/thread/google-genai/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/google-genai/index.d.ts",
+        "default": "./dist/adapters/thread/google-genai/index.js"
+      }
+    },
+    "./adapters/sandbox/inmemory": {
+      "import": {
+        "types": "./dist/adapters/sandbox/inmemory/index.d.ts",
+        "default": "./dist/adapters/sandbox/inmemory/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/inmemory/index.d.ts",
+        "default": "./dist/adapters/sandbox/inmemory/index.js"
+      }
+    },
+    "./adapters/sandbox/virtual": {
+      "import": {
+        "types": "./dist/adapters/sandbox/virtual/index.d.ts",
+        "default": "./dist/adapters/sandbox/virtual/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/virtual/index.d.ts",
+        "default": "./dist/adapters/sandbox/virtual/index.js"
+      }
+    },
+    "./adapters/sandbox/daytona": {
+      "import": {
+        "types": "./dist/adapters/sandbox/daytona/index.d.ts",
+        "default": "./dist/adapters/sandbox/daytona/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/daytona/index.d.ts",
+        "default": "./dist/adapters/sandbox/daytona/index.js"
       }
     }
   },
@@ -52,6 +92,8 @@
     "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "rm -rf dist",
     "prepare": "husky",
     "prepack": "npm run build",
@@ -78,7 +120,10 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@daytonaio/sdk": "^0.149.0",
     "@eslint/js": "^10.0.1",
+    "@google/genai": "^1.44.0",
+    "@langchain/core": "^1.1.30",
     "@temporalio/envconfig": "^1.15.0",
     "@temporalio/worker": "^1.15.0",
     "@types/node": "^25.3.3",
@@ -92,10 +137,18 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "@daytonaio/sdk": ">=0.100.0",
+    "@google/genai": "^1.43.0",
     "@langchain/core": ">=1.0.0",
     "ioredis": ">=5.0.0"
   },
   "peerDependenciesMeta": {
+    "@daytonaio/sdk": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    },
     "@langchain/core": {
       "optional": true
     }

package/src/adapters/sandbox/daytona/filesystem.ts

@@ -0,0 +1,136 @@
+import type { Sandbox as DaytonaSdkSandbox } from "@daytonaio/sdk";
+import type {
+  SandboxFileSystem,
+  DirentEntry,
+  FileStat,
+} from "../../../lib/sandbox/types";
+import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import { posix } from "node:path";
+
+/**
+ * {@link SandboxFileSystem} backed by a Daytona SDK sandbox.
+ *
+ * Maps zeitlich's filesystem interface to Daytona's `sandbox.fs` and
+ * `sandbox.process` APIs. Operations that have no direct Daytona equivalent
+ * (e.g. `appendFile`, `cp`) are composed from primitives.
+ */
+export class DaytonaSandboxFileSystem implements SandboxFileSystem {
+  constructor(private sandbox: DaytonaSdkSandbox) {}
+
+  async readFile(path: string): Promise<string> {
+    const buf = await this.sandbox.fs.downloadFile(path);
+    return buf.toString("utf-8");
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    const buf = await this.sandbox.fs.downloadFile(path);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    const buf =
+      typeof content === "string"
+        ? Buffer.from(content, "utf-8")
+        : Buffer.from(content);
+    await this.sandbox.fs.uploadFile(buf, path);
+  }
+
+  async appendFile(
+    path: string,
+    content: string | Uint8Array,
+  ): Promise<void> {
+    let existing: Buffer;
+    try {
+      existing = await this.sandbox.fs.downloadFile(path);
+    } catch {
+      return this.writeFile(path, content);
+    }
+
+    const addition =
+      typeof content === "string" ? Buffer.from(content, "utf-8") : content;
+    const merged = Buffer.concat([existing, Buffer.from(addition)]);
+    await this.sandbox.fs.uploadFile(merged, path);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await this.sandbox.fs.getFileDetails(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const info = await this.sandbox.fs.getFileDetails(path);
+    return {
+      isFile: !info.isDir,
+      isDirectory: info.isDir,
+      isSymbolicLink: false,
+      size: info.size,
+      mtime: new Date(info.modTime),
+    };
+  }
+
+  async mkdir(
+    path: string,
+    _options?: { recursive?: boolean },
+  ): Promise<void> {
+    await this.sandbox.fs.createFolder(path, "755");
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const entries = await this.sandbox.fs.listFiles(path);
+    return entries.map((e) => e.name);
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const entries = await this.sandbox.fs.listFiles(path);
+    return entries.map((e) => ({
+      name: e.name,
+      isFile: !e.isDir,
+      isDirectory: e.isDir,
+      isSymbolicLink: false,
+    }));
+  }
+
+  async rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean },
+  ): Promise<void> {
+    try {
+      await this.sandbox.fs.deleteFile(path, options?.recursive);
+    } catch (err) {
+      if (!options?.force) throw err;
+    }
+  }
+
+  async cp(
+    src: string,
+    dest: string,
+    options?: { recursive?: boolean },
+  ): Promise<void> {
+    const info = await this.sandbox.fs.getFileDetails(src);
+    if (info.isDir) {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: is a directory (use recursive): ${src}`);
+      }
+      await this.sandbox.process.executeCommand(`cp -r "${src}" "${dest}"`);
+    } else {
+      await this.sandbox.process.executeCommand(`cp "${src}" "${dest}"`);
+    }
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    await this.sandbox.fs.moveFiles(src, dest);
+  }
+
+  async readlink(_path: string): Promise<string> {
+    throw new SandboxNotSupportedError("readlink");
+  }
+
+  resolvePath(base: string, path: string): string {
+    if (posix.isAbsolute(path)) return posix.normalize(path);
+    return posix.resolve(base, path);
+  }
+}

package/src/adapters/sandbox/daytona/index.ts

@@ -0,0 +1,149 @@
+import {
+  Daytona,
+  type Sandbox as DaytonaSdkSandbox,
+} from "@daytonaio/sdk";
+import type {
+  Sandbox,
+  SandboxCapabilities,
+  SandboxCreateResult,
+  SandboxProvider,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+} from "../../../lib/sandbox/types";
+import {
+  SandboxNotFoundError,
+  SandboxNotSupportedError,
+} from "../../../lib/sandbox/types";
+import { DaytonaSandboxFileSystem } from "./filesystem";
+import type {
+  DaytonaSandbox,
+  DaytonaSandboxConfig,
+  DaytonaSandboxCreateOptions,
+} from "./types";
+
+// ============================================================================
+// DaytonaSandbox
+// ============================================================================
+
+class DaytonaSandboxImpl implements Sandbox {
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false,
+  };
+
+  readonly fs: DaytonaSandboxFileSystem;
+
+  constructor(
+    readonly id: string,
+    private sdkSandbox: DaytonaSdkSandbox,
+  ) {
+    this.fs = new DaytonaSandboxFileSystem(sdkSandbox);
+  }
+
+  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+    const response = await this.sdkSandbox.process.executeCommand(
+      command,
+      options?.cwd,
+      options?.env,
+      options?.timeout,
+    );
+
+    return {
+      exitCode: response.exitCode ?? 0,
+      stdout: response.result ?? "",
+      stderr: "",
+    };
+  }
+
+  async destroy(): Promise<void> {
+    await this.sdkSandbox.delete(60);
+  }
+}
+
+// ============================================================================
+// DaytonaSandboxProvider
+// ============================================================================
+
+export class DaytonaSandboxProvider
+  implements SandboxProvider<DaytonaSandboxCreateOptions, DaytonaSandbox>
+{
+  readonly id = "daytona";
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: false,
+  };
+
+  private client: Daytona;
+
+  constructor(config?: DaytonaSandboxConfig) {
+    this.client = new Daytona(config);
+  }
+
+  async create(
+    options?: DaytonaSandboxCreateOptions,
+  ): Promise<SandboxCreateResult> {
+    const sdkSandbox = await this.client.create(
+      {
+        language: options?.language,
+        snapshot: options?.snapshot,
+        envVars: options?.env,
+        labels: options?.labels,
+        autoStopInterval: options?.autoStopInterval,
+        autoArchiveInterval: options?.autoArchiveInterval,
+        autoDeleteInterval: options?.autoDeleteInterval,
+      },
+      { timeout: options?.timeout ?? 60 },
+    );
+
+    const sandbox = new DaytonaSandboxImpl(sdkSandbox.id, sdkSandbox);
+
+    if (options?.initialFiles) {
+      for (const [path, content] of Object.entries(options.initialFiles)) {
+        await sandbox.fs.writeFile(path, content);
+      }
+    }
+
+    return { sandbox };
+  }
+
+  async get(sandboxId: string): Promise<DaytonaSandbox> {
+    try {
+      const sdkSandbox = await this.client.get(sandboxId);
+      return new DaytonaSandboxImpl(sdkSandbox.id, sdkSandbox);
+    } catch {
+      throw new SandboxNotFoundError(sandboxId);
+    }
+  }
+
+  async destroy(sandboxId: string): Promise<void> {
+    try {
+      const sdkSandbox = await this.client.get(sandboxId);
+      await this.client.delete(sdkSandbox);
+    } catch {
+      // Already gone
+    }
+  }
+
+  async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
+    throw new SandboxNotSupportedError(
+      "snapshot (use Daytona's native snapshot API directly)",
+    );
+  }
+
+  async restore(_snapshot: SandboxSnapshot): Promise<never> {
+    throw new SandboxNotSupportedError(
+      "restore (use Daytona's native snapshot API directly)",
+    );
+  }
+}
+
+// Re-exports
+export { DaytonaSandboxFileSystem } from "./filesystem";
+export type {
+  DaytonaSandbox,
+  DaytonaSandboxConfig,
+  DaytonaSandboxCreateOptions,
+} from "./types";

package/src/adapters/sandbox/daytona/types.ts

@@ -0,0 +1,34 @@
+import type { Sandbox, SandboxCreateOptions } from "../../../lib/sandbox/types";
+import type { DaytonaSandboxFileSystem } from "./filesystem";
+
+/**
+ * A Daytona-backed {@link Sandbox} with its typed filesystem.
+ */
+export type DaytonaSandbox = Sandbox & { fs: DaytonaSandboxFileSystem };
+
+export interface DaytonaSandboxConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  target?: string;
+}
+
+export interface DaytonaSandboxCreateOptions extends SandboxCreateOptions {
+  /** Programming language runtime. Defaults to "python". */
+  language?: string;
+  /** Daytona snapshot name to create the sandbox from. */
+  snapshot?: string;
+  /** Custom Docker image to use. */
+  image?: string;
+  /** Resource allocation. */
+  resources?: { cpu?: number; memory?: number; disk?: number };
+  /** Auto-stop interval in minutes (0 = disabled). Default 15. */
+  autoStopInterval?: number;
+  /** Auto-archive interval in minutes (0 = max interval). Default 7 days. */
+  autoArchiveInterval?: number;
+  /** Auto-delete interval in minutes (negative = disabled). */
+  autoDeleteInterval?: number;
+  /** Custom labels for the sandbox. */
+  labels?: Record<string, string>;
+  /** Timeout in seconds for sandbox creation. Default 60. */
+  timeout?: number;
+}

package/src/adapters/sandbox/inmemory/index.ts

@@ -0,0 +1,213 @@
+import {
+  Bash,
+  InMemoryFs,
+  type BashOptions,
+  type IFileSystem,
+  type InitialFiles,
+} from "just-bash";
+import type {
+  Sandbox,
+  SandboxCapabilities,
+  SandboxCreateOptions,
+  SandboxCreateResult,
+  SandboxFileSystem,
+  SandboxProvider,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+  DirentEntry,
+  FileStat,
+} from "../../../lib/sandbox/types";
+import { SandboxNotFoundError } from "../../../lib/sandbox/types";
+import { getShortId } from "../../../lib/thread/id";
+
+// ============================================================================
+// Adapter: IFileSystem → SandboxFileSystem
+// ============================================================================
+
+function toSandboxFs(fs: IFileSystem): SandboxFileSystem {
+  return {
+    readFile: (path) => fs.readFile(path),
+    readFileBuffer: (path) => fs.readFileBuffer(path),
+    writeFile: (path, content) => fs.writeFile(path, content),
+    appendFile: (path, content) => fs.appendFile(path, content),
+    exists: (path) => fs.exists(path),
+    stat: async (path): Promise<FileStat> => {
+      const s = await fs.stat(path);
+      return {
+        isFile: s.isFile,
+        isDirectory: s.isDirectory,
+        isSymbolicLink: s.isSymbolicLink,
+        size: s.size,
+        mtime: s.mtime,
+      };
+    },
+    mkdir: (path, opts) => fs.mkdir(path, opts),
+    readdir: (path) => fs.readdir(path),
+    readdirWithFileTypes: async (path): Promise<DirentEntry[]> => {
+      if (!fs.readdirWithFileTypes) {
+        const names = await fs.readdir(path);
+        return Promise.all(
+          names.map(async (name) => {
+            const s = await fs.stat(`${path}/${name}`);
+            return {
+              name,
+              isFile: s.isFile,
+              isDirectory: s.isDirectory,
+              isSymbolicLink: s.isSymbolicLink,
+            };
+          })
+        );
+      }
+      return fs.readdirWithFileTypes(path);
+    },
+    rm: (path, opts) => fs.rm(path, opts),
+    cp: (src, dest, opts) => fs.cp(src, dest, opts),
+    mv: (src, dest) => fs.mv(src, dest),
+    readlink: (path) => fs.readlink(path),
+    resolvePath: (base, p) => fs.resolvePath(base, p),
+  };
+}
+
+// ============================================================================
+// InMemorySandbox
+// ============================================================================
+
+export interface InMemorySandboxOptions {
+  /** Options forwarded to `just-bash` `Bash` (minus `fs` which is managed) */
+  bashOptions?: Omit<BashOptions, "fs">;
+}
+
+/**
+ * An in-memory {@link Sandbox} backed by `just-bash`.
+ */
+export type InMemorySandbox = Sandbox & { fs: SandboxFileSystem };
+
+class InMemorySandboxImpl implements Sandbox {
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true,
+  };
+
+  readonly fs: SandboxFileSystem;
+  private bashOptions: Omit<BashOptions, "fs">;
+
+  constructor(
+    readonly id: string,
+    private justBashFs: IFileSystem,
+    options?: InMemorySandboxOptions
+  ) {
+    this.fs = toSandboxFs(justBashFs);
+    this.bashOptions = {
+      executionLimits: { maxStringLength: 52_428_800 },
+      ...options?.bashOptions,
+    };
+  }
+
+  async exec(command: string, _options?: ExecOptions): Promise<ExecResult> {
+    const bash = new Bash({ ...this.bashOptions, fs: this.justBashFs });
+    const { exitCode, stderr, stdout } = await bash.exec(command);
+    return { exitCode, stdout, stderr };
+  }
+
+  async destroy(): Promise<void> {
+    // In-memory: nothing to clean up
+  }
+
+  /** Expose the underlying IFileSystem for snapshot serialisation */
+  _getJustBashFs(): IFileSystem {
+    return this.justBashFs;
+  }
+}
+
+// ============================================================================
+// InMemorySandboxProvider
+// ============================================================================
+
+export class InMemorySandboxProvider implements SandboxProvider {
+  readonly id = "inmemory";
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true,
+  };
+
+  private sandboxes = new Map<string, InMemorySandboxImpl>();
+
+  constructor(private defaultOptions?: InMemorySandboxOptions) {}
+
+  async get(id: string): Promise<Sandbox> {
+    const sandbox = this.sandboxes.get(id);
+    if (!sandbox) throw new SandboxNotFoundError(id);
+    return sandbox;
+  }
+
+  async destroy(id: string): Promise<void> {
+    const sandbox = this.sandboxes.get(id);
+    if (sandbox) {
+      await sandbox.destroy();
+      this.sandboxes.delete(id);
+    }
+  }
+
+  async create(options?: SandboxCreateOptions): Promise<SandboxCreateResult> {
+    const id = options?.id ?? getShortId();
+    const initialFiles: InitialFiles = {};
+
+    if (options?.initialFiles) {
+      for (const [path, content] of Object.entries(options.initialFiles)) {
+        initialFiles[path] = content;
+      }
+    }
+
+    const fs = new InMemoryFs(initialFiles);
+    const sandbox = new InMemorySandboxImpl(id, fs, this.defaultOptions);
+    this.sandboxes.set(id, sandbox);
+    return { sandbox };
+  }
+
+  async snapshot(sandboxId: string): Promise<SandboxSnapshot> {
+    const sandbox = this.sandboxes.get(sandboxId);
+    if (!sandbox) throw new SandboxNotFoundError(sandboxId);
+
+    const fs = sandbox._getJustBashFs();
+    const paths = fs.getAllPaths();
+    const files: Record<string, string> = {};
+
+    for (const p of paths) {
+      try {
+        const stat = await fs.stat(p);
+        if (stat.isFile) {
+          files[p] = await fs.readFile(p);
+        }
+      } catch {
+        // skip entries that can't be read (e.g. broken symlinks)
+      }
+    }
+
+    return {
+      sandboxId,
+      providerId: this.id,
+      data: { files },
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  async restore(snapshot: SandboxSnapshot): Promise<Sandbox> {
+    const { files } = snapshot.data as { files: Record<string, string> };
+    const initialFiles: InitialFiles = {};
+    for (const [path, content] of Object.entries(files)) {
+      initialFiles[path] = content;
+    }
+
+    const fs = new InMemoryFs(initialFiles);
+    const sandbox = new InMemorySandboxImpl(
+      snapshot.sandboxId,
+      fs,
+      this.defaultOptions
+    );
+    this.sandboxes.set(sandbox.id, sandbox);
+    return sandbox;
+  }
+}