zeitlich 0.2.28 → 0.2.30

package/src/{adapters/sandbox/virtual/virtual-sandbox.test.ts → lib/virtual-fs/virtual-fs.test.ts}

@@ -1,10 +1,9 @@
 import { describe, expect, it, beforeEach } from "vitest";
 import type { FileEntry, FileResolver } from "./types";
-import { VirtualSandboxFileSystem } from "./filesystem";
-import { createVirtualSandbox } from "./index";
+import { VirtualFileSystem } from "./filesystem";
 import { applyVirtualTreeMutations } from "./mutations";
-import { VirtualSandboxProvider } from "./provider";
-import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import { createVirtualFsActivities } from "./manager";
+import { SandboxNotSupportedError } from "../sandbox/types";
 
 // ============================================================================
 // Mock resolver
@@ -112,15 +111,15 @@ const sampleTree: FileEntry[] = [
 const ctx: TestCtx = { projectId: "proj-42" };
 
 // ============================================================================
-// VirtualSandboxFileSystem
+// VirtualFileSystem
 // ============================================================================
 
-describe("VirtualSandboxFileSystem", () => {
-  let fs: VirtualSandboxFileSystem<TestCtx>;
+describe("VirtualFileSystem", () => {
+  let fs: VirtualFileSystem<TestCtx>;
 
   beforeEach(() => {
     const { resolver } = createMockResolver();
-    fs = new VirtualSandboxFileSystem(sampleTree, resolver, ctx);
+    fs = new VirtualFileSystem(sampleTree, resolver, ctx);
   });
 
   // --- exists / stat ---
@@ -327,132 +326,18 @@ describe("VirtualSandboxFileSystem", () => {
 });
 
 // ============================================================================
-// createVirtualSandbox
+// createVirtualFsActivities
 // ============================================================================
 
-describe("createVirtualSandbox", () => {
-  it("creates a sandbox with correct capabilities", () => {
+describe("createVirtualFsActivities", () => {
+  it("creates prefixed activity with resolveFileTree", async () => {
     const { resolver } = createMockResolver();
-    const sandbox = createVirtualSandbox("test-id", sampleTree, resolver, ctx);
-    expect(sandbox.capabilities.filesystem).toBe(true);
-    expect(sandbox.capabilities.execution).toBe(false);
-    expect(sandbox.capabilities.persistence).toBe(true);
-  });
-
-  it("exec throws SandboxNotSupportedError", async () => {
-    const { resolver } = createMockResolver();
-    const sandbox = createVirtualSandbox("test-id", sampleTree, resolver, ctx);
-    await expect(sandbox.exec("ls")).rejects.toThrow(SandboxNotSupportedError);
-  });
-
-  it("fs operations work through the sandbox", async () => {
-    const { resolver } = createMockResolver();
-    const sandbox = createVirtualSandbox("test-id", sampleTree, resolver, ctx);
-    const content = await sandbox.fs.readFile("/README.md");
-    expect(content).toBe("# README\nThis is a readme.");
-  });
-
-  it("getMutations is accessible", async () => {
-    const { resolver } = createMockResolver();
-    const sandbox = createVirtualSandbox("test-id", sampleTree, resolver, ctx);
-    await sandbox.fs.writeFile("/new.txt", "hi");
-    expect(sandbox.fs.getMutations()).toHaveLength(1);
-  });
-});
-
-// ============================================================================
-// VirtualSandboxProvider
-// ============================================================================
-
-describe("VirtualSandboxProvider", () => {
-  it("create resolves entries and returns sandbox + stateUpdate", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    const { sandbox, stateUpdate } = await provider.create({
-      resolverContext: ctx,
-    });
-    expect(sandbox.capabilities.filesystem).toBe(true);
-    expect(sandbox.capabilities.execution).toBe(false);
-    const content = await sandbox.fs.readFile("/resolved/file-1.txt");
-    expect(content).toBe('console.log("hello");');
-
-    expect(stateUpdate).toBeDefined();
-    expect(stateUpdate?.resolverContext).toEqual(ctx);
-    expect(Array.isArray(stateUpdate?.fileTree)).toBe(true);
-    expect((stateUpdate?.fileTree as FileEntry[]).length).toBe(3);
-  });
-
-  it("create uses provided id as sandbox id", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    const { sandbox, stateUpdate } = await provider.create({
-      id: "my-sandbox",
-      resolverContext: ctx,
-    });
-    expect(sandbox.id).toBe("my-sandbox");
-    expect(stateUpdate?.sandboxId).toBe("my-sandbox");
-  });
-
-  it("get throws (state lives in workflow)", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    await expect(provider.get()).rejects.toThrow("Sandbox does not support");
-  });
-
-  it("snapshot throws (state lives in workflow)", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    await expect(provider.snapshot()).rejects.toThrow(
-      "Sandbox does not support",
-    );
-  });
-
-  it("restore throws (state lives in workflow)", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    await expect(provider.restore()).rejects.toThrow(
-      "Sandbox does not support",
-    );
-  });
-
-  it("destroy is a no-op", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    await expect(provider.destroy()).resolves.not.toThrow();
-  });
-
-  it("create throws without required options", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    await expect(provider.create()).rejects.toThrow(
-      "requires resolverContext",
-    );
-  });
-
-  it("create seeds initialFiles via writeFile into sandbox and fileTree", async () => {
-    const { resolver } = createMockResolver();
-    const provider = new VirtualSandboxProvider(resolver);
-    const { sandbox, stateUpdate } = await provider.create({
-      resolverContext: ctx,
-      initialFiles: {
-        "/skills/my-skill/SKILL.md": "---\nname: my-skill\n---\nDo things.",
-        "/skills/my-skill/references/guide.md": "# Guide\nStep 1...",
-      },
-    });
-
-    expect(await sandbox.fs.readFile("/skills/my-skill/SKILL.md")).toBe(
-      "---\nname: my-skill\n---\nDo things.",
-    );
-    expect(await sandbox.fs.readFile("/skills/my-skill/references/guide.md")).toBe(
-      "# Guide\nStep 1...",
-    );
-    expect(await sandbox.fs.exists("/skills/my-skill")).toBe(true);
-    expect(await sandbox.fs.exists("/skills/my-skill/references")).toBe(true);
+    const activities = createVirtualFsActivities(resolver, "codingAgent");
 
-    const tree = stateUpdate?.fileTree as FileEntry[];
-    expect(tree.find((e) => e.path === "/skills/my-skill/SKILL.md")).toBeDefined();
-    expect(tree.find((e) => e.path === "/skills/my-skill/references/guide.md")).toBeDefined();
-    expect(stateUpdate).not.toHaveProperty("localFiles");
+    expect(activities).toHaveProperty("codingAgentResolveFileTree");
+    const result = await activities.codingAgentResolveFileTree(ctx);
+    expect(result.fileTree).toHaveLength(3);
+    expect(result.fileTree[0]?.path).toMatch(/^\/resolved\//);
   });
 });
 

package/src/lib/virtual-fs/with-virtual-fs.ts

@@ -0,0 +1,94 @@
+import type { WorkflowClient } from "@temporalio/client";
+import { queryParentWorkflowState } from "../activity";
+import type { JsonValue } from "../state/types";
+import type { ActivityToolHandler, RouterContext } from "../tool-router/types";
+import type {
+  FileEntryMetadata,
+  FileResolver,
+  TreeMutation,
+  VirtualFsContext,
+  VirtualFsState,
+} from "./types";
+import { VirtualFileSystem } from "./filesystem";
+
+/**
+ * Wraps a tool handler that needs a virtual filesystem, automatically querying
+ * the parent workflow for the current file tree and resolver context.
+ *
+ * On each invocation the wrapper:
+ * 1. Queries the workflow's `AgentState` for `fileTree`, `ctx`, and `workspaceBase`
+ * 2. Creates an ephemeral {@link VirtualFileSystem} from tree + resolver
+ * 3. Runs the inner handler
+ * 4. Returns the handler's result together with any {@link TreeMutation}s
+ *
+ * The consumer applies mutations back to workflow state via a post-tool hook.
+ *
+ * @param client   - Temporal `WorkflowClient` for querying the parent workflow
+ * @param resolver - {@link FileResolver} bridging to the consumer's data layer
+ * @param handler  - Inner handler expecting a {@link VirtualFsContext}
+ *
+ * @example
+ * ```typescript
+ * import { withVirtualFs, type VirtualFsContext } from 'zeitlich';
+ *
+ * const readHandler: ActivityToolHandler<FileReadArgs, ReadResult, VirtualFsContext> =
+ *   async (args, { virtualFs }) => {
+ *     const content = await virtualFs.readFile(args.path);
+ *     return { toolResponse: content, data: { path: args.path, content } };
+ *   };
+ *
+ * // At activity registration:
+ * const handler = withVirtualFs(client, resolver, readHandler);
+ * ```
+ */
+export function withVirtualFs<
+  TArgs,
+  TResult,
+  TCtx,
+  TMeta = FileEntryMetadata,
+  TToolResponse = JsonValue,
+>(
+  client: WorkflowClient,
+  resolver: FileResolver<TCtx, TMeta>,
+  handler: ActivityToolHandler<
+    TArgs,
+    TResult,
+    VirtualFsContext<TCtx, TMeta>,
+    TToolResponse
+  >
+): ActivityToolHandler<
+  TArgs,
+  (TResult & { treeMutations: TreeMutation<TMeta>[] }) | null,
+  RouterContext,
+  TToolResponse | string
+> {
+  return async (args, context) => {
+    const state =
+      await queryParentWorkflowState<VirtualFsState<TCtx, TMeta>>(client);
+
+    const { fileTree, ctx, workspaceBase } = state;
+    if (!fileTree) {
+      return {
+        toolResponse: `Error: No fileTree in agent state. The ${context.toolName} tool requires a virtual filesystem.`,
+        data: null,
+      };
+    }
+
+    const virtualFs = new VirtualFileSystem(
+      fileTree,
+      resolver,
+      ctx,
+      workspaceBase ?? "/"
+    );
+    const response = await handler(args, { ...context, virtualFs });
+    const mutations = virtualFs.getMutations();
+
+    return {
+      toolResponse: response.toolResponse,
+      data: {
+        ...(response.data ?? {}),
+        treeMutations: mutations,
+      } as TResult & { treeMutations: TreeMutation<TMeta>[] },
+    };
+  };
+}

package/src/tools/bash/bash.test.ts

@@ -21,7 +21,8 @@ describe("bash handler with sandbox", () => {
     const result = await manager.create({
       initialFiles: { "/home/user/hello.txt": "world" },
     });
-    sandboxId = result.sandboxId;
+    expect(result).not.toBeNull();
+    sandboxId = (result as NonNullable<typeof result>).sandboxId;
     handler = withSandbox(manager, bashHandler);
   });
 

package/src/workflow.ts

@@ -9,7 +9,7 @@
  * // In your workflow file
  * import { createSession, defineWorkflow, defineTool, bashTool } from 'zeitlich/workflow';
  * import { proxyLangChainThreadOps } from 'zeitlich/adapters/thread/langchain/workflow';
- * import { proxyVirtualSandboxOps } from 'zeitlich/adapters/sandbox/virtual/workflow';
+ * import { proxyVirtualFsOps } from 'zeitlich/workflow';
  * ```
  */
 
@@ -93,6 +93,20 @@ export type {
   PostHumanMessageAppendHookContext,
 } from "./lib/hooks";
 
+// Observability
+export {
+  createObservabilityHooks,
+  composeHooks,
+} from "./lib/observability";
+export type {
+  ObservabilityHooks,
+  ZeitlichObservabilitySinks,
+  SessionStartedEvent,
+  SessionEndedEvent,
+  TurnCompletedEvent,
+  ToolExecutedEvent,
+} from "./lib/observability";
+
 // Core types
 export type {
   TokenUsage,
@@ -152,24 +166,27 @@ export {
   SandboxNotSupportedError,
 } from "./lib/sandbox/types";
 
-// Virtual sandbox (workflow-safe — imported from leaf modules to avoid
-// pulling activity-side code like VirtualSandboxFileSystem / Provider).
-export { applyVirtualTreeMutations } from "./adapters/sandbox/virtual/mutations";
-export { formatVirtualFileTree } from "./adapters/sandbox/virtual/tree";
+// Virtual filesystem (workflow-safe — imported from leaf modules to avoid
+// pulling activity-side code like VirtualFileSystem).
+export { applyVirtualTreeMutations } from "./lib/virtual-fs/mutations";
+export { formatVirtualFileTree } from "./lib/virtual-fs/tree";
 export {
   hasFileWithMimeType,
   filesWithMimeType,
   hasDirectory,
-} from "./adapters/sandbox/virtual/queries";
+} from "./lib/virtual-fs/queries";
+export { proxyVirtualFsOps } from "./lib/virtual-fs/proxy";
 
 export type {
   FileEntry,
   FileEntryMetadata,
   FileResolver,
   VirtualFileTree,
-  VirtualSandboxState,
+  VirtualFsOps,
+  PrefixedVirtualFsOps,
+  VirtualFsState,
   TreeMutation,
-} from "./adapters/sandbox/virtual/types";
+} from "./lib/virtual-fs/types";
 
 // Subagent support
 export type { SubagentArgs } from "./lib/subagent";

package/tsup.config.ts

@@ -18,8 +18,6 @@ export default defineConfig({
     "adapters/sandbox/inmemory/workflow": "src/adapters/sandbox/inmemory/proxy.ts",
     "adapters/sandbox/daytona/index": "src/adapters/sandbox/daytona/index.ts",
     "adapters/sandbox/daytona/workflow": "src/adapters/sandbox/daytona/proxy.ts",
-    "adapters/sandbox/virtual/index": "src/adapters/sandbox/virtual/index.ts",
-    "adapters/sandbox/virtual/workflow": "src/adapters/sandbox/virtual/proxy.ts",
     "adapters/sandbox/e2b/index": "src/adapters/sandbox/e2b/index.ts",
     "adapters/sandbox/e2b/workflow": "src/adapters/sandbox/e2b/proxy.ts",
     "adapters/sandbox/bedrock/index": "src/adapters/sandbox/bedrock/index.ts",