zeitlich 0.2.27 → 0.2.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -107,26 +107,6 @@
         "default": "./dist/adapters/sandbox/inmemory/workflow.js"
       }
     },
-    "./adapters/sandbox/virtual": {
-      "import": {
-        "types": "./dist/adapters/sandbox/virtual/index.d.ts",
-        "default": "./dist/adapters/sandbox/virtual/index.js"
-      },
-      "require": {
-        "types": "./dist/adapters/sandbox/virtual/index.d.ts",
-        "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",
@@ -147,6 +127,26 @@
         "default": "./dist/adapters/sandbox/daytona/workflow.js"
       }
     },
+    "./adapters/sandbox/e2b": {
+      "import": {
+        "types": "./dist/adapters/sandbox/e2b/index.d.ts",
+        "default": "./dist/adapters/sandbox/e2b/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/sandbox/e2b/index.d.ts",
+        "default": "./dist/adapters/sandbox/e2b/index.js"
+      }
+    },
+    "./adapters/sandbox/e2b/workflow": {
+      "import": {
+        "types": "./dist/adapters/sandbox/e2b/workflow.d.ts",
+        "default": "./dist/adapters/sandbox/e2b/workflow.js"
+      },
+      "require": {
+        "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",
@@ -212,7 +212,7 @@
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
     "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
-    "@daytonaio/sdk": "^0.149.0",
+    "@daytonaio/sdk": "^0.158.1",
     "@e2b/code-interpreter": "^2.3.3",
     "@eslint/js": "^10.0.1",
     "@google/genai": "^1.44.0",
@@ -226,7 +226,7 @@
     "prettier": "^3.8.1",
     "release-please": "^17.3.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
   },

package/src/adapters/sandbox/{virtual → e2b}/proxy.ts

@@ -1,7 +1,10 @@
 /**
- * Workflow-safe proxy for virtual sandbox operations.
+ * Workflow-safe proxy for E2B sandbox operations.
  *
- * Import this from `zeitlich/adapters/sandbox/virtual/workflow`
+ * Uses longer timeouts than in-memory providers since E2B
+ * sandboxes are remote and creation involves provisioning.
+ *
+ * Import this from `zeitlich/adapters/sandbox/e2b/workflow`
  * in your Temporal workflow files.
  *
  * By default the scope is derived from `workflowInfo().workflowType`,
@@ -9,32 +12,32 @@
  *
  * @example
  * ```typescript
- * import { proxyVirtualSandboxOps } from 'zeitlich/adapters/sandbox/virtual/workflow';
+ * import { proxyE2bSandboxOps } from 'zeitlich/adapters/sandbox/e2b/workflow';
  *
- * const sandbox = proxyVirtualSandboxOps();
+ * const sandbox = proxyE2bSandboxOps();
  * ```
  */
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
 import type { SandboxOps } from "../../../lib/sandbox/types";
-import type { VirtualSandboxCreateOptions } from "./types";
+import type { E2bSandboxCreateOptions } from "./types";
 
-const ADAPTER_PREFIX = "virtual";
+const ADAPTER_PREFIX = "e2b";
 
-export function proxyVirtualSandboxOps(
+export function proxyE2bSandboxOps(
   scope?: string,
   options?: Parameters<typeof proxyActivities>[0]
-): SandboxOps<VirtualSandboxCreateOptions<unknown>> {
+): 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",
+      startToCloseTimeout: "120s",
       retry: {
         maximumAttempts: 3,
-        initialInterval: "2s",
-        maximumInterval: "30s",
-        backoffCoefficient: 2,
+        initialInterval: "5s",
+        maximumInterval: "60s",
+        backoffCoefficient: 3,
       },
     }
   );
@@ -49,5 +52,5 @@ export function proxyVirtualSandboxOps(
     pauseSandbox: acts[p("pauseSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
-  } as SandboxOps<VirtualSandboxCreateOptions<unknown>>;
+  } as SandboxOps<E2bSandboxCreateOptions>;
 }

