zeitlich 0.2.36 → 0.2.38

package/src/lib/model/types.ts

@@ -8,6 +8,16 @@ export interface AgentResponse<M = unknown> {
   message: M;
   rawToolCalls: RawToolCall[];
   usage?: TokenUsage;
+  /**
+   * Number of stored messages in the thread at the moment the LLM was
+   * invoked — i.e. *before* the assistant message is appended. The
+   * session uses this as a rewind snapshot so it can roll the thread
+   * back to this exact state if a tool requests a rewind.
+   *
+   * Adapters compute this for free from the array of stored messages
+   * they load when preparing the payload.
+   */
+  threadLengthAtCall?: number;
 }
 
 /**

package/src/lib/observability/hooks.ts

@@ -1,9 +1,6 @@
 import { proxySinks } from "@temporalio/workflow";
 import type { ZeitlichObservabilitySinks } from "./sinks";
-import type {
-  SessionStartHook,
-  SessionEndHook,
-} from "../hooks/types";
+import type { SessionStartHook, SessionEndHook } from "../hooks/types";
 import type {
   PostToolUseHook,
   PostToolUseFailureHook,
@@ -39,7 +36,9 @@ export interface ObservabilityHooks {
  *
  * @param agentName - Agent name attached to every emitted event
  */
-export function createObservabilityHooks(agentName: string): ObservabilityHooks {
+export function createObservabilityHooks(
+  agentName: string
+): ObservabilityHooks {
   const { zeitlichMetrics } = proxySinks<ZeitlichObservabilitySinks>();
   let sessionStartMs = Date.now();
 

package/src/lib/observability/index.ts

@@ -1,7 +1,4 @@
-export {
-  createObservabilityHooks,
-  composeHooks,
-} from "./hooks";
+export { createObservabilityHooks, composeHooks } from "./hooks";
 export type { ObservabilityHooks } from "./hooks";
 
 export type {

package/src/lib/sandbox/manager.ts

@@ -50,8 +50,12 @@ export interface SandboxManagerHooks<
 
   /**
    * Called after a sandbox has been successfully created.
+   *
+   * Receives the live {@link Sandbox} instance so the hook can run setup
+   * commands, seed files, or capture identifiers without an extra
+   * `provider.get()` round-trip.
    */
-  onPostCreate?: (sandboxId: string) => Promise<void>;
+  onPostCreate?: (sandbox: Sandbox, ctx: TCtx) => Promise<void>;
 }
 
 /**
@@ -87,8 +91,9 @@ export interface SandboxManagerHooks<
  *         for (const p of filePaths) files[p] = await db.readFile(projectId, p);
  *         return { modifiedOptions: { initialFiles: files } };
  *       },
- *       onPostCreate: async (sandboxId) => {
- *         console.log("Sandbox created:", sandboxId);
+ *       onPostCreate: async (sandbox) => {
+ *         console.log("Sandbox created:", sandbox.id);
+ *         await sandbox.exec("git init");
  *       },
  *     },
  *   },
@@ -115,9 +120,7 @@ export class SandboxManager<
   async create(
     options?: TOptions,
     ctx?: TCtx
-  ): Promise<{
-    sandboxId: string;
-  } | null> {
+  ): Promise<{ sandboxId: string } | null> {
     let providerOptions = options;
 
     if (this.hooks.onPreCreate) {
@@ -148,7 +151,7 @@ export class SandboxManager<
     const { sandbox } = await this.provider.create(providerOptions);
 
     if (this.hooks.onPostCreate) {
-      await this.hooks.onPostCreate(sandbox.id);
+      await this.hooks.onPostCreate(sandbox, ctx ?? ({} as TCtx));
     }
 
     return { sandboxId: sandbox.id };
@@ -170,17 +173,24 @@ export class SandboxManager<
     await this.provider.resume(id);
   }
 
-  async snapshot(id: string): Promise<SandboxSnapshot> {
-    return this.provider.snapshot(id);
+  async snapshot(id: string, options?: TOptions): Promise<SandboxSnapshot> {
+    return this.provider.snapshot(id, options);
   }
 
-  async restore(snapshot: SandboxSnapshot): Promise<string> {
-    const sandbox = await this.provider.restore(snapshot);
+  async restore(
+    snapshot: SandboxSnapshot,
+    options?: TOptions
+  ): Promise<string> {
+    const sandbox = await this.provider.restore(snapshot, options);
     return sandbox.id;
   }
 
-  async fork(sandboxId: string): Promise<string> {
-    const sandbox = await this.provider.fork(sandboxId);
+  async deleteSnapshot(snapshot: SandboxSnapshot): Promise<void> {
+    await this.provider.deleteSnapshot(snapshot);
+  }
+
+  async fork(sandboxId: string, options?: TOptions): Promise<string> {
+    const sandbox = await this.provider.fork(sandboxId, options);
     return sandbox.id;
   }
 
@@ -212,9 +222,7 @@ export class SandboxManager<
       createSandbox: async (
         options?: TOptions,
         ctx?: TCtx
-      ): Promise<{
-        sandboxId: string;
-      } | null> => {
+      ): Promise<{ sandboxId: string } | null> => {
         return this.create(options, ctx);
       },
       destroySandbox: async (sandboxId: string): Promise<void> => {
@@ -229,11 +237,28 @@ export class SandboxManager<
       resumeSandbox: async (sandboxId: string): Promise<void> => {
         await this.resume(sandboxId);
       },
-      snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
-        return this.snapshot(sandboxId);
+      snapshotSandbox: async (
+        sandboxId: string,
+        options?: TOptions
+      ): Promise<SandboxSnapshot> => {
+        return this.snapshot(sandboxId, options);
+      },
+      restoreSandbox: async (
+        snapshot: SandboxSnapshot,
+        options?: TOptions
+      ): Promise<string> => {
+        return this.restore(snapshot, options);
+      },
+      deleteSandboxSnapshot: async (
+        snapshot: SandboxSnapshot
+      ): Promise<void> => {
+        await this.deleteSnapshot(snapshot);
       },
-      forkSandbox: async (sandboxId: string): Promise<string> => {
-        return this.fork(sandboxId);
+      forkSandbox: async (
+        sandboxId: string,
+        options?: TOptions
+      ): Promise<string> => {
+        return this.fork(sandboxId, options);
       },
     };
     const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);

package/src/lib/sandbox/node-fs.ts

@@ -65,10 +65,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
     };
   }
 
-  async mkdir(
-    path: string,
-    options?: { recursive?: boolean },
-  ): Promise<void> {
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
     await fsp.mkdir(this.abs(path), options);
   }
 
@@ -88,7 +85,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
 
   async rm(
     path: string,
-    options?: { recursive?: boolean; force?: boolean },
+    options?: { recursive?: boolean; force?: boolean }
   ): Promise<void> {
     await fsp.rm(this.abs(path), options);
   }
@@ -96,7 +93,7 @@ export class NodeFsSandboxFileSystem implements SandboxFileSystem {
   async cp(
     src: string,
     dest: string,
-    options?: { recursive?: boolean },
+    options?: { recursive?: boolean }
   ): Promise<void> {
     await fsp.cp(this.abs(src), this.abs(dest), options);
   }

package/src/lib/sandbox/sandbox.test.ts

@@ -157,18 +157,21 @@ describe("SandboxManager", () => {
     expect(await sandbox.fs.readFile("/file.txt")).toBe("explicit");
   });
 
-  it("onPostCreate hook receives sandboxId", async () => {
+  it("onPostCreate hook receives the live sandbox", async () => {
     let capturedId: string | undefined;
     const mgr = new SandboxManager(new InMemorySandboxProvider(), {
       hooks: {
-        onPostCreate: async (sandboxId) => {
-          capturedId = sandboxId;
+        onPostCreate: async (sandbox) => {
+          capturedId = sandbox.id;
+          await sandbox.fs.writeFile("/hook.txt", "written-by-hook");
         },
       },
     });
 
     const { sandboxId } = await mustCreate(mgr);
     expect(capturedId).toBe(sandboxId);
+    const sandbox = await mgr.getSandbox(sandboxId);
+    expect(await sandbox.fs.readFile("/hook.txt")).toBe("written-by-hook");
   });
 
   it("onPostCreate hook does not run when creation is skipped", async () => {
@@ -192,6 +195,8 @@ describe("SandboxManager", () => {
     expect(activities.inMemoryTestCreateSandbox).toBeTypeOf("function");
     expect(activities.inMemoryTestDestroySandbox).toBeTypeOf("function");
     expect(activities.inMemoryTestSnapshotSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestRestoreSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestDeleteSandboxSnapshot).toBeTypeOf("function");
 
     const result = await activities.inMemoryTestCreateSandbox();
     expect(result).not.toBeNull();
@@ -203,6 +208,34 @@ describe("SandboxManager", () => {
       SandboxNotFoundError
     );
   });
+
+  it("restoreSandbox activity creates a new sandbox from a snapshot", async () => {
+    const activities = manager.createActivities("Test");
+
+    const created = await activities.inMemoryTestCreateSandbox({
+      initialFiles: { "/greeting.txt": "hello" },
+    });
+    const { sandboxId } = created as { sandboxId: string };
+
+    const snapshot = await activities.inMemoryTestSnapshotSandbox(sandboxId);
+    await activities.inMemoryTestDestroySandbox(sandboxId);
+
+    const restoredId = await activities.inMemoryTestRestoreSandbox(snapshot);
+    const restored = await manager.getSandbox(restoredId);
+    expect(await restored.fs.readFile("/greeting.txt")).toBe("hello");
+  });
+
+  it("deleteSandboxSnapshot activity is a no-op for in-memory snapshots", async () => {
+    const activities = manager.createActivities("Test");
+
+    const created = await activities.inMemoryTestCreateSandbox();
+    const { sandboxId } = created as { sandboxId: string };
+
+    const snapshot = await activities.inMemoryTestSnapshotSandbox(sandboxId);
+    await expect(
+      activities.inMemoryTestDeleteSandboxSnapshot(snapshot)
+    ).resolves.toBeUndefined();
+  });
 });
 
 describe("InMemorySandboxProvider", () => {

package/src/lib/sandbox/tree.integration.test.ts

@@ -3,7 +3,10 @@ import { toTree } from "./tree";
 import type { SandboxFileSystem, DirentEntry } from "./types";
 
 function createMockFs(
-  structure: Record<string, { isDir: boolean; isLink?: boolean; linkTarget?: string }>,
+  structure: Record<
+    string,
+    { isDir: boolean; isLink?: boolean; linkTarget?: string }
+  >
 ): SandboxFileSystem {
   return {
     workspaceBase: "/",
@@ -21,13 +24,17 @@ function createMockFs(
     readdir: async (dir: string) => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.keys(structure)
-        .filter((p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          (p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map((p) => p.slice(prefix.length));
     },
     readdirWithFileTypes: async (dir: string): Promise<DirentEntry[]> => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.entries(structure)
-        .filter(([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          ([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map(([p, meta]) => ({
           name: p.slice(prefix.length),
           isFile: !meta.isDir && !meta.isLink,

package/src/lib/sandbox/types.ts

@@ -17,6 +17,21 @@ export interface FileStat {
   mtime: Date;
 }
 
+// ============================================================================
+// Network & lifecycle
+// ============================================================================
+
+export interface SandboxNetworkConfig {
+  allowOut?: string[];
+  denyOut?: string[];
+  allowPublicTraffic?: boolean;
+}
+
+export interface SandboxLifecycleConfig {
+  onTimeout: "kill" | "pause";
+  autoResume?: boolean;
+}
+
 /**
  * Provider-agnostic filesystem interface.
  *
@@ -114,6 +129,16 @@ export interface SandboxCreateOptions {
   initialFiles?: Record<string, string | Uint8Array>;
   /** Environment variables available inside the sandbox */
   env?: Record<string, string>;
+  /** Key-value metadata surfaced via provider list/query APIs */
+  metadata?: Record<string, string>;
+  /** Sandbox idle timeout in milliseconds */
+  timeoutMs?: number;
+  /** Enable or disable outbound internet access */
+  allowInternetAccess?: boolean;
+  /** Outbound network allow/deny rules */
+  network?: SandboxNetworkConfig;
+  /** Sandbox timeout behaviour */
+  lifecycle?: SandboxLifecycleConfig;
 }
 
 export interface SandboxCreateResult {
@@ -133,9 +158,23 @@ export interface SandboxProvider<
   pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
   /** Resume a paused sandbox. No-op if already running. */
   resume(sandboxId: string): Promise<void>;
-  snapshot(sandboxId: string): Promise<SandboxSnapshot>;
-  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
-  fork(sandboxId: string): Promise<Sandbox>;
+  /**
+   * Capture a snapshot of a running sandbox. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  snapshot(sandboxId: string, options?: TOptions): Promise<SandboxSnapshot>;
+  /**
+   * Restore a sandbox from a snapshot. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  restore(snapshot: SandboxSnapshot, options?: TOptions): Promise<Sandbox>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSnapshot(snapshot: SandboxSnapshot): Promise<void>;
+  /**
+   * Fork a running sandbox into a new one. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  fork(sandboxId: string, options?: TOptions): Promise<Sandbox>;
 }
 
 // ============================================================================
@@ -154,8 +193,20 @@ export interface SandboxOps<
   pauseSandbox(sandboxId: string): Promise<void>;
   /** Resume a paused sandbox. No-op if already running. */
   resumeSandbox(sandboxId: string): Promise<void>;
-  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
-  forkSandbox(sandboxId: string): Promise<string>;
+  /** Capture a snapshot. `options` is a per-call override merged on top of provider defaults. */
+  snapshotSandbox(
+    sandboxId: string,
+    options?: TOptions
+  ): Promise<SandboxSnapshot>;
+  /** Create a fresh sandbox from a snapshot. `options` is a per-call override merged on top of provider defaults. */
+  restoreSandbox(
+    snapshot: SandboxSnapshot,
+    options?: TOptions
+  ): Promise<string>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSandboxSnapshot(snapshot: SandboxSnapshot): Promise<void>;
+  /** Fork a running sandbox. `options` is a per-call override merged on top of provider defaults. */
+  forkSandbox(sandboxId: string, options?: TOptions): Promise<string>;
 }
 
 /**
@@ -172,7 +223,10 @@ export type PrefixedSandboxOps<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TCtx = unknown,
 > = {
-  [K in keyof SandboxOps<TOptions, TCtx> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
+  [K in keyof SandboxOps<
+    TOptions,
+    TCtx
+  > as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
 };
 
 // ============================================================================