zeitlich 0.2.40 → 0.2.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -156,26 +156,6 @@
         "types": "./dist/adapters/sandbox/e2b/workflow.d.ts",
         "default": "./dist/adapters/sandbox/e2b/workflow.js"
       }
-    },
-    "./adapters/sandbox/bedrock": {
-      "import": {
-        "types": "./dist/adapters/sandbox/bedrock/index.d.ts",
-        "default": "./dist/adapters/sandbox/bedrock/index.js"
-      },
-      "require": {
-        "types": "./dist/adapters/sandbox/bedrock/index.d.ts",
-        "default": "./dist/adapters/sandbox/bedrock/index.js"
-      }
-    },
-    "./adapters/sandbox/bedrock/workflow": {
-      "import": {
-        "types": "./dist/adapters/sandbox/bedrock/workflow.d.ts",
-        "default": "./dist/adapters/sandbox/bedrock/workflow.js"
-      },
-      "require": {
-        "types": "./dist/adapters/sandbox/bedrock/workflow.d.ts",
-        "default": "./dist/adapters/sandbox/bedrock/workflow.js"
-      }
     }
   },
   "files": [
@@ -220,15 +200,16 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.81.0",
-    "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
-    "@daytonaio/sdk": "^0.158.1",
+    "@anthropic-ai/sdk": "^0.93.0",
+    "@daytonaio/sdk": "^0.171.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@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",
+    "@temporalio/common": "^1.17.0",
+    "@temporalio/envconfig": "^1.17.0",
+    "@temporalio/worker": "^1.17.0",
+    "@temporalio/workflow": "^1.17.0",
     "@types/node": "^25.3.3",
     "eslint": "^10.0.2",
     "husky": "^9.1.7",
@@ -242,18 +223,18 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.50.0",
-    "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
     "@daytonaio/sdk": ">=0.153.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@google/genai": "^1.43.0",
     "@langchain/core": ">=1.0.0",
+    "@temporalio/common": ">=1.16.0 <2.0.0",
+    "@temporalio/envconfig": ">=1.16.0 <2.0.0",
+    "@temporalio/worker": ">=1.16.0 <2.0.0",
+    "@temporalio/workflow": ">=1.16.0 <2.0.0",
     "ioredis": ">=5.0.0",
     "just-bash": ">=2.0.0"
   },
   "peerDependenciesMeta": {
-    "@aws-sdk/client-bedrock-agentcore": {
-      "optional": true
-    },
     "@daytonaio/sdk": {
       "optional": true
     },
@@ -266,6 +247,12 @@
     "@langchain/core": {
       "optional": true
     },
+    "@temporalio/envconfig": {
+      "optional": true
+    },
+    "@temporalio/worker": {
+      "optional": true
+    },
     "just-bash": {
       "optional": true
     }
@@ -276,9 +263,6 @@
   },
   "homepage": "https://github.com/bead-ai/zeitlich#readme",
   "dependencies": {
-    "@temporalio/common": "^1.15.0",
-    "@temporalio/plugin": "^1.15.0",
-    "@temporalio/workflow": "^1.15.0",
     "zod": "^4.3.6"
   }
 }

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

@@ -2,16 +2,13 @@ import { Daytona, type Sandbox as DaytonaSdkSandbox } from "@daytonaio/sdk";
 import type {
   Sandbox,
   SandboxCapabilities,
+  SandboxCapability,
   SandboxCreateResult,
   SandboxProvider,
-  SandboxSnapshot,
   ExecOptions,
   ExecResult,
 } from "../../../lib/sandbox/types";