package/src/adapters/thread/langchain/hooks.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import { HumanMessage, AIMessage } from "@langchain/core/messages";
+import type { BaseMessage } from "@langchain/core/messages";
+import { appendCachePoint } from "./hooks";
+
+const cacheBlock = { type: "cache_control" as const, cache_control: { type: "ephemeral" as const } };
+
+function applyHook(
+  messages: BaseMessage[],
+  hook: ReturnType<typeof appendCachePoint>,
+): BaseMessage[] {
+  return messages.map((m, i, arr) => hook(m, i, arr));
+}
+
+function countCacheBlocks(messages: BaseMessage[]): number {
+  return messages.reduce((n, m) => {
+    const c = m.content;
+    if (Array.isArray(c)) {
+      return n + (c.some((b) => b.type === cacheBlock.type) ? 1 : 0);
+    }
+    return n;
+  }, 0);
+}
+
+function messageAt(messages: BaseMessage[], idx: number): BaseMessage {
+  const m = messages[idx];
+  if (!m) throw new Error(`No message at index ${String(idx)}`);
+  return m;
+}
+
+describe("appendCachePoint", () => {
+  it("appends a cache block to the last message", () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage("hello"),
+      new AIMessage("hi"),
+      new HumanMessage("bye"),
+    ];
+    const hook = appendCachePoint(cacheBlock);
+    const result = applyHook(messages, hook);
+
+    const last = messageAt(result, 2);
+    expect(Array.isArray(last.content)).toBe(true);
+    const blocks = last.content as Array<{ type: string }>;
+    expect(blocks.some((b) => b.type === cacheBlock.type)).toBe(true);
+  });
+
+  it("deduplicates within the last message", () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage({
+        content: [
+          { type: "text", text: "hello" },
+          cacheBlock,
+        ],
+      }),
+    ];
+    const hook = appendCachePoint(cacheBlock);
+    const result = applyHook(messages, hook);
+
+    const blocks = (messageAt(result, 0).content as Array<{ type: string }>).filter(
+      (b) => b.type === cacheBlock.type,
+    );
+    expect(blocks).toHaveLength(1);
+  });
+
+  it("strips old cache blocks when total would exceed maxBlocks", () => {
+    const messages: BaseMessage[] = Array.from({ length: 6 }, (_, i) =>
+      new HumanMessage({
+        content: [
+          { type: "text", text: `msg ${i}` },
+          cacheBlock,
+        ],
+      }),
+    );
+    const hook = appendCachePoint(cacheBlock, { maxBlocks: 4 });
+    const result = applyHook(messages, hook);
+
+    expect(countCacheBlocks(result)).toBe(4);
+  });
+
+  it("keeps the most recent cache blocks", () => {
+    const messages: BaseMessage[] = Array.from({ length: 6 }, (_, i) =>
+      new HumanMessage({
+        content: [
+          { type: "text", text: `msg ${i}` },
+          cacheBlock,
+        ],
+      }),
+    );
+    const hook = appendCachePoint(cacheBlock, { maxBlocks: 4 });
+    const result = applyHook(messages, hook);
+
+    const hasCache = result.map((m) => {
+      const c = m.content;
+      return Array.isArray(c) && c.some((b) => b.type === cacheBlock.type);
+    });
+    expect(hasCache[0]).toBe(false);
+    expect(hasCache[1]).toBe(false);
+    expect(hasCache[3]).toBe(true);
+    expect(hasCache[4]).toBe(true);
+    expect(hasCache[5]).toBe(true);
+  });
+
+  it("respects a custom maxBlocks value", () => {
+    const messages: BaseMessage[] = Array.from({ length: 5 }, (_, i) =>
+      new HumanMessage({
+        content: [
+          { type: "text", text: `msg ${i}` },
+          cacheBlock,
+        ],
+      }),
+    );
+    const hook = appendCachePoint(cacheBlock, { maxBlocks: 2 });
+    const result = applyHook(messages, hook);
+
+    expect(countCacheBlocks(result)).toBe(2);
+  });
+
+  it("does nothing to non-last messages without cache blocks", () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage("plain"),
+      new AIMessage("response"),
+      new HumanMessage("last"),
+    ];
+    const hook = appendCachePoint(cacheBlock);
+    const result = applyHook(messages, hook);
+
+    expect(messageAt(result, 0).content).toBe("plain");
+    expect(messageAt(result, 1).content).toBe("response");
+    expect(countCacheBlocks(result)).toBe(1);
+  });
+
+  it("handles string content on the last message", () => {
+    const messages: BaseMessage[] = [new HumanMessage("only")];
+    const hook = appendCachePoint(cacheBlock);
+    const result = applyHook(messages, hook);
+
+    const first = messageAt(result, 0);
+    expect(Array.isArray(first.content)).toBe(true);
+    const content = first.content as Array<{ type: string }>;
+    expect(content.some((b) => b.type === cacheBlock.type)).toBe(true);
+  });
+
+  it("defaults maxBlocks to 4", () => {
+    const messages: BaseMessage[] = Array.from({ length: 8 }, (_, i) =>
+      new HumanMessage({
+        content: [
+          { type: "text", text: `msg ${i}` },
+          cacheBlock,
+        ],
+      }),
+    );
+    const hook = appendCachePoint(cacheBlock);
+    const result = applyHook(messages, hook);
+
+    expect(countCacheBlocks(result)).toBe(4);
+  });
+
+  it("preserves non-cache content blocks when stripping", () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage({
+        content: [
+          { type: "text", text: "keep me" },
+          cacheBlock,
+          { type: "image_url", image_url: { url: "http://example.com" } },
+        ],
+      }),
+      new HumanMessage({
+        content: [
+          { type: "text", text: "msg 1" },
+          cacheBlock,
+        ],
+      }),
+      new HumanMessage({
+        content: [
+          { type: "text", text: "msg 2" },
+          cacheBlock,
+        ],
+      }),
+      new HumanMessage({
+        content: [
+          { type: "text", text: "msg 3" },
+          cacheBlock,
+        ],
+      }),
+      new HumanMessage("last"),
+    ];
+    const hook = appendCachePoint(cacheBlock, { maxBlocks: 4 });
+    const result = applyHook(messages, hook);
+
+    const first = messageAt(result, 0).content as Array<{ type: string }>;
+    expect(first.some((b) => b.type === "text")).toBe(true);
+    expect(first.some((b) => b.type === "image_url")).toBe(true);
+    expect(first.some((b) => b.type === cacheBlock.type)).toBe(false);
+  });
+});

