zeitlich 0.2.40 → 0.2.42

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineSignal, CancellationScope, isCancellation, uuid4, setHandler, defineUpdate, ApplicationFailure, log, condition, defineQuery, proxySinks, workflowInfo, proxyActivities, getExternalWorkflowHandle, executeChild } from '@temporalio/workflow';
+import { defineSignal, CancellationScope, isCancellation, uuid4, setHandler, defineUpdate, ApplicationFailure, log, defineQuery, condition, proxySinks, workflowInfo, proxyActivities, getExternalWorkflowHandle, executeChild } from '@temporalio/workflow';
 import z14, { z } from 'zod';
 import { randomUUID, randomFillSync } from 'crypto';
 import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
@@ -7,6 +7,16 @@ import { Context } from '@temporalio/activity';
 import { promises } from 'fs';
 
 // src/lib/session/session.ts
+
+// src/lib/session/types.ts
+function resolveSessionLifecycle(init, shutdown) {
+  const resolvedInit = init ?? { mode: "new" };
+  const resolvedShutdown = shutdown ?? "destroy";
+  return {
+    mode: resolvedInit.mode,
+    shutdown: resolvedShutdown
+  };
+}
 function createToolRouter(options) {
   const { appendToolResult } = options;
   const toolMap = /* @__PURE__ */ new Map();
@@ -435,6 +445,37 @@ function createSubagentTool(subagents) {
     schema
   };
 }
+
+// src/lib/subagent/types.ts
+function isSurvivalShutdown(s) {
+  return s === "pause" || s === "pause-until-parent-close" || s === "keep" || s === "keep-until-parent-close";
+}
+function resolveSubagentLifecycle(cfg, isLazyCreator) {
+  if (cfg.source !== "own") {
+    return {
+      shutdownOverride: cfg.shutdown,
+      mustSurvive: false
+    };
+  }
+  if (cfg.continuation === "snapshot") {
+    return {
+      shutdownOverride: "snapshot",
+      mustSurvive: false
+    };
+  }
+  const isLazy = cfg.init === "once";
+  const mustSurvive = isLazyCreator || cfg.continuation === "continue" || isLazy && cfg.continuation === "fork";
+  if (!mustSurvive) {
+    return { shutdownOverride: cfg.shutdown, mustSurvive: false };
+  }
+  if (isSurvivalShutdown(cfg.shutdown)) {
+    return { shutdownOverride: cfg.shutdown, mustSurvive };
+  }
+  return {
+    shutdownOverride: isLazyCreator ? "pause-until-parent-close" : "pause",
+    mustSurvive
+  };
+}
 var childSandboxReadySignal = defineSignal("childSandboxReady");
 
 // src/lib/subagent/handler.ts
@@ -460,10 +501,18 @@ function resolveSandboxConfig(config) {
 }
 function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflowInfo();
