zeitlich 0.2.28 → 0.2.30

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineSignal, uuid4, setHandler, defineUpdate, ApplicationFailure, condition, defineQuery, workflowInfo, getExternalWorkflowHandle, log, startChild } from '@temporalio/workflow';
+import { defineSignal, uuid4, setHandler, defineUpdate, ApplicationFailure, log, condition, defineQuery, proxySinks, workflowInfo, proxyActivities, getExternalWorkflowHandle, startChild } from '@temporalio/workflow';
 import z14, { z } from 'zod';
 import { randomUUID, randomFillSync } from 'crypto';
 import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
@@ -129,6 +129,11 @@ function createToolRouter(options) {
       return null;
     }
     const effectiveArgs = preResult.args;
+    log.debug("tool call dispatched", {
+      toolName: toolCall.name,
+      toolCallId: toolCall.id,
+      turn
+    });
     let result;
     let content;
     let resultAppended = false;
@@ -155,6 +160,13 @@ function createToolRouter(options) {
         content = JSON.stringify(result, null, 2);
       }
     } catch (error) {
+      log.warn("tool call failed", {
+        toolName: toolCall.name,
+        toolCallId: toolCall.id,
+        turn,
+        durationMs: Date.now() - startTime,
+        error: error instanceof Error ? error.message : String(error)
+      });
       const recovery = await runFailureHooks(
         toolCall,
         tool,
@@ -180,19 +192,26 @@ function createToolRouter(options) {
         [uuid4(), config]
       );
     }
+    const durationMs = Date.now() - startTime;
     const toolResult = {
       toolCallId: toolCall.id,
       name: toolCall.name,
       data: result,
       ...metadata && { metadata }
     };
+    log.debug("tool call completed", {
+      toolName: toolCall.name,
+      toolCallId: toolCall.id,
+      turn,
+      durationMs
+    });
     await runPostHooks(
       toolCall,
       tool,
       toolResult,
       effectiveArgs,
       turn,
-      Date.now() - startTime
+      durationMs
     );
     return toolResult;
   }
@@ -380,7 +399,7 @@ function resolveSandboxConfig(config) {
   if (config === "own") return { source: "own" };
   return { source: "own", shutdown: config.shutdown };
 }
