zeitlich 0.2.22 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -189,7 +189,7 @@
     "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",

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,10 @@ 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");
   }

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

@@ -19,6 +19,7 @@
  */
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
 import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { DaytonaSandboxCreateOptions } from "./types";
 
 const ADAPTER_PREFIX = "daytona";
 
@@ -41,15 +42,15 @@ export function proxyDaytonaSandboxOps(
     }
   );
 
-  const prefix =
-    `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  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;
+  } as SandboxOps<DaytonaSandboxCreateOptions>;
 }

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

@@ -131,6 +131,11 @@ export class E2bSandboxProvider
     }
   }
 
+  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");
   }

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),
@@ -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,8 +206,22 @@ export class InMemorySandboxProvider implements SandboxProvider {
     };
   }
 
-  async fork(_sandboxId: string): Promise<Sandbox> {
-    throw new Error("Not implemented");
+  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> {

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

@@ -39,14 +39,14 @@ export function proxyInMemorySandboxOps(
     }
   );
 
-  const prefix =
-    `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  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;

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

@@ -29,7 +29,7 @@ function parentDir(p: string): string {
  */
 function inferDirectories(
   entries: { path: string }[],
-  workspaceBase: string,
+  workspaceBase: string
 ): Set<string> {
   const dirs = new Set<string>();
   dirs.add("/");
@@ -54,8 +54,7 @@ function inferDirectories(
 export class VirtualSandboxFileSystem<
   TCtx = unknown,
   TMeta = FileEntryMetadata,
-> implements SandboxFileSystem
-{
+> implements SandboxFileSystem {
   readonly workspaceBase: string;
   private entries: Map<string, FileEntry<TMeta>>;
   private directories: Set<string>;
@@ -65,11 +64,11 @@ export class VirtualSandboxFileSystem<
     tree: FileEntry<TMeta>[],
     private resolver: FileResolver<TCtx, TMeta>,
     private ctx: TCtx,
-    workspaceBase = "/",
+    workspaceBase = "/"
   ) {
     this.workspaceBase = normalisePath(workspaceBase);
     this.entries = new Map(
-      tree.map((e) => [normalisePath(e.path, this.workspaceBase), e]),
+      tree.map((e) => [normalisePath(e.path, this.workspaceBase), e])
     );
     this.directories = inferDirectories(tree, this.workspaceBase);
   }
@@ -91,13 +90,13 @@ export class VirtualSandboxFileSystem<
   async readFile(path: string): Promise<string> {
     const entry = this.entries.get(normalisePath(path, this.workspaceBase));
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
-    return this.resolver.readFile(entry.id, this.ctx);
+    return this.resolver.readFile(entry.id, this.ctx, entry.metadata);
   }
 
   async readFileBuffer(path: string): Promise<Uint8Array> {
     const entry = this.entries.get(normalisePath(path, this.workspaceBase));
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
-    return this.resolver.readFileBuffer(entry.id, this.ctx);
+    return this.resolver.readFileBuffer(entry.id, this.ctx, entry.metadata);
   }
 
   // --------------------------------------------------------------------------
@@ -180,7 +179,12 @@ export class VirtualSandboxFileSystem<
     const existing = this.entries.get(norm);
 
     if (existing) {
-      await this.resolver.writeFile(existing.id, content, this.ctx);
+      await this.resolver.writeFile(
+        existing.id,
+        content,
+        this.ctx,
+        existing.metadata
+      );
       const size =
         typeof content === "string"
           ? new TextEncoder().encode(content).byteLength
@@ -209,12 +213,21 @@ export class VirtualSandboxFileSystem<
       return this.writeFile(path, content);
     }
 
-    const current = await this.resolver.readFile(existing.id, this.ctx);
+    const current = await this.resolver.readFile(
+      existing.id,
+      this.ctx,
+      existing.metadata
+    );
     const appended =
       typeof content === "string"
         ? current + content
         : current + new TextDecoder().decode(content);
-    await this.resolver.writeFile(existing.id, appended, this.ctx);
+    await this.resolver.writeFile(
+      existing.id,
+      appended,
+      this.ctx,
+      existing.metadata
+    );
 
     const size = new TextEncoder().encode(appended).byteLength;
     const updated: FileEntry<TMeta> = {
@@ -226,7 +239,10 @@ export class VirtualSandboxFileSystem<
     this.mutations.push({ type: "update", path: norm, entry: updated });
   }
 
-  async mkdir(_path: string, _options?: { recursive?: boolean }): Promise<void> {
+  async mkdir(
+    _path: string,
+    _options?: { recursive?: boolean }
+  ): Promise<void> {
     const norm = normalisePath(_path, this.workspaceBase);
     if (this.directories.has(norm)) return;
 
@@ -244,13 +260,13 @@ export class VirtualSandboxFileSystem<
 
   async rm(
     path: string,
-    options?: { recursive?: boolean; force?: boolean },
+    options?: { recursive?: boolean; force?: boolean }
   ): Promise<void> {
     const norm = normalisePath(path, this.workspaceBase);
     const entry = this.entries.get(norm);
 
     if (entry) {
-      await this.resolver.deleteFile(entry.id, this.ctx);
+      await this.resolver.deleteFile(entry.id, this.ctx, entry.metadata);
       this.entries.delete(norm);
       this.mutations.push({ type: "remove", path: norm });
       return;
@@ -263,7 +279,7 @@ export class VirtualSandboxFileSystem<
       const prefix = norm === "/" ? "/" : norm + "/";
       for (const [p, e] of this.entries) {
         if (p.startsWith(prefix)) {
-          await this.resolver.deleteFile(e.id, this.ctx);
+          await this.resolver.deleteFile(e.id, this.ctx, e.metadata);
           this.entries.delete(p);
           this.mutations.push({ type: "remove", path: p });
         }
@@ -283,14 +299,18 @@ export class VirtualSandboxFileSystem<
   async cp(
     src: string,
     dest: string,
-    _options?: { recursive?: boolean },
+    _options?: { recursive?: boolean }
   ): Promise<void> {
     const normSrc = normalisePath(src, this.workspaceBase);
     const normDest = normalisePath(dest, this.workspaceBase);
 
     const entry = this.entries.get(normSrc);
     if (entry) {
-      const content = await this.resolver.readFile(entry.id, this.ctx);
+      const content = await this.resolver.readFile(
+        entry.id,
+        this.ctx,
+        entry.metadata
+      );
       await this.writeFile(normDest, content);
       return;
     }
@@ -306,7 +326,11 @@ export class VirtualSandboxFileSystem<
     for (const [p, e] of this.entries) {
       if (p.startsWith(prefix)) {
         const relative = p.slice(normSrc.length);
-        const content = await this.resolver.readFile(e.id, this.ctx);
+        const content = await this.resolver.readFile(
+          e.id,
+          this.ctx,
+          e.metadata
+        );
         await this.writeFile(normDest + relative, content);
       }
     }

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

@@ -90,6 +90,10 @@ export class VirtualSandboxProvider<
     // No-op — no internal state to clean up
   }
 
+  async pause(): Promise<void> {
+    // No-op — virtual sandbox state lives in workflow AgentState
+  }
+
   async fork(_sandboxId: string): Promise<never> {
     throw new Error("Not implemented");
   }

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

@@ -46,6 +46,7 @@ export function proxyVirtualSandboxOps(
   return {
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
+    pauseSandbox: acts[p("pauseSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
   } as SandboxOps<VirtualSandboxCreateOptions<unknown>>;

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

@@ -56,15 +56,20 @@ export type TreeMutation<TMeta = FileEntryMetadata> =
  */
 export interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
   resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
-  readFile(id: string, ctx: TCtx): Promise<string>;
-  readFileBuffer(id: string, ctx: TCtx): Promise<Uint8Array>;
-  writeFile(id: string, content: string | Uint8Array, ctx: TCtx): Promise<void>;
+  readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
+  readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
+  writeFile(
+    id: string,
+    content: string | Uint8Array,
+    ctx: TCtx,
+    metadata: TMeta
+  ): Promise<void>;
   createFile(
     path: string,
     content: string | Uint8Array,
     ctx: TCtx
   ): Promise<FileEntry<TMeta>>;
-  deleteFile(id: string, ctx: TCtx): Promise<void>;
+  deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
 }
 
 // ============================================================================

package/src/lib/lifecycle.ts

@@ -0,0 +1,57 @@
+// ============================================================================
+// Thread lifecycle
+// ============================================================================
+
+/**
+ * Thread initialization strategy.
+ *
+ * - `"new"` — start a fresh thread (optionally specify its ID).
+ * - `"continue"` — append directly to an existing thread in-place.
+ * - `"fork"` — copy all messages from an existing thread into a new one and
+ *   continue there.
+ */
+export type ThreadInit =
+  | { mode: "new"; threadId?: string }
+  | { mode: "continue"; threadId: string }
+  | { mode: "fork"; threadId: string };
+
+// ============================================================================
+// Sandbox lifecycle
+// ============================================================================
+
+/**
+ * Sandbox initialization strategy.
+ *
+ * - `"new"` — create a fresh sandbox.
+ * - `"continue"` — resume a previously-paused sandbox (this session takes
+ *   ownership and the shutdown policy applies on exit).
+ * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
+ *   created and owned by this session.
+ * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
+ *   The session will **not** manage its lifecycle on exit.
+ */
+export type SandboxInit =
+  | { mode: "new" }
+  | { mode: "continue"; sandboxId: string }
+  | { mode: "fork"; sandboxId: string }
+  | { mode: "inherit"; sandboxId: string };
+
+/**
+ * What to do with the sandbox when the session exits.
+ *
+ * - `"destroy"` — tear down the sandbox entirely.
+ * - `"pause"` — pause the sandbox so it can be resumed later.
+ * - `"keep"` — leave the sandbox running (no-op on exit).
+ */
+export type SandboxShutdown = "destroy" | "pause" | "keep";
+
+/**
+ * Extended shutdown options available to subagent workflows.
+ *
+ * Includes all base {@link SandboxShutdown} values plus:
+ * - `"pause-until-parent-close"` — pause the sandbox on exit, then wait for
+ *   the parent workflow to signal when to destroy it.
+ */
+export type SubagentSandboxShutdown =
+  | SandboxShutdown
+  | "pause-until-parent-close";

package/src/lib/sandbox/manager.ts

@@ -28,7 +28,9 @@ export class SandboxManager<
   TSandbox extends Sandbox = Sandbox,
   TId extends string = string,
 > {
-  constructor(private provider: SandboxProvider<TOptions, TSandbox> & { readonly id: TId }) {}
+  constructor(
+    private provider: SandboxProvider<TOptions, TSandbox> & { readonly id: TId }
+  ) {}
 
   async create(
     options?: TOptions
@@ -45,6 +47,10 @@ export class SandboxManager<
     await this.provider.destroy(id);
   }
 
+  async pause(id: string, ttlSeconds?: number): Promise<void> {
+    await this.provider.pause(id, ttlSeconds);
+  }
+
   async snapshot(id: string): Promise<SandboxSnapshot> {
     return this.provider.snapshot(id);
   }
@@ -95,6 +101,12 @@ export class SandboxManager<
       destroySandbox: async (sandboxId: string): Promise<void> => {
         await this.destroy(sandboxId);
       },
+      pauseSandbox: async (
+        sandboxId: string,
+        ttlSeconds?: number
+      ): Promise<void> => {
+        await this.pause(sandboxId, ttlSeconds);
+      },
       snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId);
       },

package/src/lib/sandbox/types.ts

@@ -35,8 +35,15 @@ export interface SandboxFileSystem {
   mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
   readdir(path: string): Promise<string[]>;
   readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
-  cp(src: string, dest: string, options?: { recursive?: boolean }): Promise<void>;
+  rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean }
+  ): Promise<void>;
+  cp(
+    src: string,
+    dest: string,
+    options?: { recursive?: boolean }
+  ): Promise<void>;
   mv(src: string, dest: string): Promise<void>;
   readlink(path: string): Promise<string>;
   resolvePath(base: string, path: string): string;
@@ -125,6 +132,7 @@ export interface SandboxProvider<
   create(options?: TOptions): Promise<SandboxCreateResult>;
   get(sandboxId: string): Promise<TSandbox>;
   destroy(sandboxId: string): Promise<void>;
+  pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
   fork(sandboxId: string): Promise<Sandbox>;
@@ -138,9 +146,10 @@ export interface SandboxOps<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
 > {
   createSandbox(
-    options?: TOptions,
+    options?: TOptions
   ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }>;
   destroySandbox(sandboxId: string): Promise<void>;
+  pauseSandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
   forkSandbox(sandboxId: string): Promise<string>;
 }
@@ -172,7 +181,7 @@ export class SandboxNotSupportedError extends ApplicationFailure {
     super(
       `Sandbox does not support: ${operation}`,
       "SandboxNotSupportedError",
-      true,
+      true
     );
   }
 }

package/src/lib/session/index.ts

@@ -5,5 +5,6 @@ export type {
   PrefixedThreadOps,
   ScopedPrefix,
   SessionConfig,
+  SessionResult,
   ZeitlichSession,
 } from "./types";