-  const agentSandboxOps = /* @__PURE__ */ new Map();
+  const agentDestroyOps = /* @__PURE__ */ new Map();
+  const agentDeleteSnapshotOps = /* @__PURE__ */ new Map();
   for (const cfg of subagents) {
-    if (cfg.sandbox && cfg.sandbox !== "none") {
-      agentSandboxOps.set(cfg.agentName, cfg.sandbox.proxy(cfg.agentName));
+    const cfgSandbox = cfg.sandbox;
+    if (!cfgSandbox || cfgSandbox === "none") continue;
+    if (cfgSandbox.continuation === "snapshot") {
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
+      agentDeleteSnapshotOps.set(cfg.agentName, proxy);
+    } else {
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
     }
   }
   const pendingDestroys = /* @__PURE__ */ new Map();
@@ -502,7 +551,7 @@ function createSubagentHandler(subagents) {
     const childWorkflowId = `${args.subagent}-${getShortId()}`;
     const { sandboxId: parentSandboxId } = context;
     const sandboxCfg = resolveSandboxConfig(config.sandbox);
-    if (sandboxCfg.source !== "none" && !agentSandboxOps.has(config.agentName)) {
+    if (sandboxCfg.source !== "none" && !agentDestroyOps.has(config.agentName)) {
       throw ApplicationFailure.create({
         message: `Subagent "${config.agentName}" uses a sandbox but no \`sandbox.proxy\` is configured on its SubagentConfig`,
         nonRetryable: true
@@ -570,7 +619,6 @@ function createSubagentHandler(subagents) {
       if (baseSnap) {
         sandbox = { mode: "from-snapshot", snapshot: baseSnap };
       }
-      sandboxShutdownOverride = "snapshot";
     } else if (sandboxCfg.source === "own") {
       const isLazy = sandboxCfg.init === "once";
       let baseSandboxId;
@@ -606,12 +654,10 @@ function createSubagentHandler(subagents) {
           sandboxId: baseSandboxId
         };
       }
-      const userShutdown = sandboxCfg.shutdown;
-      const alreadySurvives = userShutdown === "pause-until-parent-close" || userShutdown === "keep-until-parent-close" || userShutdown === "pause" || userShutdown === "keep";
-      const mustSurvive = isLazyCreator || sandboxCfg.continuation === "continue" || isLazy && sandboxCfg.continuation === "fork";
-      if (mustSurvive && !alreadySurvives) {
-        sandboxShutdownOverride = isLazyCreator ? "pause-until-parent-close" : "pause";
-      }
+    }
+    {
+      const lifecycle = resolveSubagentLifecycle(sandboxCfg, isLazyCreator);
+      sandboxShutdownOverride = lifecycle.shutdownOverride;
     }
     const workflowInput = {
       ...thread && { thread },
@@ -756,7 +802,7 @@ function createSubagentHandler(subagents) {
     pendingDestroys.clear();
     await Promise.all(
       entries.map(async ({ agentName, sandboxId }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDestroyOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping sandbox destroy \u2014 no sandbox.proxy registered for agent",
@@ -786,7 +832,7 @@ function createSubagentHandler(subagents) {
     persistentBaseSnapshot.clear();
     await Promise.all(
       tagged.map(async ({ agentName, snapshot }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDeleteSnapshotOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping snapshot delete \u2014 no sandbox.proxy registered for agent",
@@ -938,30 +984,31 @@ function collectSkillFiles(skills) {
   }
   return files;
 }
-async function createSession({
-  agentName,
-  maxTurns = 50,
-  metadata = {},
-  runAgent,
-  threadOps,
-  buildContextMessage,
-  subagents,
-  skills,
-  tools = {},
-  processToolsInParallel = true,
-  hooks = {},
-  appendSystemPrompt = true,
-  waitForInputTimeout = "48h",
-  threadKey,
-  sandboxOps,
-  thread: threadInit,
-  sandbox: sandboxInit,
-  sandboxShutdown = "destroy",
-  onSandboxReady,
-  onSessionExit,
-  virtualFs: virtualFsConfig,
-  virtualFsOps
-}) {
+async function createSession(config) {
+  const {
+    agentName,
+    maxTurns = 50,
+    metadata = {},
+    runAgent,
+    threadOps,
+    buildContextMessage,
+    subagents,
+    skills,
+    tools = {},
+    processToolsInParallel = true,
+    hooks = {},
+    appendSystemPrompt = true,
+    threadKey,
+    sandboxOps,
+    thread: threadInit,
+    sandbox: sandboxInit,
+    sandboxShutdown,
+    onSandboxReady,
+    onSessionExit,
+    virtualFs: virtualFsConfig,
+    virtualFsOps
+  } = config;
+  const wideOps = () => sandboxOps;
   const threadMode = threadInit?.mode ?? "new";
   let threadId;
   let sourceThreadId;
@@ -1045,7 +1092,12 @@ async function createSession({
           stateManager.run();
         }
       );
-      const sandboxMode = sandboxInit?.mode;
+      const lifecycle = resolveSessionLifecycle(
+        sandboxInit,
+        sandboxShutdown
+      );
+      const sandboxMode = lifecycle.mode;
+      const resolvedShutdown = lifecycle.shutdown;
       let sandboxId;
       let sandboxOwned = false;
       let baseSnapshot;
@@ -1068,8 +1120,8 @@ async function createSession({
           });
         }
         sandboxId = sandboxInit.sandboxId;
-        if (sandboxShutdown === "pause-until-parent-close") {
-          await sandboxOps.resumeSandbox(sandboxId);
+        if (resolvedShutdown === "pause-until-parent-close") {
+          await wideOps().resumeSandbox(sandboxId);
         }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
@@ -1080,7 +1132,7 @@ async function createSession({
           });
         }
         const forkInit = sandboxInit;
-        sandboxId = await sandboxOps.forkSandbox(
+        sandboxId = await wideOps().forkSandbox(
           forkInit.sandboxId,
           forkInit.options
         );
@@ -1093,7 +1145,7 @@ async function createSession({
           });
         }
         const restoreInit = sandboxInit;
-        sandboxId = await sandboxOps.restoreSandbox(
+        sandboxId = await wideOps().restoreSandbox(
           restoreInit.snapshot,
           restoreInit.options
         );
@@ -1109,8 +1161,8 @@ async function createSession({
           freshlyCreated = true;
         }
       }
-      if (sandboxId && sandboxOwned && freshlyCreated && sandboxShutdown === "snapshot" && sandboxOps) {
-        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+      if (sandboxId && sandboxOwned && freshlyCreated && resolvedShutdown === "snapshot" && sandboxOps) {
+        baseSnapshot = await wideOps().snapshotSandbox(sandboxId);
       }
       if (sandboxId && sandboxOwned && onSandboxReady) {
         onSandboxReady({
@@ -1134,12 +1186,23 @@ async function createSession({
             path,
             size: content.length,
             mtime: (/* @__PURE__ */ new Date()).toISOString(),
-            metadata: {}
+            metadata: {},
+            // Carry the content directly on the entry so any handler that
+            // constructs a VirtualFileSystem from `fileTree` can read it
+            // without needing to also wire up `inlineFiles` from state.
+            inlineContent: content
           }))
         ] : result.fileTree;
         stateManager.mergeUpdate({
           fileTree,
           virtualFsCtx: virtualFsConfig.ctx,
+          // `inlineFiles` is still the source of truth at read time:
+          // VirtualFileSystem checks the inlineFiles map first and only
+          // falls through to entry.inlineContent. Embedding the content on
+          // the entry is the migration target so that handlers building a
+          // VirtualFileSystem from `fileTree` alone (without forwarding
+          // `inlineFiles` from state) can read skill resources. Until a
+          // follow-up drops `inlineFiles`, both fields are populated.
           ...skillFiles && { inlineFiles: skillFiles }
         });
       }
@@ -1265,18 +1328,6 @@ async function createSession({
             continue;
           }
           assistantId = void 0;
-          if (stateManager.getStatus() === "WAITING_FOR_INPUT") {
-            const conditionMet = await condition(
-              () => stateManager.getStatus() === "RUNNING",
-              waitForInputTimeout
-            );
-            if (!conditionMet) {
-              stateManager.cancel();
-              exitReason = "cancelled";
-              await condition(() => false, "2s");
-              break;
-            }
-          }
         }
         if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
           exitReason = "max_turns";
@@ -1312,19 +1363,19 @@ async function createSession({
         }
         await callSessionEnd(exitReason, stateManager.getTurns());
         if (sandboxOwned && sandboxId && sandboxOps) {
-          switch (sandboxShutdown) {
+          switch (resolvedShutdown) {
             case "destroy":
               await sandboxOps.destroySandbox(sandboxId);
               break;
             case "pause":
             case "pause-until-parent-close":
-              await sandboxOps.pauseSandbox(sandboxId);
+              await wideOps().pauseSandbox(sandboxId);
               break;
             case "keep":
             case "keep-until-parent-close":
               break;
             case "snapshot":
-              exitSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+              exitSnapshot = await wideOps().snapshotSandbox(sandboxId);
               await sandboxOps.destroySandbox(sandboxId);
               break;
           }
@@ -1350,7 +1401,8 @@ async function createSession({
         onSessionExit({
           ...sandboxId && { sandboxId },
           ...exitSnapshot && { snapshot: exitSnapshot },
-          threadId
+          threadId,
+          usage: stateManager.getTotalUsage()
         });
       }
       return {
@@ -1638,9 +1690,24 @@ function withAutoAppend(threadHandler, handler) {
     };
   };
 }
+var SandboxNotSupportedError = class extends ApplicationFailure$1 {
+  constructor(operation) {
+    super(
+      `Sandbox does not support: ${operation}`,
+      "SandboxNotSupportedError",
+      true
+    );
+  }
+};
+var SandboxNotFoundError = class extends ApplicationFailure$1 {
+  constructor(sandboxId) {
+    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
+  }
+};
 
 // src/lib/tool-router/with-sandbox.ts
-function withSandbox(manager, handler) {
+function withSandbox(manager, handler, options) {
+  const translateSandboxNotFound = options?.translateSandboxNotFound ?? false;
   return async (args, context) => {
     if (!context.sandboxId) {
       return {
@@ -1648,7 +1715,18 @@ function withSandbox(manager, handler) {
         data: null
       };
     }
-    const sandbox = await manager.getSandbox(context.sandboxId);
+    let sandbox;
+    try {
+      sandbox = await manager.getSandbox(context.sandboxId);
+    } catch (err) {
+      if (translateSandboxNotFound && err instanceof SandboxNotFoundError) {
+        return {
+          toolResponse: options?.sandboxNotFoundToolResponse ?? `Error: the execution environment for the ${context.toolName} tool is no longer available, so this tool call could not be completed.`,
+          data: null
+        };
+      }
+      throw err;
+    }
     return handler(args, { ...context, sandbox, sandboxId: context.sandboxId });
   };
 }
@@ -1680,6 +1758,7 @@ function defineSubagentWorkflow(config, fn) {
     let capturedSnapshot;
     let capturedBaseSnapshot;
     let capturedThreadId;
+    let capturedUsage;
     const sessionInput = {
       agentName: config.name,
       sandboxShutdown: effectiveShutdown,
@@ -1696,10 +1775,17 @@ function defineSubagentWorkflow(config, fn) {
           });
         }
       },
-      onSessionExit: ({ sandboxId, snapshot, threadId }) => {
+      onSessionExit: ({ sandboxId, snapshot, threadId, usage }) => {
         capturedSandboxId = sandboxId;
         capturedSnapshot = snapshot;
         capturedThreadId = threadId;
+        capturedUsage = {
+          inputTokens: usage.totalInputTokens,
+          outputTokens: usage.totalOutputTokens,
+          cachedWriteTokens: usage.totalCachedWriteTokens,
+          cachedReadTokens: usage.totalCachedReadTokens,
+          reasonTokens: usage.totalReasonTokens
+        };
       }
     };
     const result = await fn(prompt, sessionInput, context ?? {});
@@ -1710,7 +1796,8 @@ function defineSubagentWorkflow(config, fn) {
       ...capturedSnapshot !== void 0 && { snapshot: capturedSnapshot },
       ...capturedBaseSnapshot !== void 0 && {
         baseSnapshot: capturedBaseSnapshot
-      }
+      },
+      ...capturedUsage !== void 0 && { usage: capturedUsage }
     };
   };
   Object.defineProperty(workflow, "name", { value: config.name });
@@ -1794,20 +1881,6 @@ function proxyRunAgent(scope, options) {
   );
   return acts[name];
 }
-var SandboxNotSupportedError = class extends ApplicationFailure$1 {
-  constructor(operation) {
-    super(
-      `Sandbox does not support: ${operation}`,
-      "SandboxNotSupportedError",
-      true
-    );
-  }
-};
-var SandboxNotFoundError = class extends ApplicationFailure$1 {
-  constructor(sandboxId) {
-    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
-  }
-};
 
 // src/lib/virtual-fs/mutations.ts
 function applyVirtualTreeMutations(stateManager, mutations) {
@@ -2650,6 +2723,9 @@ function getActivityContext() {
 }
 async function queryParentWorkflowState(client) {
   const { workflowExecution } = Context.current().info;
+  if (!workflowExecution) {
+    throw new Error("No workflow execution found");
+  }
   const handle = client.getHandle(
     workflowExecution.workflowId,
     workflowExecution.runId
@@ -2673,13 +2749,56 @@ function withParentWorkflowState(client, handler) {
 }
 
 // src/lib/sandbox/manager.ts
+var CAP_METHOD_TO_CAPABILITY = [
+  { method: "pause", capability: "pause" },
+  { method: "resume", capability: "resume" },
+  { method: "snapshot", capability: "snapshot" },
+  { method: "deleteSnapshot", capability: "snapshot" },
+  { method: "restore", capability: "restore" },
+  { method: "fork", capability: "fork" }
+];
 var SandboxManager = class {
   constructor(provider, options) {
     this.provider = provider;
     this.hooks = options?.hooks ?? {};
+    this.assertCapabilityRuntimeConsistency();
   }
   provider;
   hooks;
+  /**
+   * Verifies that the provider's runtime `supportedCapabilities` set is
+   * consistent with the gated methods physically present on the provider.
+   *
+   * Belt-and-suspenders complement to the type-level
+   * `ReadonlySet<TCaps & SandboxCapability>` constraint: TypeScript can
+   * prevent the runtime set from containing capabilities not declared in
+   * `TCaps`, but it cannot detect a provider that **declares** a cap in
+   * `TCaps` and forgets to include it in the runtime set (or that ships
+   * a method without listing its cap). Both shapes silently break
+   * activity registration, so we trip a loud failure at construction
+   * time instead.
+   *
+   * Adapters that derive both surfaces from a single `as const`
+   * capability array (the recommended pattern) pass this check by
+   * construction.
+   */
+  assertCapabilityRuntimeConsistency() {
+    const supported = this.provider.supportedCapabilities;
+    for (const { method, capability } of CAP_METHOD_TO_CAPABILITY) {
+      const hasMethod = typeof this.provider[method] === "function";
+      const declaresCap = supported.has(capability);
+      if (hasMethod && !declaresCap) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" implements ${method}() but does not list "${capability}" in supportedCapabilities. Add the capability to the provider's runtime set so activities for it can be registered.`
+        );
+      }
+      if (declaresCap && !hasMethod) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" lists "${capability}" in supportedCapabilities but does not implement ${method}(). Either add the method to the provider or remove the capability from supportedCapabilities.`
+        );
+      }
+    }
+  }
   async create(options, ctx) {
     let providerOptions = options;
     if (this.hooks.onPreCreate) {
@@ -2717,26 +2836,61 @@ var SandboxManager = class {
   async destroy(id) {
     await this.provider.destroy(id);
   }
+  /**
+   * Capability-gated lifecycle methods on the underlying provider.
+   *
+   * These manager methods always exist at runtime; calling one whose
+   * capability is absent from the provider's `supportedCapabilities`
+   * throws an error. The activities returned from
+   * {@link SandboxManager.createActivities} are gated at the type level
+   * via `TCaps`, which is where compile-time safety is enforced.
+   */
   async pause(id, ttlSeconds) {
-    await this.provider.pause(id, ttlSeconds);
+    const fn = this.providerMethod("pause");
+    if (!fn) throw this.unsupported("pause");
+    await fn.call(this.provider, id, ttlSeconds);
   }
   async resume(id) {
-    await this.provider.resume(id);
+    const fn = this.providerMethod("resume");
+    if (!fn) throw this.unsupported("resume");
+    await fn.call(this.provider, id);
   }
   async snapshot(id, options) {
-    return this.provider.snapshot(id, options);
+    const fn = this.providerMethod("snapshot");
+    if (!fn) throw this.unsupported("snapshot");
+    return fn.call(this.provider, id, options);
   }
   async restore(snapshot, options) {
-    const sandbox = await this.provider.restore(snapshot, options);
+    const fn = this.providerMethod("restore");
+    if (!fn) throw this.unsupported("restore");
+    const sandbox = await fn.call(this.provider, snapshot, options);
     return sandbox.id;
   }
   async deleteSnapshot(snapshot) {
-    await this.provider.deleteSnapshot(snapshot);
+    const fn = this.providerMethod("deleteSnapshot");
+    if (!fn) throw this.unsupported("deleteSnapshot");
+    await fn.call(this.provider, snapshot);
   }
   async fork(sandboxId, options) {
-    const sandbox = await this.provider.fork(sandboxId, options);
+    const fn = this.providerMethod("fork");
+    if (!fn) throw this.unsupported("fork");
+    const sandbox = await fn.call(this.provider, sandboxId, options);
     return sandbox.id;
   }
+  providerMethod(name) {
+    const value = this.provider[name];
+    return typeof value === "function" ? value : void 0;
+  }
+  /**
+   * Constructs the structured error thrown when an unsupported lifecycle
+   * method is invoked through the manager. Uses the public
+   * {@link SandboxNotSupportedError} symbol so consumers that catch on
+   * `instanceof SandboxNotSupportedError` (the documented compatibility
+   * path) keep matching after the refactor.
+   */
+  unsupported(name) {
+    return new SandboxNotSupportedError(name);
+  }
   /**
    * Returns Temporal activity functions with prefixed names.
    *
@@ -2744,6 +2898,11 @@ var SandboxManager = class {
    * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
    * helper from the adapter's `/workflow` entrypoint on the workflow side.
    *
+   * Activities are only registered for capabilities the provider declares
+   * via {@link SandboxProvider.supportedCapabilities}: methods omitted
+   * from the cap set are not wrapped, and the returned object's type
+   * omits the corresponding keys.
+   *
    * @param scope - Workflow name (appended to the provider id)
    *
    * @example
@@ -2754,40 +2913,55 @@ var SandboxManager = class {
    *
    * const dmgr = new SandboxManager(new DaytonaSandboxProvider(config));
    * dmgr.createActivities("CodingAgent");
-   * // registers: daytonaCodingAgentCreateSandbox, …
+   * // registers: daytonaCodingAgentCreateSandbox, daytonaCodingAgentDestroySandbox
+   * // (snapshot/restore/fork/pause/resume omitted — Daytona doesn't declare them)
    * ```
    */
   createActivities(scope) {
     const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+    const supported = this.provider.supportedCapabilities;
     const ops = {
       createSandbox: async (options, ctx) => {
         return this.create(options, ctx);
       },
       destroySandbox: async (sandboxId) => {
         await this.destroy(sandboxId);
-      },
-      pauseSandbox: async (sandboxId, ttlSeconds) => {
+      }
+    };
+    if (supported.has("pause")) {
+      ops.pauseSandbox = async (sandboxId, ttlSeconds) => {
         await this.pause(sandboxId, ttlSeconds);
-      },
-      resumeSandbox: async (sandboxId) => {
+      };
+    }
+    if (supported.has("resume")) {
+      ops.resumeSandbox = async (sandboxId) => {
         await this.resume(sandboxId);
-      },
-      snapshotSandbox: async (sandboxId, options) => {
+      };
+    }
+    if (supported.has("snapshot")) {
+      ops.snapshotSandbox = async (sandboxId, options) => {
         return this.snapshot(sandboxId, options);
-      },
-      restoreSandbox: async (snapshot, options) => {
-        return this.restore(snapshot, options);
-      },
-      deleteSandboxSnapshot: async (snapshot) => {
+      };
+      ops.deleteSandboxSnapshot = async (snapshot) => {
         await this.deleteSnapshot(snapshot);
-      },
-      forkSandbox: async (sandboxId, options) => {
+      };
+    }
+    if (supported.has("restore")) {
+      ops.restoreSandbox = async (snapshot, options) => {
+        return this.restore(snapshot, options);
+      };
+    }
+    if (supported.has("fork")) {
+      ops.forkSandbox = async (sandboxId, options) => {
         return this.fork(sandboxId, options);
-      }
-    };
-    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+      };
+    }
+    const entries = Object.entries(ops).filter(
+      ([, v]) => typeof v === "function"
+    );
     return Object.fromEntries(
-      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+      entries.map(([k, v]) => [`${prefix}${cap(k)}`, v])
     );
   }
 };
@@ -2920,7 +3094,7 @@ var VirtualFileSystem = class {
     if (inline !== void 0) return inline;
     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);
+    return this.readEntryContent(entry);
   }
   async readFileBuffer(path) {
     const norm = normalisePath(path, this.workspaceBase);
@@ -2928,8 +3102,23 @@ var VirtualFileSystem = class {
     if (inline !== void 0) return new TextEncoder().encode(inline);
     const entry = this.entries.get(norm);
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    if (entry.inlineContent !== void 0) {
+      return new TextEncoder().encode(entry.inlineContent);
+    }
     return this.resolver.readFileBuffer(entry.id, this.ctx, entry.metadata);
   }
+  /**
+   * Resolve the string content for an entry, preferring inline content
+   * carried on the entry itself before consulting the resolver. Used by
+   * `readFile`, `appendFile`, and `cp` so all read paths agree on the
+   * lookup precedence.
+   */
+  readEntryContent(entry) {
+    if (entry.inlineContent !== void 0) {
+      return Promise.resolve(entry.inlineContent);
+    }
+    return this.resolver.readFile(entry.id, this.ctx, entry.metadata);
+  }
   // --------------------------------------------------------------------------
   // Metadata operations — pure, resolved from the tree
   // --------------------------------------------------------------------------
@@ -3001,6 +3190,11 @@ var VirtualFileSystem = class {
     const norm = normalisePath(path, this.workspaceBase);
     const existing = this.entries.get(norm);
     if (existing) {
+      if (existing.inlineContent !== void 0) {
+        throw new Error(
+          `EROFS: cannot write to inline (read-only) entry: ${path}`
+        );
+      }
       await this.resolver.writeFile(
         existing.id,
         content,
@@ -3029,11 +3223,12 @@ var VirtualFileSystem = class {
     if (!existing) {
       return this.writeFile(path, content);
     }
-    const current = await this.resolver.readFile(
-      existing.id,
-      this.ctx,
-      existing.metadata
-    );
+    if (existing.inlineContent !== void 0) {
+      throw new Error(
+        `EROFS: cannot append to inline (read-only) entry: ${path}`
+      );
+    }
+    const current = await this.readEntryContent(existing);
     const appended = typeof content === "string" ? current + content : current + new TextDecoder().decode(content);
     await this.resolver.writeFile(
       existing.id,
@@ -3068,6 +3263,11 @@ var VirtualFileSystem = class {
     const norm = normalisePath(path, this.workspaceBase);
     const entry = this.entries.get(norm);
     if (entry) {
+      if (entry.inlineContent !== void 0) {
+        throw new Error(
+          `EROFS: cannot remove inline (read-only) entry: ${path}`
+        );
+      }
       await this.resolver.deleteFile(entry.id, this.ctx, entry.metadata);
       this.entries.delete(norm);
       this.mutations.push({ type: "remove", path: norm });
@@ -3080,6 +3280,11 @@ var VirtualFileSystem = class {
       const prefix = norm === "/" ? "/" : norm + "/";
       for (const [p, e] of this.entries) {
         if (p.startsWith(prefix)) {
+          if (e.inlineContent !== void 0) {
+            throw new Error(
+              `EROFS: cannot remove inline (read-only) entry: ${p}`
+            );
+          }
           await this.resolver.deleteFile(e.id, this.ctx, e.metadata);
           this.entries.delete(p);
           this.mutations.push({ type: "remove", path: p });
@@ -3100,11 +3305,7 @@ var VirtualFileSystem = class {
     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
-      );
+      const content = await this.readEntryContent(entry);
       await this.writeFile(normDest, content);
       return;
     }
@@ -3118,11 +3319,7 @@ var VirtualFileSystem = class {
     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
-        );
+        const content = await this.readEntryContent(e);
         await this.writeFile(normDest + relative, content);
       }
     }