zeitlich 0.2.21 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -37,6 +37,16 @@
         "default": "./dist/adapters/thread/langchain/index.js"
       }
     },
+    "./adapters/thread/langchain/workflow": {
+      "import": {
+        "types": "./dist/adapters/thread/langchain/workflow.d.ts",
+        "default": "./dist/adapters/thread/langchain/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/langchain/workflow.d.ts",
+        "default": "./dist/adapters/thread/langchain/workflow.js"
+      }
+    },
     "./adapters/thread/google-genai": {
       "import": {
         "types": "./dist/adapters/thread/google-genai/index.d.ts",
@@ -47,6 +57,16 @@
         "default": "./dist/adapters/thread/google-genai/index.js"
       }
     },
+    "./adapters/thread/google-genai/workflow": {
+      "import": {
+        "types": "./dist/adapters/thread/google-genai/workflow.d.ts",
+        "default": "./dist/adapters/thread/google-genai/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/thread/google-genai/workflow.d.ts",
+        "default": "./dist/adapters/thread/google-genai/workflow.js"
+      }
+    },
     "./adapters/sandbox/inmemory": {
       "import": {
         "types": "./dist/adapters/sandbox/inmemory/index.d.ts",
@@ -57,6 +77,16 @@
         "default": "./dist/adapters/sandbox/inmemory/index.js"
       }
     },
+    "./adapters/sandbox/inmemory/workflow": {
+      "import": {
+        "types": "./dist/adapters/sandbox/inmemory/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/inmemory/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/inmemory/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/inmemory/workflow.js"
+      }
+    },
     "./adapters/sandbox/virtual": {
       "import": {
         "types": "./dist/adapters/sandbox/virtual/index.d.ts",
@@ -67,6 +97,16 @@
         "default": "./dist/adapters/sandbox/virtual/index.js"
       }
     },
+    "./adapters/sandbox/virtual/workflow": {
+      "import": {
+        "types": "./dist/adapters/sandbox/virtual/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/virtual/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/virtual/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/virtual/workflow.js"
+      }
+    },
     "./adapters/sandbox/daytona": {
       "import": {
         "types": "./dist/adapters/sandbox/daytona/index.d.ts",
@@ -76,6 +116,16 @@
         "types": "./dist/adapters/sandbox/daytona/index.d.ts",
         "default": "./dist/adapters/sandbox/daytona/index.js"
       }
+    },
+    "./adapters/sandbox/daytona/workflow": {
+      "import": {
+        "types": "./dist/adapters/sandbox/daytona/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/daytona/workflow.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/daytona/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/daytona/workflow.js"
+      }
     }
   },
   "files": [
@@ -121,6 +171,7 @@
   },
   "devDependencies": {
     "@daytonaio/sdk": "^0.149.0",
+    "@e2b/code-interpreter": "^2.3.3",
     "@eslint/js": "^10.0.1",
     "@google/genai": "^1.44.0",
     "@langchain/core": "^1.1.30",
@@ -138,7 +189,8 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@daytonaio/sdk": ">=0.100.0",
+    "@daytonaio/sdk": ">=0.153.0",
+    "@e2b/code-interpreter": "^2.3.3",
     "@google/genai": "^1.43.0",
     "@langchain/core": ">=1.0.0",
     "ioredis": ">=5.0.0",

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

@@ -55,7 +55,7 @@ export class DaytonaSandboxFileSystem implements SandboxFileSystem {
     await this.sandbox.fs.uploadFiles(
       files.map((f) => ({
         source: Buffer.from(f.content),
-        destination: f.path,
+        destination: this.normalisePath(f.path),
       }))
     );
   }

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

@@ -141,6 +141,14 @@ export class DaytonaSandboxProvider implements SandboxProvider<
     }
   }
 