-function createSubagentHandler(subagents, options) {
+function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflowInfo();
   const childResults = /* @__PURE__ */ new Map();
   const pendingDestroys = /* @__PURE__ */ new Map();
@@ -408,15 +427,16 @@ function createSubagentHandler(subagents, options) {
     const continuationThreadId = args.threadId && allowsContinuation ? args.threadId : void 0;
     let thread;
     if (continuationThreadId) {
-      thread = { mode: threadMode, threadId: continuationThreadId };
+      thread = {
+        mode: threadMode,
+        threadId: continuationThreadId
+      };
     }
     let sandbox;
     if (sandboxCfg.source === "inherit" && parentSandboxId) {
-      const stateUpdate = options?.getSandboxStateForInheritance?.();
       sandbox = {
         mode: "inherit",
-        sandboxId: parentSandboxId,
-        ...stateUpdate && { stateUpdate }
+        sandboxId: parentSandboxId
       };
     } else if (sandboxCfg.source === "own") {
       const prevSbId = continuationThreadId ? threadSandboxes.get(continuationThreadId) : void 0;
@@ -435,6 +455,12 @@ function createSubagentHandler(subagents, options) {
       args: resolvedContext === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, resolvedContext],
       taskQueue: config.taskQueue ?? parentTaskQueue
     };
+    log.info("subagent spawned", {
+      subagent: config.agentName,
+      childWorkflowId,
+      threadMode,
+      sandboxSource: sandboxCfg.source
+    });
     const childHandle = await startChild(config.workflow, childOpts);
     const effectiveShutdown = sandboxCfg.shutdown ?? "destroy";
     const shouldDeferDestroy = effectiveShutdown === "pause-until-parent-close" && (sandboxCfg.source === "own" || allowsContinuation && sandboxCfg.source !== "inherit");
@@ -451,11 +477,20 @@ function createSubagentHandler(subagents, options) {
     const childResult = childResults.get(childWorkflowId);
     childResults.delete(childWorkflowId);
     if (!childResult) {
+      log.warn("subagent returned no result", {
+        subagent: config.agentName,
+        childWorkflowId
+      });
       return {
         toolResponse: "Subagent workflow did not signal a result",
         data: null
       };
     }
+    log.info("subagent completed", {
+      subagent: config.agentName,
+      childWorkflowId,
+      ...childResult.usage && { usage: childResult.usage }
+    });
     const {
       toolResponse,
       data,
@@ -521,7 +556,7 @@ function createSubagentHandler(subagents, options) {
 }
 
 // src/lib/subagent/register.ts
-function buildSubagentRegistration(subagents, options) {
+function buildSubagentRegistration(subagents) {
   if (subagents.length === 0) return null;
   const getEnabled = () => subagents.filter(
     (s) => typeof s.enabled === "function" ? s.enabled() : s.enabled ?? true
@@ -531,9 +566,7 @@ function buildSubagentRegistration(subagents, options) {
     if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
   }
   const resolveSubagentName = (args) => args.subagent;
-  const { handler, destroySubagentSandboxes } = createSubagentHandler(subagents, {
-    getSandboxStateForInheritance: options?.getSandboxStateForInheritance
-  });
+  const { handler, destroySubagentSandboxes } = createSubagentHandler(subagents);
   const registration = {
     name: SUBAGENT_TOOL_NAME,
     enabled: () => getEnabled().length > 0,
@@ -672,7 +705,9 @@ async function createSession({
   sandboxOps,
   thread: threadInit,
   sandbox: sandboxInit,
-  sandboxShutdown = "destroy"
+  sandboxShutdown = "destroy",
+  virtualFs: virtualFsConfig,
+  virtualFsOps
 }) {
   const threadMode = threadInit?.mode ?? "new";
   let threadId;
@@ -698,11 +733,8 @@ async function createSession({
   } = threadOps;
   const plugins = [];
   let destroySubagentSandboxes;
-  let sandboxStateGetter;
   if (subagents) {
-    const result = buildSubagentRegistration(subagents, {
-      getSandboxStateForInheritance: () => sandboxStateGetter?.()
-    });
+    const result = buildSubagentRegistration(subagents);
     if (result) {
       plugins.push(result.registration);
       destroySubagentSandboxes = result.destroySubagentSandboxes;
@@ -758,23 +790,9 @@ async function createSession({
       const sandboxMode = sandboxInit?.mode;
       let sandboxId;
       let sandboxOwned = false;
-      sandboxStateGetter = () => {
-        const fileTree = stateManager.get("fileTree");
-        const resolverContext = stateManager.get("resolverContext");
-        const workspaceBase = stateManager.get("workspaceBase");
-        if (!fileTree && !resolverContext && !workspaceBase) return void 0;
-        return {
-          ...fileTree !== void 0 && { fileTree },
-          ...resolverContext !== void 0 && { resolverContext },
-          ...workspaceBase !== void 0 && { workspaceBase }
-        };
-      };
       if (sandboxMode === "inherit") {
         const inheritInit = sandboxInit;
         sandboxId = inheritInit.sandboxId;
-        if (inheritInit.stateUpdate) {
-          stateManager.mergeUpdate(inheritInit.stateUpdate);
-        }
         if (!sandboxOps) {
           throw ApplicationFailure.create({
             message: "sandboxId provided but no sandboxOps \u2014 cannot manage sandbox lifecycle",
@@ -803,14 +821,25 @@ async function createSession({
         sandboxOwned = true;
       } else if (sandboxOps) {
         const skillFiles = skills ? collectSkillFiles(skills) : void 0;
-        const result = await sandboxOps.createSandbox(
-          skillFiles ? { initialFiles: skillFiles } : void 0
-        );
-        sandboxId = result.sandboxId;
-        sandboxOwned = true;
-        if (result.stateUpdate) {
-          stateManager.mergeUpdate(result.stateUpdate);
+        const ctx = sandboxInit?.ctx;
+        const createOptions = skillFiles ? { initialFiles: skillFiles } : void 0;
+        const result = await sandboxOps.createSandbox(createOptions, ctx);
+        if (result) {
+          sandboxId = result.sandboxId;
+          sandboxOwned = true;
+        }
+      }
+      if (virtualFsConfig) {
+        if (!virtualFsOps) {
+          throw ApplicationFailure.create({
+            message: "No virtualFsOps provided \u2014 cannot resolve file tree",
+            nonRetryable: true
+          });
         }
+        const result = await virtualFsOps.resolveFileTree(virtualFsConfig.ctx);
+        stateManager.mergeUpdate({
+          fileTree: result.fileTree
+        });
       }
       if (hooks.onSessionStart) {
         await hooks.onSessionStart({
@@ -819,6 +848,14 @@ async function createSession({
           metadata
         });
       }
+      log.info("session started", {
+        agentName,
+        threadId,
+        threadMode,
+        maxTurns,
+        ...sandboxId && { sandboxId }
+      });
+      const sessionStartMs = Date.now();
       const systemPrompt = stateManager.getSystemPrompt();
       if (threadMode === "fork" && sourceThreadId) {
         await forkThread(sourceThreadId, threadId, threadKey);
@@ -835,12 +872,18 @@ async function createSession({
           await initializeThread(threadId, threadKey);
         }
       }
-      await appendHumanMessage(threadId, uuid4(), await buildContextMessage(), threadKey);
+      await appendHumanMessage(
+        threadId,
+        uuid4(),
+        await buildContextMessage(),
+        threadKey
+      );
       let exitReason = "completed";
       try {
         while (stateManager.isRunning() && !stateManager.isTerminal() && stateManager.getTurns() < maxTurns) {
           stateManager.incrementTurns();
           const currentTurn = stateManager.getTurns();
+          log.debug("turn started", { agentName, threadId, turn: currentTurn });
           stateManager.setTools(toolRouter.getToolDefinitions());
           const { message, rawToolCalls, usage } = await runAgent({
             threadId,
@@ -851,9 +894,24 @@ async function createSession({
           if (usage) {
             stateManager.updateUsage(usage);
           }
+          log.debug("model response received", {
+            agentName,
+            threadId,
+            turn: currentTurn,
+            toolCallCount: rawToolCalls.length,
+            ...usage && { usage }
+          });
           if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
             stateManager.complete();
             exitReason = "completed";
+            log.info("session ended", {
+              agentName,
+              threadId,
+              exitReason,
+              turns: currentTurn,
+              durationMs: Date.now() - sessionStartMs,
+              usage: stateManager.getTotalUsage()
+            });
             return {
               threadId,
               finalMessage: message,
@@ -905,9 +963,21 @@ async function createSession({
         }
         if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
           exitReason = "max_turns";
+          log.warn("session hit max turns", {
+            agentName,
+            threadId,
+            maxTurns
+          });
         }
       } catch (error) {
         exitReason = "failed";
+        log.error("session failed", {
+          agentName,
+          threadId,
+          turns: stateManager.getTurns(),
+          durationMs: Date.now() - sessionStartMs,
+          error: error instanceof Error ? error.message : String(error)
+        });
         throw ApplicationFailure.fromError(error);
       } finally {
         await callSessionEnd(exitReason, stateManager.getTurns());
@@ -926,6 +996,14 @@ async function createSession({
           await destroySubagentSandboxes();
         }
       }
+      log.info("session ended", {
+        agentName,
+        threadId,
+        exitReason,
+        turns: stateManager.getTurns(),
+        durationMs: Date.now() - sessionStartMs,
+        usage: stateManager.getTotalUsage()
+      });
       return {
         threadId,
         finalMessage: null,
@@ -1263,6 +1341,60 @@ function defineSubagentWorkflow(config, fn) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   });
 }
+function createObservabilityHooks(agentName) {
+  const { zeitlichMetrics } = proxySinks();
+  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 {};
+    }
+  };
+}
+function composeHooks(...fns) {
+  return async (...args) => {
+    let lastResult;
+    for (const fn of fns) {
+      lastResult = await fn(...args);
+    }
+    return lastResult;
+  };
+}
 var SandboxNotSupportedError = class extends ApplicationFailure$1 {
   constructor(operation) {
     super(
@@ -1278,7 +1410,7 @@ var SandboxNotFoundError = class extends ApplicationFailure$1 {
   }
 };
 
-// src/adapters/sandbox/virtual/mutations.ts
+// src/lib/virtual-fs/mutations.ts
 function applyVirtualTreeMutations(stateManager, mutations) {
   let tree = [...stateManager.get("fileTree")];
   for (const m of mutations) {
@@ -1300,7 +1432,7 @@ function applyVirtualTreeMutations(stateManager, mutations) {
   return tree;
 }
 
-// src/adapters/sandbox/virtual/tree.ts
+// src/lib/virtual-fs/tree.ts
 var buildTree = (entries) => {
   const root = { name: "/", children: /* @__PURE__ */ new Map(), isFile: false };
   for (const entry of entries) {
@@ -1348,7 +1480,7 @@ function formatVirtualFileTree(entries, opts = {}) {
   return "/" + printNode(root, "", sort);
 }
 
-// src/adapters/sandbox/virtual/queries.ts
+// src/lib/virtual-fs/queries.ts
 function hasFileWithMimeType(stateManager, pattern) {
   const tree = stateManager.get("fileTree");
   const matchers = (Array.isArray(pattern) ? pattern : [pattern]).map(buildMatcher);
@@ -1389,6 +1521,25 @@ function buildGlobMatcher(pattern) {
   );
   return (v) => re.test(v);
 }
+function proxyVirtualFsOps(scope, options) {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+  const acts = proxyActivities(
+    options ?? {
+      startToCloseTimeout: "30s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "2s",
+        maximumInterval: "30s",
+        backoffCoefficient: 2
+      }
+    }
+  );
+  const prefix = resolvedScope;
+  const p = (key) => `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+  return {
+    resolveFileTree: acts[p("resolveFileTree")]
+  };
+}
 
 // src/lib/skills/parse.ts
 function parseSkillFile(raw) {
@@ -2023,12 +2174,41 @@ function withParentWorkflowState(client, handler) {
 
 // src/lib/sandbox/manager.ts
 var SandboxManager = class {
-  constructor(provider) {
+  constructor(provider, options) {
     this.provider = provider;
-  }
-  async create(options) {
-    const { sandbox, stateUpdate } = await this.provider.create(options);
-    return { sandboxId: sandbox.id, ...stateUpdate && { stateUpdate } };
+    this.hooks = options?.hooks ?? {};
+  }
+  hooks;
+  async create(options, ctx) {
+    let providerOptions = options;
+    if (this.hooks.onPreCreate) {
+      const hookResult = await this.hooks.onPreCreate(
+        options ?? {},
+        ctx ?? {}
+      );
+      if (hookResult?.skip) return null;
+      if (hookResult?.modifiedOptions) {
+        const orig = options ?? {};
+        const mod = hookResult.modifiedOptions;
+        providerOptions = {
+          ...mod,
+          ...orig,
+          initialFiles: {
+            ...mod.initialFiles,
+            ...orig.initialFiles
+          },
+          env: {
+            ...mod.env,
+            ...orig.env
+          }
+        };
+      }
+    }
+    const { sandbox } = await this.provider.create(providerOptions);
+    if (this.hooks.onPostCreate) {
+      await this.hooks.onPostCreate(sandbox.id);
+    }
+    return { sandboxId: sandbox.id };
   }
   async getSandbox(id) {
     return this.provider.get(id);
@@ -2065,16 +2245,16 @@ var SandboxManager = class {
    * 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(scope) {
     const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
     const ops = {
-      createSandbox: async (options) => {
-        return this.create(options);
+      createSandbox: async (options, ctx) => {
+        return this.create(options, ctx);
       },
       destroySandbox: async (sandboxId) => {
         await this.destroy(sandboxId);
@@ -2164,6 +2344,328 @@ var NodeFsSandboxFileSystem = class {
     return posix.resolve(base, path);
   }
 };
+function normalisePath(p, workspaceBase = "/") {
+  return posix.resolve(workspaceBase, p);
+}
+function parentDir(p) {
+  const idx = p.lastIndexOf("/");
+  return idx <= 0 ? "/" : p.slice(0, idx);
+}
+function inferDirectories(entries, workspaceBase) {
+  const dirs = /* @__PURE__ */ new Set();
+  dirs.add("/");
+  for (const entry of entries) {
+    let dir = parentDir(normalisePath(entry.path, workspaceBase));
+    while (dir !== "/" && !dirs.has(dir)) {
+      dirs.add(dir);
+      dir = parentDir(dir);
+    }
+    dirs.add("/");
+  }
+  return dirs;
+}
+var VirtualFileSystem = class {
+  constructor(tree, resolver, ctx, workspaceBase = "/") {
+    this.resolver = resolver;
+    this.ctx = ctx;
+    this.workspaceBase = normalisePath(workspaceBase);
+    this.entries = new Map(
+      tree.map((e) => [normalisePath(e.path, this.workspaceBase), e])
+    );
+    this.directories = inferDirectories(tree, this.workspaceBase);
+  }
+  workspaceBase;
+  entries;
+  directories;
+  mutations = [];
+  /** Return all mutations accumulated during this invocation. */
+  getMutations() {
+    return this.mutations;
+  }
+  /** Look up a file entry by virtual path. */
+  getEntry(path) {
+    return this.entries.get(normalisePath(path, this.workspaceBase));
+  }
+  // --------------------------------------------------------------------------
+  // Read operations — delegate to resolver lazily
+  // --------------------------------------------------------------------------
+  async readFile(path) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFile(entry.id, this.ctx, entry.metadata);
+  }
+  async readFileBuffer(path) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFileBuffer(entry.id, this.ctx, entry.metadata);
+  }
+  // --------------------------------------------------------------------------
+  // Metadata operations — pure, resolved from the tree
+  // --------------------------------------------------------------------------
+  async exists(path) {
+    const norm = normalisePath(path, this.workspaceBase);
+    return this.entries.has(norm) || this.directories.has(norm);
+  }
+  async stat(path) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
+    if (entry) {
+      return {
+        isFile: true,
+        isDirectory: false,
+        isSymbolicLink: false,
+        size: entry.size,
+        mtime: new Date(entry.mtime)
+      };
+    }
+    if (this.directories.has(norm)) {
+      return {
+        isFile: false,
+        isDirectory: true,
+        isSymbolicLink: false,
+        size: 0,
+        mtime: /* @__PURE__ */ new Date()
+      };
+    }
+    throw new Error(`ENOENT: no such file or directory: ${path}`);
+  }
+  async readdir(path) {
+    const norm = normalisePath(path, this.workspaceBase);
+    if (!this.directories.has(norm)) {
+      throw new Error(`ENOENT: no such directory: ${path}`);
+    }
+    const prefix = norm === "/" ? "/" : norm + "/";
+    const names = /* @__PURE__ */ new Set();
+    for (const p of this.entries.keys()) {
+      if (p.startsWith(prefix)) {
+        const rest = p.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    for (const d of this.directories) {
+      if (d.startsWith(prefix) && d !== norm) {
+        const rest = d.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    return [...names].sort();
+  }
+  async readdirWithFileTypes(path) {
+    const names = await this.readdir(path);
+    const norm = normalisePath(path, this.workspaceBase);
+    const prefix = norm === "/" ? "/" : norm + "/";
+    return names.map((name) => {
+      const full = prefix + name;
+      const isFile = this.entries.has(full);
+      const isDirectory = this.directories.has(full);
+      return { name, isFile, isDirectory, isSymbolicLink: false };
+    });
+  }
+  // --------------------------------------------------------------------------
+  // Write operations — delegate to resolver, record mutations
+  // --------------------------------------------------------------------------
+  async writeFile(path, content) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const existing = this.entries.get(norm);
+    if (existing) {
+      await this.resolver.writeFile(
+        existing.id,
+        content,
+        this.ctx,
+        existing.metadata
+      );
+      const size = typeof content === "string" ? new TextEncoder().encode(content).byteLength : content.byteLength;
+      const updated = {
+        ...existing,
+        size,
+        mtime: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.entries.set(norm, updated);
+      this.mutations.push({ type: "update", path: norm, entry: updated });
+    } else {
+      const entry = await this.resolver.createFile(norm, content, this.ctx);
+      const normalised = { ...entry, path: norm };
+      this.entries.set(norm, normalised);
+      this.addParentDirectories(norm);
+      this.mutations.push({ type: "add", entry: normalised });
+    }
+  }
+  async appendFile(path, content) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const existing = this.entries.get(norm);
+    if (!existing) {
+      return this.writeFile(path, content);
+    }
+    const current = await this.resolver.readFile(
+      existing.id,
+      this.ctx,
+      existing.metadata
+    );
+    const appended = typeof content === "string" ? current + content : current + new TextDecoder().decode(content);
+    await this.resolver.writeFile(
+      existing.id,
+      appended,
+      this.ctx,
+      existing.metadata
+    );
+    const size = new TextEncoder().encode(appended).byteLength;
+    const updated = {
+      ...existing,
+      size,
+      mtime: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.entries.set(norm, updated);
+    this.mutations.push({ type: "update", path: norm, entry: updated });
+  }
+  async mkdir(_path, _options) {
+    const norm = normalisePath(_path, this.workspaceBase);
+    if (this.directories.has(norm)) return;
+    if (_options?.recursive) {
+      this.addParentDirectories(norm + "/placeholder");
+      this.directories.add(norm);
+    } else {
+      const parent = parentDir(norm);
+      if (!this.directories.has(parent)) {
+        throw new Error(`ENOENT: no such directory: ${parent}`);
+      }
+      this.directories.add(norm);
+    }
+  }
+  async rm(path, options) {
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
+    if (entry) {
+      await this.resolver.deleteFile(entry.id, this.ctx, entry.metadata);
+      this.entries.delete(norm);
+      this.mutations.push({ type: "remove", path: norm });
+      return;
+    }
+    if (this.directories.has(norm)) {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: is a directory (use recursive): ${path}`);
+      }
+      const prefix = norm === "/" ? "/" : norm + "/";
+      for (const [p, e] of this.entries) {
+        if (p.startsWith(prefix)) {
+          await this.resolver.deleteFile(e.id, this.ctx, e.metadata);
+          this.entries.delete(p);
+          this.mutations.push({ type: "remove", path: p });
+        }
+      }
+      for (const d of this.directories) {
+        if (d.startsWith(prefix)) this.directories.delete(d);
+      }
+      this.directories.delete(norm);
+      return;
+    }
+    if (!options?.force) {
+      throw new Error(`ENOENT: no such file or directory: ${path}`);
+    }
+  }
+  async cp(src, dest, _options) {
+    const normSrc = normalisePath(src, this.workspaceBase);
+    const normDest = normalisePath(dest, this.workspaceBase);
+    const entry = this.entries.get(normSrc);
+    if (entry) {
+      const content = await this.resolver.readFile(
+        entry.id,
+        this.ctx,
+        entry.metadata
+      );
+      await this.writeFile(normDest, content);
+      return;
+    }
+    if (!this.directories.has(normSrc)) {
+      throw new Error(`ENOENT: no such file or directory: ${src}`);
+    }
+    if (!_options?.recursive) {
+      throw new Error(`EISDIR: is a directory (use recursive): ${src}`);
+    }
+    const prefix = normSrc === "/" ? "/" : normSrc + "/";
+    for (const [p, e] of this.entries) {
+      if (p.startsWith(prefix)) {
+        const relative = p.slice(normSrc.length);
+        const content = await this.resolver.readFile(
+          e.id,
+          this.ctx,
+          e.metadata
+        );
+        await this.writeFile(normDest + relative, content);
+      }
+    }
+  }
+  async mv(src, dest) {
+    await this.cp(src, dest, { recursive: true });
+    await this.rm(src, { recursive: true });
+  }
+  // --------------------------------------------------------------------------
+  // Unsupported
+  // --------------------------------------------------------------------------
+  async readlink(_path) {
+    throw new SandboxNotSupportedError("readlink");
+  }
+  resolvePath(base, path) {
+    return posix.resolve(normalisePath(base, this.workspaceBase), path);
+  }
+  // --------------------------------------------------------------------------
+  // Helpers
+  // --------------------------------------------------------------------------
+  addParentDirectories(filePath) {
+    let dir = parentDir(normalisePath(filePath, this.workspaceBase));
+    while (!this.directories.has(dir)) {
+      this.directories.add(dir);
+      dir = parentDir(dir);
+    }
+  }
+};
+
+// src/lib/virtual-fs/with-virtual-fs.ts
+function withVirtualFs(client, resolver, handler) {
+  return async (args, context) => {
+    const state = await queryParentWorkflowState(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
+      }
+    };
+  };
+}
+
+// src/lib/virtual-fs/manager.ts
+function createVirtualFsActivities(resolver, scope) {
+  const ops = {
+    resolveFileTree: async (ctx) => {
+      const fileTree = await resolver.resolveEntries(ctx);
+      return { fileTree };
+    }
+  };
+  const prefix = scope;
+  const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+  return Object.fromEntries(
+    Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+  );
+}
 
 // src/tools/bash/handler.ts
 var bashHandler = async (args, { sandbox }) => {
@@ -2419,6 +2921,6 @@ var toTree = async (fs, opts = {}) => {
   return base + subtree;
 };
 
-export { FileSystemSkillProvider, NodeFsSandboxFileSystem, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, writeFileHandler, writeFileTool };
+export { FileSystemSkillProvider, NodeFsSandboxFileSystem, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, VirtualFileSystem, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, composeHooks, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createObservabilityHooks, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, createVirtualFsActivities, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyVirtualFsOps, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler, writeFileTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map