-import {
-  SandboxNotFoundError,
-  SandboxNotSupportedError,
-} from "../../../lib/sandbox/types";
+import { SandboxNotFoundError } from "../../../lib/sandbox/types";
 import { DaytonaSandboxFileSystem } from "./filesystem";
 import type {
   DaytonaSandbox,
@@ -64,16 +61,35 @@ class DaytonaSandboxImpl implements Sandbox {
 // DaytonaSandboxProvider
 // ============================================================================
 
-export class DaytonaSandboxProvider implements SandboxProvider<
-  DaytonaSandboxCreateOptions,
-  DaytonaSandbox
-> {
+/**
+ * Single source of truth for the Daytona adapter's capability set. Daytona
+ * implements only base lifecycle (`create` / `get` / `destroy`); both the
+ * type-level `TCaps` (`never`) and the runtime `supportedCapabilities`
+ * set fall out of this empty array, so the two surfaces cannot drift.
+ */
+const DAYTONA_CAPS = [] as const satisfies readonly SandboxCapability[];
+type DaytonaCaps = (typeof DAYTONA_CAPS)[number]; // → never
+
+/**
+ * Daytona implements only base sandbox lifecycle (`create` / `get` /
+ * `destroy`). Snapshot, restore, fork, pause, and resume are not supported
+ * — the type-level capability set is `never`, so calling any of those
+ * methods on a Daytona provider, manager, or `SandboxOps` proxy is a
+ * compile-time TypeScript error.
+ */
+export class DaytonaSandboxProvider
+  implements
+    SandboxProvider<DaytonaSandboxCreateOptions, DaytonaSandbox, DaytonaCaps>
+{
   readonly id = "daytona";
   readonly capabilities: SandboxCapabilities = {
     filesystem: true,
     execution: true,
     persistence: false,
   };
+  readonly supportedCapabilities: ReadonlySet<DaytonaCaps> = new Set(
+    DAYTONA_CAPS
+  );
 
   private client: Daytona;
   private readonly defaultWorkspaceBase: string;
@@ -140,45 +156,6 @@ export class DaytonaSandboxProvider implements SandboxProvider<
       // Already gone
     }
   }
-
-  async pause(_sandboxId: string, _ttlSeconds?: number): Promise<void> {
-    throw new SandboxNotSupportedError("pause");
-  }
-
-  async resume(_sandboxId: string): Promise<void> {
-    // Daytona sandboxes don't support pause, so resume is a no-op
-  }
-
-  async fork(
-    _sandboxId: string,
-    _options?: DaytonaSandboxCreateOptions
-  ): Promise<Sandbox> {
-    throw new Error("Not implemented");
-  }
-
-  async snapshot(
-    _sandboxId: string,
-    _options?: DaytonaSandboxCreateOptions
-  ): Promise<SandboxSnapshot> {
-    throw new SandboxNotSupportedError(
-      "snapshot (use Daytona's native snapshot API directly)"
-    );
-  }
-
-  async restore(
-    _snapshot: SandboxSnapshot,
-    _options?: DaytonaSandboxCreateOptions
-  ): Promise<never> {
-    throw new SandboxNotSupportedError(
-      "restore (use Daytona's native snapshot API directly)"
-    );
-  }
-
-  async deleteSnapshot(_snapshot: SandboxSnapshot): Promise<void> {
-    throw new SandboxNotSupportedError(
-      "deleteSnapshot (use Daytona's native snapshot API directly)"
-    );
-  }
 }
 
 // Re-exports

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

@@ -10,6 +10,11 @@
  * By default the scope is derived from `workflowInfo().workflowType`,
  * so activities are automatically namespaced per workflow.
  *
+ * Daytona only exposes base sandbox lifecycle (`create`/`destroy`) — the
+ * returned proxy is typed with `TCaps = never`, so calling
+ * `pauseSandbox` / `snapshotSandbox` / `forkSandbox` / etc. on it is a
+ * TypeScript error rather than a runtime throw.
+ *
  * @example
  * ```typescript
  * import { proxyDaytonaSandboxOps } from 'zeitlich/adapters/sandbox/daytona/workflow';
@@ -26,7 +31,7 @@ const ADAPTER_PREFIX = "daytona";
 export function proxyDaytonaSandboxOps(
   scope?: string,
   options?: Parameters<typeof proxyActivities>[0]
-): SandboxOps {
+): SandboxOps<DaytonaSandboxCreateOptions, unknown, never> {
   const resolvedScope = scope ?? workflowInfo().workflowType;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -49,11 +54,5 @@ export function proxyDaytonaSandboxOps(
   return {
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
-    pauseSandbox: acts[p("pauseSandbox")],
-    resumeSandbox: acts[p("resumeSandbox")],
-    snapshotSandbox: acts[p("snapshotSandbox")],
-    restoreSandbox: acts[p("restoreSandbox")],
-    deleteSandboxSnapshot: acts[p("deleteSandboxSnapshot")],
-    forkSandbox: acts[p("forkSandbox")],
-  } as SandboxOps<DaytonaSandboxCreateOptions>;
+  } as SandboxOps<DaytonaSandboxCreateOptions, unknown, never>;
 }

package/src/adapters/sandbox/e2b/README.md

@@ -0,0 +1,81 @@
+# E2B Sandbox Adapter
+
+Adapter that exposes [E2B](https://e2b.dev/) cloud sandboxes through the
+standard `SandboxProvider` interface used by the rest of Zeitlich.
+
+## Configuration
+
+`E2bSandboxProvider` accepts an `E2bSandboxConfig` (provider-level defaults).
+Per-create overrides may be passed to `create()` via `E2bSandboxCreateOptions`.
+
+```ts
+import { E2bSandboxProvider } from "zeitlich/adapters/sandbox/e2b";
+
+const provider = new E2bSandboxProvider({
+  template: "my-template",
+  timeoutMs: 15 * 60 * 1000, // kill-on-abandon safety net
+  keepAliveMs: 15 * 60 * 1000, // refreshed on every tool call
+});
+```
+
+## Keep-alive pattern
+
+E2B's `timeoutMs` on `Sandbox.create` is a **sandbox lifetime**, not an idle
+timeout: when it elapses, E2B kills the sandbox regardless of activity. Long
+agent loops (LLM thinking + many tool calls) can outlive that window, and the
+next tool call hits `Sandbox.connect(sandboxId)` and surfaces a
+`SandboxNotFoundError` mid-run.
+
+`keepAliveMs` solves this without giving up the kill-on-abandon safety net.
+When set, every call to `provider.get(sandboxId)` passes
+`{ timeoutMs: keepAliveMs }` to `Sandbox.connect()`. Per the E2B SDK's
+`SandboxConnectOpts.timeoutMs` JSDoc:
+
+> For running sandboxes, the timeout will update only if the new timeout is
+> longer than the existing one.
+
+So `connect()` with a `timeoutMs` is **monotonic**: it never shrinks the
+lifetime of a running sandbox. Pick `keepAliveMs` as the **full per-call
+refresh window** you want — passing a value smaller than the time remaining
+is a no-op rather than a shrink, but you should still pick the value with
+"every tool call should give me at least this much headroom" in mind, not
+"floor to add".
+
+`provider.get()` is invoked exactly once per tool call by `withSandbox`, so:
+
+- An active session's tool calls each refresh the lifetime to at least
+  `keepAliveMs`. The sandbox cannot be killed mid-run as long as tools are
+  still firing — conceptually this is the sandbox equivalent of a Temporal
+  activity heartbeat.
+- An abandoned sandbox still dies `keepAliveMs` after the last tool call. The
+  existing kill-on-timeout safety net is preserved.
+- Consumers can drop `timeoutMs` back down to short, safe values (e.g.
+  15 minutes) without tuning against worst-case run length.
+
+### Recommended usage
+
+- Set `timeoutMs` to a value that bounds how long a sandbox can sit unused
+  after the consumer abnormally terminates (worker crash, workflow terminated,
+  `workflowRunTimeout`). This is your **abandon safety net**.
+- Set `keepAliveMs` to your **per-call refresh window** — typically the same
+  value as `timeoutMs`, or shorter if you want sandboxes to be reaped sooner
+  after the last tool call.
+
+### Provider-level only
+
+`keepAliveMs` is a provider-construction-time config. There is intentionally
+no per-create override: every sandbox managed by the provider refreshes by
+the same amount on each `get()`. If a real use case for per-sandbox refresh
+windows ever shows up we can add it without breaking changes.
+
+### When connect-with-options is not enough
+
+If you ever need to **shrink** a sandbox's remaining lifetime (e.g. force an
+early reap), `connect()` won't do it because of the monotonic-extend rule
+above. Use `Sandbox.setTimeout(timeoutMs)` or the static
+`SandboxApi.setTimeout(sandboxId, timeoutMs)` instead — those can extend or
+reduce.
+
+If E2B ever changes the semantics of `Sandbox.connect(sandboxId, { timeoutMs })`
+so it stops extending a running sandbox's lifetime at all, `setTimeout` is
+also a drop-in replacement for the call site in `provider.get()`.

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

@@ -1,7 +1,12 @@
-import { Sandbox as E2bSdkSandbox } from "@e2b/code-interpreter";
+import {
+  NotFoundError as E2bNotFoundError,
+  Sandbox as E2bSdkSandbox,
+  SandboxNotFoundError as E2bSandboxNotFoundError,
+} from "@e2b/code-interpreter";
 import type {
   Sandbox,
   SandboxCapabilities,
+  SandboxCapability,
   SandboxCreateResult,
   SandboxProvider,
   SandboxSnapshot,
@@ -19,6 +24,20 @@ import type {
   E2bSandboxCreateOptions,
 } from "./types";
 
+/**
+ * True iff `err` is the E2B SDK's "this sandbox doesn't exist (anymore)"
+ * signal. We narrow to `SandboxNotFoundError` (the canonical class) and to
+ * its deprecated parent `NotFoundError` as a defensive fallback — older
+ * SDK paths still throw the parent for sandbox-not-found cases. Any other
+ * error (auth failure, network blip, 5xx, validation) is propagated
+ * unchanged so callers can react to it specifically.
+ */
+function isE2bSandboxNotFound(err: unknown): boolean {
+  return (
+    err instanceof E2bSandboxNotFoundError || err instanceof E2bNotFoundError
+  );
+}
+
 // ============================================================================
 // E2bSandbox
 // ============================================================================
@@ -62,20 +81,35 @@ class E2bSandboxImpl implements Sandbox {
 // E2bSandboxProvider
 // ============================================================================
 
-export class E2bSandboxProvider implements SandboxProvider<
-  E2bSandboxCreateOptions,
-  E2bSandbox
-> {
+/**
+ * Single source of truth for the E2B adapter's capability set. Both the
+ * runtime `supportedCapabilities` set and the type-level `TCaps` flow
+ * out of this array, so the two surfaces cannot drift.
+ */
+export const E2B_CAPS = [
+  "pause",
+  "resume",
+  "snapshot",
+  "restore",
+  "fork",
+] as const satisfies readonly SandboxCapability[];
+export type E2bCaps = (typeof E2B_CAPS)[number];
+
+export class E2bSandboxProvider
+  implements SandboxProvider<E2bSandboxCreateOptions, E2bSandbox, E2bCaps>
+{
   readonly id = "e2b";
   readonly capabilities: SandboxCapabilities = {
     filesystem: true,
     execution: true,
     persistence: true,
   };
+  readonly supportedCapabilities: ReadonlySet<E2bCaps> = new Set(E2B_CAPS);
 
   private readonly defaultTemplate?: string;
   private readonly defaultWorkspaceBase: string;
   private readonly defaultTimeoutMs?: number;
+  private readonly defaultKeepAliveMs?: number;
   private readonly defaultAllowInternetAccess?: boolean;
   private readonly defaultNetwork?: E2bSandboxConfig["network"];
   private readonly defaultMetadata?: E2bSandboxConfig["metadata"];
@@ -85,6 +119,7 @@ export class E2bSandboxProvider implements SandboxProvider<
     this.defaultTemplate = config?.template;
     this.defaultWorkspaceBase = config?.workspaceBase ?? "/home/user";
     this.defaultTimeoutMs = config?.timeoutMs;
+    this.defaultKeepAliveMs = config?.keepAliveMs;
     this.defaultAllowInternetAccess = config?.allowInternetAccess;
     this.defaultNetwork = config?.network;
     this.defaultMetadata = config?.metadata;
@@ -120,15 +155,22 @@ export class E2bSandboxProvider implements SandboxProvider<
   }
 
   async get(sandboxId: string): Promise<E2bSandbox> {
+    const keepAliveMs = this.defaultKeepAliveMs;
     try {
-      const sdkSandbox = await E2bSdkSandbox.connect(sandboxId);
+      const sdkSandbox =
+        keepAliveMs !== undefined
+          ? await E2bSdkSandbox.connect(sandboxId, { timeoutMs: keepAliveMs })
+          : await E2bSdkSandbox.connect(sandboxId);
       return new E2bSandboxImpl(
         sandboxId,
         sdkSandbox,
         this.defaultWorkspaceBase
       );
-    } catch {
-      throw new SandboxNotFoundError(sandboxId);
+    } catch (err) {
+      if (isE2bSandboxNotFound(err)) {
+        throw new SandboxNotFoundError(sandboxId);
+      }
+      throw err;
     }
   }
 
@@ -137,7 +179,7 @@ export class E2bSandboxProvider implements SandboxProvider<
       const sdkSandbox = await E2bSdkSandbox.connect(sandboxId);
       await sdkSandbox.kill();
     } catch {
-      // Already gone or not found
+      // Already gone or not found — destroy is idempotent.
     }
   }
 
@@ -166,7 +208,7 @@ export class E2bSandboxProvider implements SandboxProvider<
   async restore(
     snapshot: SandboxSnapshot,
     options?: E2bSandboxCreateOptions
-  ): Promise<Sandbox> {
+  ): Promise<E2bSandbox> {
     const data = snapshot.data as { snapshotId?: string } | null;
     if (!data?.snapshotId) {
       throw new SandboxNotSupportedError(
@@ -195,7 +237,7 @@ export class E2bSandboxProvider implements SandboxProvider<
   async fork(
     sandboxId: string,
     options?: E2bSandboxCreateOptions
-  ): Promise<Sandbox> {
+  ): Promise<E2bSandbox> {
     const { snapshotId } = await E2bSdkSandbox.createSnapshot(sandboxId);
     const sdkOpts = this.buildSdkCreateOpts(options);
     const sdkSandbox = await E2bSdkSandbox.create(snapshotId, sdkOpts);

package/src/adapters/sandbox/e2b/keep-alive.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  Sandbox as E2bSdkSandbox,
+  SandboxNotFoundError as E2bSandboxNotFoundError,
+} from "@e2b/code-interpreter";
+import { E2bSandboxProvider } from "./index";
+import { SandboxNotFoundError } from "../../../lib/sandbox/types";
+
+vi.mock("@e2b/code-interpreter", () => {
+  class FakeSdkSandbox {
+    static create = vi.fn();
+    static connect = vi.fn();
+    static createSnapshot = vi.fn();
+    static deleteSnapshot = vi.fn();
+    sandboxId: string;
+    constructor(sandboxId: string) {
+      this.sandboxId = sandboxId;
+    }
+    commands = { run: vi.fn() };
+    files = {};
+    async kill() {}
+    async pause() {}
+  }
+  // Mirror the real SDK error class hierarchy: SandboxNotFoundError extends
+  // (deprecated) NotFoundError extends SandboxError extends Error.
+  class FakeSandboxError extends Error {}
+  class FakeNotFoundError extends FakeSandboxError {}
+  class FakeSandboxNotFoundError extends FakeNotFoundError {}
+  return {
+    Sandbox: FakeSdkSandbox,
+    SandboxError: FakeSandboxError,
+    NotFoundError: FakeNotFoundError,
+    SandboxNotFoundError: FakeSandboxNotFoundError,
+  };
+});
+
+const sdk = E2bSdkSandbox as unknown as {
+  create: ReturnType<typeof vi.fn>;
+  connect: ReturnType<typeof vi.fn>;
+  createSnapshot: ReturnType<typeof vi.fn>;
+};
+
+function makeFakeSdkSandbox(id = "sbx-1") {
+  return {
+    sandboxId: id,
+    commands: { run: vi.fn() },
+    files: {},
+    kill: vi.fn(),
+    pause: vi.fn(),
+  };
+}
+
+describe("E2bSandboxProvider keep-alive", () => {
+  beforeEach(() => {
+    sdk.create.mockReset();
+    sdk.connect.mockReset();
+    sdk.createSnapshot.mockReset();
+  });
+
+  it("forwards timeoutMs to connect() when keepAliveMs is configured at the provider level", async () => {
+    const fake = makeFakeSdkSandbox();
+    sdk.connect.mockResolvedValue(fake);
+
+    const provider = new E2bSandboxProvider({ keepAliveMs: 15 * 60 * 1000 });
+    const sandbox = await provider.get("sbx-1");
+
+    expect(sandbox.id).toBe("sbx-1");
+    expect(sdk.connect).toHaveBeenCalledTimes(1);
+    expect(sdk.connect).toHaveBeenCalledWith("sbx-1", {
+      timeoutMs: 15 * 60 * 1000,
+    });
+  });
+
+  it("omits timeoutMs from connect() when keepAliveMs is not configured", async () => {
+    const fake = makeFakeSdkSandbox();
+    sdk.connect.mockResolvedValue(fake);
+
+    const provider = new E2bSandboxProvider();
+    await provider.get("sbx-1");
+
+    expect(sdk.connect).toHaveBeenCalledTimes(1);
+    expect(sdk.connect).toHaveBeenCalledWith("sbx-1");
+  });
+
+  it("uses provider-level keepAliveMs for every sandbox managed by the provider", async () => {
+    const fake = makeFakeSdkSandbox("sbx-default");
+    sdk.connect.mockResolvedValue(fake);
+
+    const provider = new E2bSandboxProvider({ keepAliveMs: 60_000 });
+    await provider.get("sbx-default");
+
+    expect(sdk.connect).toHaveBeenCalledWith("sbx-default", {
+      timeoutMs: 60_000,
+    });
+  });
+
+  it("translates the SDK's SandboxNotFoundError into our SandboxNotFoundError", async () => {
+    sdk.connect.mockRejectedValue(
+      new E2bSandboxNotFoundError("sandbox missing-sbx not found")
+    );
+
+    const provider = new E2bSandboxProvider({ keepAliveMs: 60_000 });
+    await expect(provider.get("missing-sbx")).rejects.toBeInstanceOf(
+      SandboxNotFoundError
+    );
+  });
+
+  it("propagates non-not-found connect() errors unchanged (auth, network, 5xx)", async () => {
+    const transient = new Error("ECONNRESET: socket hang up");
+    sdk.connect.mockRejectedValue(transient);
+
+    const provider = new E2bSandboxProvider({ keepAliveMs: 60_000 });
+    await expect(provider.get("sbx-1")).rejects.toBe(transient);
+  });
+});

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

@@ -19,6 +19,7 @@
  */
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
 import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { E2bCaps } from "./index";
 import type { E2bSandboxCreateOptions } from "./types";
 
 const ADAPTER_PREFIX = "e2b";
@@ -26,7 +27,7 @@ const ADAPTER_PREFIX = "e2b";
 export function proxyE2bSandboxOps(
   scope?: string,
   options?: Parameters<typeof proxyActivities>[0]
-): SandboxOps {
+): SandboxOps<E2bSandboxCreateOptions, unknown, E2bCaps> {
   const resolvedScope = scope ?? workflowInfo().workflowType;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -55,5 +56,5 @@ export function proxyE2bSandboxOps(
     restoreSandbox: acts[p("restoreSandbox")],
     deleteSandboxSnapshot: acts[p("deleteSandboxSnapshot")],
     forkSandbox: acts[p("forkSandbox")],
-  } as SandboxOps<E2bSandboxCreateOptions>;
+  } as SandboxOps<E2bSandboxCreateOptions, unknown, E2bCaps>;
 }

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

@@ -19,8 +19,35 @@ export interface E2bSandboxConfig {
   template?: string;
   /** Default working directory inside the sandbox */
   workspaceBase?: string;
-  /** Sandbox idle timeout in milliseconds */
+  /**
+   * Sandbox lifetime in milliseconds. Despite the name, this is **not** an
+   * idle timeout: E2B kills the sandbox once this many milliseconds elapse
+   * from creation regardless of activity. Pair with {@link keepAliveMs} to
+   * refresh the lifetime on every `provider.get()` call so that this value
+   * acts as a kill-on-abandon safety net rather than a hard cap on run
+   * length.
+   */
   timeoutMs?: number;
+  /**
+   * If set, every call to `provider.get(sandboxId)` passes
+   * `{ timeoutMs: keepAliveMs }` to `Sandbox.connect()`, refreshing the
+   * sandbox lifetime on each tool invocation. The provider-level
+   * `timeoutMs` then acts as a kill-on-abandon safety net rather than a
+   * hard cap on run length.
+   *
+   * E2B's `Sandbox.connect()` is monotonic for running sandboxes: per the
+   * SDK's `SandboxConnectOpts.timeoutMs` doc, "the timeout will update
+   * only if the new timeout is longer than the existing one". Pick
+   * `keepAliveMs` as the full per-call refresh window you want; passing a
+   * value smaller than the time remaining is a no-op rather than a
+   * shrink. (If you ever need to shrink, use `Sandbox.setTimeout` /
+   * `SandboxApi.setTimeout`, which can extend or reduce.)
+   *
+   * Per-sandbox overrides are intentionally not exposed — this is a
+   * provider-level config only. Every sandbox managed by the provider
+   * refreshes by the same amount on each `get()`.
+   */
+  keepAliveMs?: number;
   /** Default outbound internet access policy */
   allowInternetAccess?: boolean;
   /** Default outbound network allow/deny rules */
@@ -34,6 +61,11 @@ export interface E2bSandboxConfig {
 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 */
+  /**
+   * Sandbox lifetime in milliseconds — overrides the provider default. See
+   * {@link E2bSandboxConfig.timeoutMs} for the full semantics; pair with
+   * the provider-level `keepAliveMs` to refresh on every `provider.get()`
+   * call.
+   */
   timeoutMs?: number;
 }

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

@@ -8,6 +8,7 @@ import {
 import type {
   Sandbox,
   SandboxCapabilities,
+  SandboxCapability,
   SandboxCreateOptions,
   SandboxCreateResult,
   SandboxFileSystem,
@@ -133,13 +134,32 @@ class InMemorySandboxImpl implements Sandbox {
 // InMemorySandboxProvider
 // ============================================================================
 
-export class InMemorySandboxProvider implements SandboxProvider {
+/**
+ * Single source of truth for the in-memory adapter's capability set. The
+ * runtime `supportedCapabilities` set and the type-level `TCaps` are both
+ * derived from this array, so the two surfaces cannot drift.
+ */
+export const IN_MEMORY_CAPS = [
+  "pause",
+  "resume",
+  "snapshot",
+  "restore",
+  "fork",
+] as const satisfies readonly SandboxCapability[];
+export type InMemoryCaps = (typeof IN_MEMORY_CAPS)[number];
+
+export class InMemorySandboxProvider
+  implements SandboxProvider<SandboxCreateOptions, Sandbox, InMemoryCaps>
+{
   readonly id = "inMemory";
   readonly capabilities: SandboxCapabilities = {
     filesystem: true,
     execution: true,
     persistence: true,
   };
+  readonly supportedCapabilities: ReadonlySet<InMemoryCaps> = new Set(
+    IN_MEMORY_CAPS
+  );
 
   private sandboxes = new Map<string, InMemorySandboxImpl>();