+  async pause(_sandboxId: string, _ttlSeconds?: number): Promise<void> {
+    throw new SandboxNotSupportedError("pause");
+  }
+
+  async fork(_sandboxId: string): Promise<Sandbox> {
+    throw new Error("Not implemented");
+  }
+
   async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
     throw new SandboxNotSupportedError(
       "snapshot (use Daytona's native snapshot API directly)"

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

@@ -0,0 +1,56 @@
+/**
+ * Workflow-safe proxy for Daytona sandbox operations.
+ *
+ * Uses longer timeouts than in-memory providers since Daytona
+ * sandboxes are remote and creation involves provisioning.
+ *
+ * Import this from `zeitlich/adapters/sandbox/daytona/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyDaytonaSandboxOps } from 'zeitlich/adapters/sandbox/daytona/workflow';
+ *
+ * const sandbox = proxyDaytonaSandboxOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { DaytonaSandboxCreateOptions } from "./types";
+
+const ADAPTER_PREFIX = "daytona";
+
+export function proxyDaytonaSandboxOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "120s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "5s",
+        maximumInterval: "60s",
+        backoffCoefficient: 3,
+      },
+    }
+  );
+
+  const prefix = `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    createSandbox: acts[p("createSandbox")],
+    destroySandbox: acts[p("destroySandbox")],
+    pauseSandbox: acts[p("pauseSandbox")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps<DaytonaSandboxCreateOptions>;
+}

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

@@ -0,0 +1,147 @@
+import { FileType, type Sandbox as E2bSdkSandbox } from "@e2b/code-interpreter";
+import type {
+  SandboxFileSystem,
+  DirentEntry,
+  FileStat,
+} from "../../../lib/sandbox/types";
+import { posix } from "node:path";
+
+function toArrayBuffer(u8: Uint8Array): ArrayBuffer {
+  return u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
+}
+
+/**
+ * {@link SandboxFileSystem} backed by an E2B SDK sandbox.
+ *
+ * Maps zeitlich's filesystem interface to E2B's `sandbox.files` and
+ * `sandbox.commands` APIs. Operations that have no direct E2B equivalent
+ * (e.g. `appendFile`, `cp`) are composed from primitives.
+ */
+export class E2bSandboxFileSystem implements SandboxFileSystem {
+  readonly workspaceBase: string;
+
+  constructor(
+    private sandbox: E2bSdkSandbox,
+    workspaceBase = "/home/user"
+  ) {
+    this.workspaceBase = posix.resolve("/", workspaceBase);
+  }
+
+  private normalisePath(path: string): string {
+    return posix.resolve(this.workspaceBase, path);
+  }
+
+  async readFile(path: string): Promise<string> {
+    return this.sandbox.files.read(this.normalisePath(path));
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    return this.sandbox.files.read(this.normalisePath(path), {
+      format: "bytes",
+    });
+  }
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = this.normalisePath(path);
+    if (typeof content === "string") {
+      await this.sandbox.files.write(norm, content);
+    } else {
+      await this.sandbox.files.write(norm, toArrayBuffer(content));
+    }
+  }
+
+  async appendFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = this.normalisePath(path);
+    let existing = "";
+    try {
+      existing = await this.sandbox.files.read(norm);
+    } catch {
+      // file doesn't exist yet — write from scratch
+    }
+    const addition =
+      typeof content === "string"
+        ? content
+        : new TextDecoder().decode(content);
+    await this.sandbox.files.write(norm, existing + addition);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.sandbox.files.exists(this.normalisePath(path));
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const norm = this.normalisePath(path);
+    const info = await this.sandbox.files.getInfo(norm);
+    const isSymlink = !!info.symlinkTarget;
+    return {
+      isFile: isSymlink ? false : info.type === FileType.FILE,
+      isDirectory: isSymlink ? false : info.type === FileType.DIR,
+      isSymbolicLink: isSymlink,
+      size: info.size,
+      mtime: info.modifiedTime ?? new Date(0),
+    };
+  }
+
+  async mkdir(path: string, _options?: { recursive?: boolean }): Promise<void> {
+    await this.sandbox.files.makeDir(this.normalisePath(path));
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const entries = await this.sandbox.files.list(this.normalisePath(path));
+    return entries.map((e) => posix.basename(e.path));
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const entries = await this.sandbox.files.list(this.normalisePath(path));
+    return entries.map((e) => {
+      const isSymlink = !!e.symlinkTarget;
+      return {
+        name: posix.basename(e.path),
+        isFile: isSymlink ? false : e.type === FileType.FILE,
+        isDirectory: isSymlink ? false : e.type === FileType.DIR,
+        isSymbolicLink: isSymlink,
+      };
+    });
+  }
+
+  async rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean }
+  ): Promise<void> {
+    const norm = this.normalisePath(path);
+    try {
+      await this.sandbox.files.remove(norm);
+    } catch (err) {
+      if (!options?.force) throw err;
+    }
+  }
+
+  async cp(
+    src: string,
+    dest: string,
+    _options?: { recursive?: boolean }
+  ): Promise<void> {
+    const normSrc = this.normalisePath(src);
+    const normDest = this.normalisePath(dest);
+    await this.sandbox.commands.run(`cp -r "${normSrc}" "${normDest}"`);
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    const normSrc = this.normalisePath(src);
+    const normDest = this.normalisePath(dest);
+    await this.sandbox.files.rename(normSrc, normDest);
+  }
+
+  async readlink(path: string): Promise<string> {
+    const norm = this.normalisePath(path);
+    const info = await this.sandbox.files.getInfo(norm);
+    if (!info.symlinkTarget) {
+      throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
+    }
+    return info.symlinkTarget;
+  }
+
+  resolvePath(base: string, path: string): string {
+    return posix.resolve(this.normalisePath(base), path);
+  }
+}

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