package/src/adapters/thread/langchain/hooks.ts

@@ -4,32 +4,49 @@ type ContentBlock = MessageContent extends (infer U)[] | string ? U : never;
 
 /**
  * Creates an `onPreparedMessage` hook that appends a cache-point content
- * block to the last message in the thread.
+ * block to the last message in the thread, and strips excess cache-point
+ * blocks from earlier messages so the total never exceeds `maxBlocks`.
  *
- * Skips appending if the last message already contains a block with the
- * same `type`.
+ * Older cache-point blocks are removed first, keeping the most recent
+ * `maxBlocks - 1` positions plus the last message's block.
  */
 export function appendCachePoint(
   block: ContentBlock,
+  { maxBlocks = 4 }: { maxBlocks?: number } = {},
 ): (message: BaseMessage, index: number, messages: readonly BaseMessage[]) => BaseMessage {
   return (message, index, messages) => {
-    if (index !== messages.length - 1) {
+    const isLast = index === messages.length - 1;
+
+    if (isLast) {
+      const { content } = message;
+      if (Array.isArray(content)) {
+        if (content.some((b) => b.type === block.type)) return message;
+        message.content = [...content, block];
+      } else if (typeof content === "string") {
+        message.content = [{ type: "text", text: content }, block] satisfies MessageContent;
+      }
       return message;
     }
 
     const { content } = message;
+    if (!Array.isArray(content) || !content.some((b) => b.type === block.type)) {
+      return message;
+    }
 
-    if (Array.isArray(content)) {
-      if (content.some((b) => b.type === block.type)) {
-        return message;
+    // Count cache blocks in messages after this one (excluding the last,
+    // which always gets one) plus 1 for the last message itself.
+    let cacheBlocksAfter = 1;
+    for (let i = index + 1; i < messages.length - 1; i++) {
+      const msg = messages[i];
+      if (!msg) continue;
+      const c = msg.content;
+      if (Array.isArray(c) && c.some((b: ContentBlock) => b.type === block.type)) {
+        cacheBlocksAfter++;
       }
-      message.content = [...content, block];
-      return message;
     }
 
-    if (typeof content === "string") {
-      message.content = [{ type: "text", text: content }, block] satisfies MessageContent;
-      return message;
+    if (cacheBlocksAfter >= maxBlocks) {
+      message.content = content.filter((b) => b.type !== block.type);
     }
 
     return message;

package/src/index.ts

@@ -59,6 +59,13 @@ export type { AgentStateContext } from "./lib/activity";
 export { SandboxManager } from "./lib/sandbox/manager";
 export { NodeFsSandboxFileSystem } from "./lib/sandbox/node-fs";
 
+// Virtual filesystem (activity-side)
+export { VirtualFileSystem } from "./lib/virtual-fs/filesystem";
+export { withVirtualFs } from "./lib/virtual-fs/with-virtual-fs";
+export { createVirtualFsActivities } from "./lib/virtual-fs/manager";
+export type { FileTreeAccessor } from "./lib/virtual-fs/queries";
+export type { VirtualFsContext } from "./lib/virtual-fs/types";
+
 // Tool handlers (activity implementations)
 // Wrap sandbox handlers with withSandbox(manager, handler) at registration time
 export { bashHandler } from "./tools/bash/handler";

package/src/lib/observability/hooks.ts

@@ -0,0 +1,117 @@
+import { proxySinks } from "@temporalio/workflow";
+import type { ZeitlichObservabilitySinks } from "./sinks";
+import type {
+  SessionStartHook,
+  SessionEndHook,
+} from "../hooks/types";
+import type {
+  PostToolUseHook,
+  PostToolUseFailureHook,
+} from "../tool-router/types";
+
+export interface ObservabilityHooks {
+  onSessionStart: SessionStartHook;
+  onSessionEnd: SessionEndHook;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onPostToolUse: PostToolUseHook<any, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onPostToolUseFailure: PostToolUseFailureHook<any>;
+}
+
+/**
+ * Creates session hooks that emit agent lifecycle events to
+ * {@link ZeitlichObservabilitySinks}.
+ *
+ * The returned hooks call `proxySinks()` once and forward each event to
+ * the `zeitlichMetrics` sink. If the sink is not registered on the Worker,
+ * calls are silently dropped by the Temporal runtime.
+ *
+ * Combine with your own hooks using spread or {@link composeHooks}:
+ *
+ * ```typescript
+ * const session = await createSession({
+ *   hooks: {
+ *     ...createObservabilityHooks("myAgent"),
+ *     // additional hooks can be composed via composeHooks()
+ *   },
+ * });
+ * ```
+ *
+ * @param agentName - Agent name attached to every emitted event
+ */
+export function createObservabilityHooks(agentName: string): ObservabilityHooks {
+  const { zeitlichMetrics } = proxySinks<ZeitlichObservabilitySinks>();
+  let sessionStartMs = Date.now();
+
+  return {
+    onSessionStart: (ctx) => {
+      sessionStartMs = Date.now();
+      zeitlichMetrics.sessionStarted({
+        agentName,
+        threadId: ctx.threadId,
+        metadata: ctx.metadata,
+      });
+    },
+
+    onSessionEnd: (ctx) => {
+      zeitlichMetrics.sessionEnded({
+        agentName,
+        threadId: ctx.threadId,
+        exitReason: ctx.exitReason,
+        turns: ctx.turns,
+        usage: {},
+        durationMs: Date.now() - sessionStartMs,
+      });
+    },
+
+    onPostToolUse: (ctx) => {
+      zeitlichMetrics.toolExecuted({
+        agentName,
+        toolName: ctx.toolCall.name,
+        durationMs: ctx.durationMs,
+        success: true,
+        threadId: ctx.threadId,
+        turn: ctx.turn,
+      });
+    },
+
+    onPostToolUseFailure: (ctx) => {
+      zeitlichMetrics.toolExecuted({
+        agentName,
+        toolName: ctx.toolCall.name,
+        durationMs: 0,
+        success: false,
+        threadId: ctx.threadId,
+        turn: ctx.turn,
+      });
+      return {};
+    },
+  };
+}
+
+/**
+ * Compose multiple hook functions for the same lifecycle event into one.
+ *
+ * Each hook is called sequentially in order. Return values from
+ * `onPreToolUse` / `onPostToolUseFailure` use the **last** non-undefined
+ * result (later hooks can override earlier ones).
+ *
+ * @example
+ * ```typescript
+ * const obs = createObservabilityHooks("myAgent");
+ * const hooks = {
+ *   onSessionEnd: composeHooks(obs.onSessionEnd, myCustomEndHook),
+ * };
+ * ```
+ */
+export function composeHooks<TArgs extends unknown[], TReturn>(
+  ...fns: ((...args: TArgs) => TReturn | Promise<TReturn>)[]
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    let lastResult!: TReturn;
+    for (const fn of fns) {
+      lastResult = await fn(...args);
+    }
+    return lastResult;
+  };
+}

package/src/lib/observability/index.ts

@@ -0,0 +1,13 @@
+export {
+  createObservabilityHooks,
+  composeHooks,
+} from "./hooks";
+export type { ObservabilityHooks } from "./hooks";
+
+export type {
+  ZeitlichObservabilitySinks,
+  SessionStartedEvent,
+  SessionEndedEvent,
+  TurnCompletedEvent,
+  ToolExecutedEvent,
+} from "./sinks";

package/src/lib/observability/sinks.ts

@@ -0,0 +1,88 @@
+import type { Sinks } from "@temporalio/workflow";
+import type { TokenUsage, SessionExitReason } from "../types";
+
+// ============================================================================
+// Sink Event Types
+// ============================================================================
+
+export interface SessionStartedEvent {
+  agentName: string;
+  threadId: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface SessionEndedEvent {
+  agentName: string;
+  threadId: string;
+  exitReason: SessionExitReason;
+  turns: number;
+  usage: TokenUsage;
+  durationMs: number;
+}
+
+export interface TurnCompletedEvent {
+  agentName: string;
+  threadId: string;
+  turn: number;
+  toolCallCount: number;
+  usage?: TokenUsage;
+}
+
+export interface ToolExecutedEvent {
+  agentName: string;
+  toolName: string;
+  durationMs: number;
+  success: boolean;
+  threadId: string;
+  turn: number;
+}
+
+// ============================================================================
+// Sink Interface
+// ============================================================================
+
+/**
+ * Temporal Sinks interface for zeitlich agent observability.
+ *
+ * Sinks bridge the workflow sandbox to the Node.js environment, allowing
+ * consumers to emit metrics (Prometheus, Datadog, OpenTelemetry, etc.)
+ * from agent lifecycle events without breaking determinism.
+ *
+ * Register on the Worker via `InjectedSinks<ZeitlichObservabilitySinks>`:
+ *
+ * ```typescript
+ * import { Worker, InjectedSinks } from "@temporalio/worker";
+ * import type { ZeitlichObservabilitySinks } from "zeitlich/workflow";
+ *
+ * const sinks: InjectedSinks<ZeitlichObservabilitySinks> = {
+ *   zeitlichMetrics: {
+ *     sessionStarted: {
+ *       fn(workflowInfo, event) { counter.inc({ agent: event.agentName }); },
+ *       callDuringReplay: false,
+ *     },
+ *     sessionEnded: {
+ *       fn(workflowInfo, event) { histogram.observe(event.durationMs); },
+ *       callDuringReplay: false,
+ *     },
+ *     turnCompleted: {
+ *       fn(workflowInfo, event) { gauge.set(event.turn); },
+ *       callDuringReplay: false,
+ *     },
+ *     toolExecuted: {
+ *       fn(workflowInfo, event) { histogram.observe({ tool: event.toolName }, event.durationMs); },
+ *       callDuringReplay: false,
+ *     },
+ *   },
+ * };
+ *
+ * const worker = await Worker.create({ sinks, ... });
+ * ```
+ */
+export interface ZeitlichObservabilitySinks extends Sinks {
+  zeitlichMetrics: {
+    sessionStarted(event: SessionStartedEvent): void;
+    sessionEnded(event: SessionEndedEvent): void;
+    turnCompleted(event: TurnCompletedEvent): void;
+    toolExecuted(event: ToolExecutedEvent): void;
+  };
+}

package/src/lib/sandbox/manager.ts

@@ -80,9 +80,9 @@ export class SandboxManager<
    * manager.createActivities("CodingAgent");
    * // registers: inMemoryCodingAgentCreateSandbox, inMemoryCodingAgentDestroySandbox, …
    *
-   * const vmgr = new SandboxManager(new VirtualSandboxProvider(resolver));
-   * vmgr.createActivities("CodingAgent");
-   * // registers: virtualCodingAgentCreateSandbox, …
+   * const dmgr = new SandboxManager(new DaytonaSandboxProvider(config));
+   * dmgr.createActivities("CodingAgent");
+   * // registers: daytonaCodingAgentCreateSandbox, …
    * ```
    */
   createActivities<S extends string>(

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -42,6 +42,7 @@ vi.mock("@temporalio/workflow", () => {
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
     ApplicationFailure: MockApplicationFailure,
+    log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
   };
 });
 

package/src/lib/session/session.integration.test.ts

@@ -46,6 +46,7 @@ vi.mock("@temporalio/workflow", () => {
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
     ApplicationFailure: MockApplicationFailure,
+    log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
   };
 });