zeitlich 0.2.28 → 0.2.29

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

@@ -0,0 +1,48 @@
+import type {
+  FileEntryMetadata,
+  FileResolver,
+  PrefixedVirtualFsOps,
+  VirtualFsOps,
+} from "./types";
+
+/**
+ * Creates prefixed Temporal activity functions for a {@link FileResolver}.
+ *
+ * Pair with {@link proxyVirtualFsOps} on the workflow side using the same
+ * scope string.
+ *
+ * @param resolver - Consumer-provided bridge to DB / S3 / CRUD layer
+ * @param scope    - Workflow name used to namespace the activities
+ *
+ * @example
+ * ```typescript
+ * import { createVirtualFsActivities } from 'zeitlich';
+ *
+ * const activities = {
+ *   ...createVirtualFsActivities(resolver, "CodingAgent"),
+ * };
+ * // registers: codingAgentResolveFileTree
+ * ```
+ */
+export function createVirtualFsActivities<
+  S extends string,
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+>(
+  resolver: FileResolver<TCtx, TMeta>,
+  scope: S,
+): PrefixedVirtualFsOps<S, TCtx, TMeta> {
+  const ops: VirtualFsOps<TCtx, TMeta> = {
+    resolveFileTree: async (ctx: TCtx) => {
+      const fileTree = await resolver.resolveEntries(ctx);
+      return { fileTree };
+    },
+  };
+
+  const prefix = scope;
+  const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+
+  return Object.fromEntries(
+    Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v]),
+  ) as PrefixedVirtualFsOps<S, TCtx, TMeta>;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Workflow-safe proxy for virtual filesystem operations.
+ *
+ * Import this from `zeitlich/workflow` in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyVirtualFsOps } from 'zeitlich/workflow';
+ *
+ * const virtualFsOps = proxyVirtualFsOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { VirtualFsOps } from "./types";
+
+export function proxyVirtualFsOps<TCtx = unknown>(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0],
+): VirtualFsOps<TCtx> {
+  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",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "2s",
+        maximumInterval: "30s",
+        backoffCoefficient: 2,
+      },
+    },
+  );
+
+  const prefix = resolvedScope;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    resolveFileTree: acts[p("resolveFileTree")],
+  } as VirtualFsOps<TCtx>;
+}

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

@@ -1,6 +1,5 @@
-import type { Sandbox, SandboxCreateOptions } from "../../../lib/sandbox/types";
-import type { RouterContext } from "../../../lib/tool-router/types";
-import type { VirtualSandboxFileSystem } from "./filesystem";
+import type { RouterContext } from "../tool-router/types";
+import type { VirtualFileSystem } from "./filesystem";
 
 // ============================================================================
 // File Entry
@@ -15,7 +14,7 @@ export type FileEntryMetadata = Record<
 /** JSON-serializable metadata for a single file in the virtual tree. */
 export interface FileEntry<TMeta = FileEntryMetadata> {
   id: string;
-  /** Virtual path inside the sandbox, e.g. "/src/index.ts" */
+  /** Virtual path, e.g. "/src/index.ts" */
   path: string;
   size: number;
   /** ISO-8601 date string (JSON-safe) */
@@ -73,63 +72,74 @@ export interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
 }
 
 // ============================================================================
-// Create Options
+// VirtualFsOps — workflow-side activity interface
 // ============================================================================
 
 /**
- * Options for {@link VirtualSandboxProvider.create}.
- * Extends base options with resolver context.
+ * Workflow-side operations for the virtual filesystem.
+ *
+ * Unlike {@link SandboxOps}, this only exposes what is actually needed:
+ * resolving the initial file tree from the consumer's data layer.
  */
-export interface VirtualSandboxCreateOptions<
-  TCtx,
-> extends SandboxCreateOptions {
-  resolverContext: TCtx;
-  /** Base path for resolving relative filesystem paths (default "/"). */
-  workspaceBase?: string;
+export interface VirtualFsOps<
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+> {
+  resolveFileTree(
+    ctx: TCtx,
+  ): Promise<{
+    fileTree: FileEntry<TMeta>[];
+    stateUpdate?: Record<string, unknown>;
+  }>;
 }
 
+/**
+ * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type Ops = PrefixedVirtualFsOps<"codingAgent">;
+ * // → { codingAgentResolveFileTree: ... }
+ * ```
+ */
+export type PrefixedVirtualFsOps<
+  TPrefix extends string,
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+> = {
+  [K in keyof VirtualFsOps<TCtx, TMeta> as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+};
+
 // ============================================================================
 // Workflow State Shape
 // ============================================================================
 
 /**
- * The portion of workflow `AgentState` that the virtual sandbox reads via
+ * The portion of workflow `AgentState` that the virtual filesystem reads via
  * {@link queryParentWorkflowState}. Populated automatically by the session
- * from the provider's `stateUpdate` after `createSandbox`.
+ * when `virtualFs` config is provided.
  */
-export interface VirtualSandboxState<
+export interface VirtualFsState<
   TCtx = unknown,
   TMeta = FileEntryMetadata,
 > {
-  sandboxId: string;
   fileTree: FileEntry<TMeta>[];
   resolverContext: TCtx;
   workspaceBase?: string;
 }
 
-// ============================================================================
-// VirtualSandbox instance type
-// ============================================================================
-
-/**
- * A {@link Sandbox} whose filesystem is backed by a {@link VirtualSandboxFileSystem}.
- */
-export type VirtualSandbox<
-  TCtx = unknown,
-  TMeta = FileEntryMetadata,
-> = Sandbox & { fs: VirtualSandboxFileSystem<TCtx, TMeta> };
-
 // ============================================================================
 // Handler Context
 // ============================================================================
 
 /**
- * Extended router context injected by {@link withVirtualSandbox}.
- * Guarantees a live (ephemeral) sandbox built from the workflow file tree.
+ * Extended router context injected by {@link withVirtualFs}.
+ * Guarantees a live (ephemeral) virtual filesystem built from the workflow
+ * file tree.
  */
-export interface VirtualSandboxContext<
+export interface VirtualFsContext<
   TCtx = unknown,
   TMeta = FileEntryMetadata,
 > extends RouterContext {
-  sandbox: VirtualSandbox<TCtx, TMeta>;
+  virtualFs: VirtualFileSystem<TCtx, TMeta>;
 }

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`, `resolverContext`, 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, resolverContext, 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,
+      resolverContext,
+      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/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",