@@ -0,0 +1,164 @@
+import { Sandbox as E2bSdkSandbox } from "@e2b/code-interpreter";
+import type {
+  Sandbox,
+  SandboxCapabilities,
+  SandboxCreateResult,
+  SandboxProvider,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+} from "../../../lib/sandbox/types";
+import {
+  SandboxNotFoundError,
+  SandboxNotSupportedError,
+} from "../../../lib/sandbox/types";
+import { E2bSandboxFileSystem } from "./filesystem";
+import type {
+  E2bSandbox,
+  E2bSandboxConfig,
+  E2bSandboxCreateOptions,
+} from "./types";
+
+// ============================================================================
+// E2bSandbox
+// ============================================================================
+
+class E2bSandboxImpl implements Sandbox {
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true,
+  };
+
+  readonly fs: E2bSandboxFileSystem;
+
+  constructor(
+    readonly id: string,
+    private sdkSandbox: E2bSdkSandbox,
+    workspaceBase = "/home/user"
+  ) {
+    this.fs = new E2bSandboxFileSystem(sdkSandbox, workspaceBase);
+  }
+
+  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+    const result = await this.sdkSandbox.commands.run(command, {
+      cwd: options?.cwd,
+      envs: options?.env,
+      timeoutMs: options?.timeout,
+    });
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  }
+
+  async destroy(): Promise<void> {
+    await this.sdkSandbox.kill();
+  }
+}
+
+// ============================================================================
+// E2bSandboxProvider
+// ============================================================================
+
+export class E2bSandboxProvider
+  implements SandboxProvider<E2bSandboxCreateOptions, E2bSandbox>
+{
+  readonly id = "e2b";
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: true,
+    persistence: true,
+  };
+
+  private readonly defaultTemplate?: string;
+  private readonly defaultWorkspaceBase: string;
+  private readonly defaultTimeoutMs?: number;
+
+  constructor(config?: E2bSandboxConfig) {
+    this.defaultTemplate = config?.template;
+    this.defaultWorkspaceBase = config?.workspaceBase ?? "/home/user";
+    this.defaultTimeoutMs = config?.timeoutMs;
+  }
+
+  async create(
+    options?: E2bSandboxCreateOptions
+  ): Promise<SandboxCreateResult> {
+    const template = options?.template ?? this.defaultTemplate;
+    const workspaceBase = this.defaultWorkspaceBase;
+    const createOpts = {
+      envs: options?.env,
+      timeoutMs: options?.timeoutMs ?? this.defaultTimeoutMs,
+    };
+
+    const sdkSandbox = template
+      ? await E2bSdkSandbox.create(template, createOpts)
+      : await E2bSdkSandbox.create(createOpts);
+
+    const sandbox = new E2bSandboxImpl(
+      sdkSandbox.sandboxId,
+      sdkSandbox,
+      workspaceBase
+    );
+
+    if (options?.initialFiles) {
+      await Promise.all(
+        Object.entries(options.initialFiles).map(([path, content]) =>
+          sandbox.fs.writeFile(path, content)
+        )
+      );
+    }
+
+    return { sandbox };
+  }
+
+  async get(sandboxId: string): Promise<E2bSandbox> {
+    try {
+      const sdkSandbox = await E2bSdkSandbox.connect(sandboxId);
+      return new E2bSandboxImpl(sandboxId, sdkSandbox, this.defaultWorkspaceBase);
+    } catch {
+      throw new SandboxNotFoundError(sandboxId);
+    }
+  }
+
+  async destroy(sandboxId: string): Promise<void> {
+    try {
+      const sdkSandbox = await E2bSdkSandbox.connect(sandboxId);
+      await sdkSandbox.kill();
+    } catch {
+      // Already gone or not found
+    }
+  }
+
+  async pause(sandboxId: string, _ttlSeconds?: number): Promise<void> {
+    const sdkSandbox = await E2bSdkSandbox.connect(sandboxId);
+    await sdkSandbox.pause();
+  }
+
+  async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
+    throw new SandboxNotSupportedError("snapshot");
+  }
+
+  async restore(_snapshot: SandboxSnapshot): Promise<Sandbox> {
+    throw new SandboxNotSupportedError("restore");
+  }
+
+  async fork(sandboxId: string): Promise<Sandbox> {
+    const { snapshotId } = await E2bSdkSandbox.createSnapshot(sandboxId);
+    const sdkSandbox = await E2bSdkSandbox.create(snapshotId);
+    return new E2bSandboxImpl(
+      sdkSandbox.sandboxId,
+      sdkSandbox,
+      this.defaultWorkspaceBase
+    );
+  }
+}
+
+// Re-exports
+export { E2bSandboxFileSystem } from "./filesystem";
+export type {
+  E2bSandbox,
+  E2bSandboxConfig,
+  E2bSandboxCreateOptions,
+} from "./types";

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

