zeitlich 0.2.21 → 0.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "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",
@@ -139,6 +190,7 @@
   },
   "peerDependencies": {
     "@daytonaio/sdk": ">=0.100.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/index.ts

@@ -141,6 +141,10 @@ export class DaytonaSandboxProvider implements SandboxProvider<
     }
   }
 
+  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,55 @@
+/**
+ * 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";
+
+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")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps;
+}

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,159 @@
+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 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

@@ -132,7 +132,7 @@ class InMemorySandboxImpl implements Sandbox {
 // ============================================================================
 
 export class InMemorySandboxProvider implements SandboxProvider {
-  readonly id = "inmemory";
+  readonly id = "inMemory";
   readonly capabilities: SandboxCapabilities = {
     filesystem: true,
     execution: true,
@@ -200,6 +200,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     };
   }
 
+  async fork(_sandboxId: string): Promise<Sandbox> {
+    throw new Error("Not implemented");
+  }
+
   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")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps;
+}

package/src/adapters/sandbox/virtual/provider.ts

@@ -26,7 +26,7 @@ import type {
  * const manager = new SandboxManager(provider);
  *
  * export const activities = {
- *   ...manager.createActivities(),
+ *   ...manager.createActivities("CodingAgent"),
  *   readFile: withVirtualSandbox(client, provider, readHandler),
  * };
  * ```
@@ -90,6 +90,10 @@ export class VirtualSandboxProvider<
     // No-op — no internal state to clean up
   }
 
+  async fork(_sandboxId: string): Promise<never> {
+    throw new Error("Not implemented");
+  }
+
   async snapshot(): Promise<never> {
     throw new SandboxNotSupportedError(
       "snapshot (virtual sandbox state lives in workflow AgentState)"

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

@@ -0,0 +1,52 @@
+/**
+ * Workflow-safe proxy for virtual sandbox operations.
+ *
+ * Import this from `zeitlich/adapters/sandbox/virtual/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 { proxyVirtualSandboxOps } from 'zeitlich/adapters/sandbox/virtual/workflow';
+ *
+ * const sandbox = proxyVirtualSandboxOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { VirtualSandboxCreateOptions } from "./types";
+
+const ADAPTER_PREFIX = "virtual";
+
+export function proxyVirtualSandboxOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps<VirtualSandboxCreateOptions<unknown>> {
+  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")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps<VirtualSandboxCreateOptions<unknown>>;
+}