@@ -0,0 +1,23 @@
+import type { Sandbox, SandboxCreateOptions } from "../../../lib/sandbox/types";
+import type { E2bSandboxFileSystem } from "./filesystem";
+
+/**
+ * An E2B-backed {@link Sandbox} with its typed filesystem.
+ */
+export type E2bSandbox = Sandbox & { fs: E2bSandboxFileSystem };
+
+export interface E2bSandboxConfig {
+  /** Sandbox template name or ID */
+  template?: string;
+  /** Default working directory inside the sandbox */
+  workspaceBase?: string;
+  /** Sandbox idle timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+export interface E2bSandboxCreateOptions extends SandboxCreateOptions {
+  /** Sandbox template name or ID — overrides the provider default */
+  template?: string;
+  /** Sandbox idle timeout in milliseconds — overrides the provider default */
+  timeoutMs?: number;
+}

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

@@ -27,7 +27,8 @@ import { getShortId } from "../../../lib/thread/id";
 
 function toSandboxFs(fs: IFileSystem): SandboxFileSystem {
   const workspaceBase = "/";
-  const normalisePath = (path: string): string => fs.resolvePath(workspaceBase, path);
+  const normalisePath = (path: string): string =>
+    fs.resolvePath(workspaceBase, path);
 
   return {
     workspaceBase,
@@ -68,7 +69,8 @@ function toSandboxFs(fs: IFileSystem): SandboxFileSystem {
       return fs.readdirWithFileTypes(dirPath);
     },
     rm: (path, opts) => fs.rm(normalisePath(path), opts),
-    cp: (src, dest, opts) => fs.cp(normalisePath(src), normalisePath(dest), opts),
+    cp: (src, dest, opts) =>
+      fs.cp(normalisePath(src), normalisePath(dest), opts),
     mv: (src, dest) => fs.mv(normalisePath(src), normalisePath(dest)),
     readlink: (path) => fs.readlink(normalisePath(path)),
     resolvePath: (base, p) => fs.resolvePath(normalisePath(base), p),
@@ -132,7 +134,7 @@ class InMemorySandboxImpl implements Sandbox {
 // ============================================================================
 
 export class InMemorySandboxProvider implements SandboxProvider {
-  readonly id = "inmemory";
+  readonly id = "inMemory";
   readonly capabilities: SandboxCapabilities = {
     filesystem: true,
     execution: true,
@@ -157,6 +159,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     }
   }
 
+  async pause(_sandboxId: string, _ttlSeconds?: number): Promise<void> {
+    // In-memory: nothing to pause
+  }
+
   async create(options?: SandboxCreateOptions): Promise<SandboxCreateResult> {
     const id = options?.id ?? getShortId();
     const initialFiles: InitialFiles = {};
@@ -200,6 +206,24 @@ export class InMemorySandboxProvider implements SandboxProvider {
     };
   }
 
+  async fork(sandboxId: string): Promise<Sandbox> {
+    const sandbox = await this.get(sandboxId);
+
+    const entries = await sandbox.fs.readdirWithFileTypes("/");
+    const initialFiles: Record<string, Uint8Array> = {};
+    for (const entry of entries) {
+      if (entry.isFile) {
+        initialFiles[entry.name] = await sandbox.fs.readFileBuffer(entry.name);
+      }
+    }
+
+    const newSandbox = await this.create({
+      id: getShortId(),
+      initialFiles,
+    });
+    return newSandbox.sandbox;
+  }
+
   async restore(snapshot: SandboxSnapshot): Promise<Sandbox> {
     const { files } = snapshot.data as { files: Record<string, string> };
     const initialFiles: InitialFiles = {};

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

@@ -0,0 +1,53 @@
+/**
+ * Workflow-safe proxy for in-memory sandbox operations.
+ *
+ * Import this from `zeitlich/adapters/sandbox/inmemory/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyInMemorySandboxOps } from 'zeitlich/adapters/sandbox/inmemory/workflow';
+ *
+ * // Auto-scoped to the current workflow name
+ * const sandbox = proxyInMemorySandboxOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { SandboxOps } from "../../../lib/sandbox/types";
+
+const ADAPTER_PREFIX = "inMemory";
+
+export function proxyInMemorySandboxOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "30s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "2s",
+        maximumInterval: "30s",
+        backoffCoefficient: 2,
+      },
+    }
+  );
+
+  const prefix = `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    createSandbox: acts[p("createSandbox")],
+    destroySandbox: acts[p("destroySandbox")],
+    pauseSandbox: acts[p("pauseSandbox")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps;
+}