zeitlich 0.2.29 → 0.2.31

package/src/lib/session/session.ts

@@ -8,7 +8,11 @@ import {
 import type { SessionExitReason } from "../types";
 import type { SessionConfig, ZeitlichSession } from "./types";
 import type { SandboxOps } from "../sandbox/types";
-import { type AgentStateManager, type JsonSerializable } from "../state/types";
+import type {
+  AgentState,
+  AgentStateManager,
+  JsonSerializable,
+} from "../state/types";
 import { createToolRouter } from "../tool-router/router";
 import type { ParsedToolCallUnion, ToolMap } from "../tool-router/types";
 import { getShortId } from "../thread/id";
@@ -23,7 +27,7 @@ import { uuid4 } from "@temporalio/workflow";
  * Returns undefined when no skills carry resource contents.
  */
 function collectSkillFiles(
-  skills: Skill[],
+  skills: Skill[]
 ): Record<string, string> | undefined {
   let files: Record<string, string> | undefined;
   for (const skill of skills) {
@@ -67,13 +71,23 @@ function collectSkillFiles(
  * const { finalMessage, exitReason } = await session.runSession({ stateManager });
  * ```
  */
-export async function createSession<T extends ToolMap, M = unknown, TContent = string>(
+export async function createSession<
+  T extends ToolMap,
+  M = unknown,
+  TContent = string,
+>(
   config: SessionConfig<T, M, TContent> & { sandboxOps: SandboxOps }
 ): Promise<ZeitlichSession<M, true>>;
-export async function createSession<T extends ToolMap, M = unknown, TContent = string>(
-  config: SessionConfig<T, M, TContent>
-): Promise<ZeitlichSession<M, false>>;
-export async function createSession<T extends ToolMap, M = unknown, TContent = string>({
+export async function createSession<
+  T extends ToolMap,
+  M = unknown,
+  TContent = string,
+>(config: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, false>>;
+export async function createSession<
+  T extends ToolMap,
+  M = unknown,
+  TContent = string,
+>({
   agentName,
   maxTurns = 50,
   metadata = {},
@@ -93,6 +107,7 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
   sandbox: sandboxInit,
   sandboxShutdown = "destroy",
   virtualFs: virtualFsConfig,
+  virtualFsOps,
 }: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, boolean>> {
   // ---------------------------------------------------------------------------
   // Thread resolution
@@ -103,15 +118,18 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
 
   switch (threadMode) {
     case "new":
-      threadId = threadInit?.mode === "new" && threadInit.threadId
-        ? threadInit.threadId
-        : getShortId();
+      threadId =
+        threadInit?.mode === "new" && threadInit.threadId
+          ? threadInit.threadId
+          : getShortId();
       break;
     case "continue":
-      threadId = (threadInit as { mode: "continue"; threadId: string }).threadId;
+      threadId = (threadInit as { mode: "continue"; threadId: string })
+        .threadId;
       break;
     case "fork":
-      sourceThreadId = (threadInit as { mode: "fork"; threadId: string }).threadId;
+      sourceThreadId = (threadInit as { mode: "fork"; threadId: string })
+        .threadId;
       threadId = getShortId();
       break;
   }
@@ -126,11 +144,9 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
 
   const plugins: ToolMap[string][] = [];
   let destroySubagentSandboxes: (() => Promise<void>) | undefined;
-  let sandboxStateGetter: (() => Record<string, unknown> | undefined) | undefined;
+
   if (subagents) {
-    const result = buildSubagentRegistration(subagents, {
-      getSandboxStateForInheritance: () => sandboxStateGetter?.(),
-    });
+    const result = buildSubagentRegistration(subagents);
     if (result) {
       plugins.push(result.registration);
       destroySubagentSandboxes = result.destroySubagentSandboxes;
@@ -197,27 +213,16 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
       let sandboxId: string | undefined;
       let sandboxOwned = false;
 
-      sandboxStateGetter = () => {
-        const fileTree = stateManager.get("fileTree" as keyof TState);
-        const resolverContext = stateManager.get("resolverContext" as keyof TState);
-        const workspaceBase = stateManager.get("workspaceBase" as keyof TState);
-        if (!fileTree && !resolverContext && !workspaceBase) return undefined;
-        return {
-          ...(fileTree !== undefined && { fileTree }),
-          ...(resolverContext !== undefined && { resolverContext }),
-          ...(workspaceBase !== undefined && { workspaceBase }),
-        };
-      };
-
       if (sandboxMode === "inherit") {
-        const inheritInit = sandboxInit as { mode: "inherit"; sandboxId: string; stateUpdate?: Record<string, unknown> };
+        const inheritInit = sandboxInit as {
+          mode: "inherit";
+          sandboxId: string;
+        };
         sandboxId = inheritInit.sandboxId;
-        if (inheritInit.stateUpdate) {
-          stateManager.mergeUpdate(inheritInit.stateUpdate as Partial<TState>);
-        }
         if (!sandboxOps) {
           throw ApplicationFailure.create({
-            message: "sandboxId provided but no sandboxOps — cannot manage sandbox lifecycle",
+            message:
+              "sandboxId provided but no sandboxOps — cannot manage sandbox lifecycle",
             nonRetryable: true,
           });
         }
@@ -228,7 +233,8 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
             nonRetryable: true,
           });
         }
-        sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string }).sandboxId;
+        sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string })
+          .sandboxId;
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
         if (!sandboxOps) {
@@ -243,27 +249,44 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
         sandboxOwned = true;
       } else if (sandboxOps) {
         const skillFiles = skills ? collectSkillFiles(skills) : undefined;
-        const result = await sandboxOps.createSandbox(
-          skillFiles ? { initialFiles: skillFiles } : undefined,
-        );
-        sandboxId = result.sandboxId;
-        sandboxOwned = true;
-        if (result.stateUpdate) {
-          stateManager.mergeUpdate(result.stateUpdate as Partial<TState>);
+        const ctx = (sandboxInit as { mode: "new"; ctx?: unknown } | undefined)
+          ?.ctx;
+        const createOptions = skillFiles
+          ? { initialFiles: skillFiles }
+          : undefined;
+        const result = await sandboxOps.createSandbox(createOptions, ctx);
+        if (result) {
+          sandboxId = result.sandboxId;
+          sandboxOwned = true;
         }
       }
 
       // --- Virtual filesystem init (independent of sandbox) ----------------
       if (virtualFsConfig) {
-        const result = await virtualFsConfig.ops.resolveFileTree(
-          virtualFsConfig.resolverContext,
-        );
+        if (!virtualFsOps) {
+          throw ApplicationFailure.create({
+            message: "No virtualFsOps provided — cannot resolve file tree",
+            nonRetryable: true,
+          });
+        }
+        const result = await virtualFsOps.resolveFileTree(virtualFsConfig.ctx);
+        const skillFiles = skills ? collectSkillFiles(skills) : undefined;
+        const fileTree = skillFiles
+          ? [
+              ...result.fileTree,
+              ...Object.entries(skillFiles).map(([path, content]) => ({
+                id: `skill:${path}`,
+                path,
+                size: content.length,
+                mtime: new Date().toISOString(),
+                metadata: {},
+              })),
+            ]
+          : result.fileTree;
         stateManager.mergeUpdate({
-          fileTree: result.fileTree,
-          resolverContext: virtualFsConfig.resolverContext,
-          workspaceBase: virtualFsConfig.workspaceBase ?? "/",
-          ...result.stateUpdate,
-        } as unknown as Partial<TState>);
+          fileTree,
+          ...(skillFiles && { inlineFiles: skillFiles }),
+        } as Partial<AgentState<TState>>);
       }
 
       if (hooks.onSessionStart) {
@@ -303,7 +326,12 @@ export async function createSession<T extends ToolMap, M = unknown, TContent = s
           await initializeThread(threadId, threadKey);
         }
       }
-      await appendHumanMessage(threadId, uuid4(), await buildContextMessage(), threadKey);
+      await appendHumanMessage(
+        threadId,
+        uuid4(),
+        await buildContextMessage(),
+        threadKey
+      );
 
       let exitReason: SessionExitReason = "completed";
 

package/src/lib/session/types.ts

@@ -1,8 +1,5 @@
 import type { Duration } from "@temporalio/common";
-import type {
-  ToolResultConfig,
-  SessionExitReason,
-} from "../types";
+import type { ToolResultConfig, SessionExitReason } from "../types";
 import type {
   ToolMap,
   ToolCallResultUnion,
@@ -16,7 +13,11 @@ import type { VirtualFsOps } from "../virtual-fs/types";
 import type { RunAgentActivity } from "../model/types";
 import type { AgentStateManager, JsonSerializable } from "../state/types";
 import type { ActivityInterfaceFor } from "@temporalio/workflow";
-import type { ThreadInit, SandboxInit, SubagentSandboxShutdown } from "../lifecycle";
+import type {
+  ThreadInit,
+  SandboxInit,
+  SubagentSandboxShutdown,
+} from "../lifecycle";
 
 /**
  * Thread operations required by a session.
@@ -34,7 +35,7 @@ export interface ThreadOps<TContent = string> {
     threadId: string,
     id: string,
     content: TContent,
-    threadKey?: string,
+    threadKey?: string
   ): Promise<void>;
   /** Append a tool result to the thread */
   appendToolResult(id: string, config: ToolResultConfig): Promise<void>;
@@ -43,10 +44,14 @@ export interface ThreadOps<TContent = string> {
     threadId: string,
     id: string,
     content: string,
-    threadKey?: string,
+    threadKey?: string
   ): Promise<void>;
   /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
-  forkThread(sourceThreadId: string, targetThreadId: string, threadKey?: string): Promise<void>;
+  forkThread(
+    sourceThreadId: string,
+    targetThreadId: string,
+    threadKey?: string
+  ): Promise<void>;
 }
 
 /**
@@ -87,7 +92,11 @@ export type PrefixedThreadOps<TPrefix extends string, TContent = string> = {
  * @typeParam M - SDK-native message type returned by the model invoker
  * @typeParam TContent - SDK-native content type for human messages (defaults to `string`)
  */
-export interface SessionConfig<T extends ToolMap, M = unknown, TContent = string> {
+export interface SessionConfig<
+  T extends ToolMap,
+  M = unknown,
+  TContent = string,
+> {
   /** The name of the agent, should be unique within the workflows */
   agentName: string;
   /** Metadata for the session */
@@ -169,20 +178,20 @@ export interface SessionConfig<T extends ToolMap, M = unknown, TContent = string
   // Virtual filesystem
   // ---------------------------------------------------------------------------
 
+  virtualFsOps?: VirtualFsOps;
+
   /**
    * Virtual filesystem configuration (optional — independent of sandbox).
    *
    * When provided, the session resolves the file tree on start and merges
-   * `fileTree`, `resolverContext`, and `workspaceBase` into `AgentState`.
+   * `fileTree`, `ctx`, and `workspaceBase` into `AgentState`.
    * Tool handlers wrapped with `withVirtualFs` can then read this state.
    *
    * Can be used alongside `sandboxOps` for agents that need both a real
    * sandbox (e.g. for execution) and a virtual filesystem.
    */
   virtualFs?: {
-    ops: VirtualFsOps;
-    resolverContext: unknown;
-    workspaceBase?: string;
+    ctx: unknown;
   };
 }
 

package/src/lib/state/types.ts

@@ -1,8 +1,11 @@
-import type {
-  QueryDefinition,
-} from "@temporalio/workflow";
+import type { QueryDefinition } from "@temporalio/workflow";
 import type { UpdateDefinition } from "@temporalio/common/lib/interfaces";
-import type { AgentStatus, BaseAgentState, TokenUsage, WorkflowTask } from "../types";
+import type {
+  AgentStatus,
+  BaseAgentState,
+  TokenUsage,
+  WorkflowTask,
+} from "../types";
 import type { ToolDefinition } from "../tool-router/types";
 
 /**
@@ -98,8 +101,8 @@ export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
   /** Set a custom state value by key */
   set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
 
-  /** Bulk-merge a partial update into custom state (e.g. from sandbox stateUpdate) */
-  mergeUpdate(update: Partial<TCustom>): void;
+  /** Bulk-merge a partial update into custom state */
+  mergeUpdate(update: Partial<AgentState<TCustom>>): void;
 
   /** Get full state for query handler */
   getCurrentState(): AgentState<TCustom>;

package/src/lib/subagent/handler.ts

@@ -17,7 +17,11 @@ import type {
 } from "./types";
 import type { SubagentArgs } from "./tool";
 import type { z } from "zod";
-import type { ThreadInit, SandboxInit, SubagentSandboxShutdown } from "../lifecycle";
+import type {
+  ThreadInit,
+  SandboxInit,
+  SubagentSandboxShutdown,
+} from "../lifecycle";
 import { childResultSignal, destroySandboxSignal } from "./signals";
 
 /**
@@ -45,9 +49,9 @@ function resolveSandboxConfig(config?: SubagentSandboxConfig): {
  */
 export function createSubagentHandler<
   const T extends readonly SubagentConfig[],
->(subagents: [...T], options?: {
-  getSandboxStateForInheritance?: () => Record<string, unknown> | undefined;
-}): {
+>(
+  subagents: [...T]
+): {
   handler: (
     args: SubagentArgs,
     context: RouterContext
@@ -99,18 +103,18 @@ export function createSubagentHandler<
     // --- Build thread init ---
     let thread: ThreadInit | undefined;
     if (continuationThreadId) {
-      thread = { mode: threadMode as "fork" | "continue", threadId: continuationThreadId };
-
+      thread = {
+        mode: threadMode as "fork" | "continue",
+        threadId: continuationThreadId,
+      };
     }
 
     // --- Build sandbox init ---
     let sandbox: SandboxInit | undefined;
     if (sandboxCfg.source === "inherit" && parentSandboxId) {
-      const stateUpdate = options?.getSandboxStateForInheritance?.();
       sandbox = {
         mode: "inherit",
         sandboxId: parentSandboxId,
-        ...(stateUpdate && { stateUpdate }),
       };
     } else if (sandboxCfg.source === "own") {
       const prevSbId = continuationThreadId
@@ -156,7 +160,8 @@ export function createSubagentHandler<
     const effectiveShutdown = sandboxCfg.shutdown ?? "destroy";
     const shouldDeferDestroy =
       effectiveShutdown === "pause-until-parent-close" &&
-      (sandboxCfg.source === "own" || (allowsContinuation && sandboxCfg.source !== "inherit"));
+      (sandboxCfg.source === "own" ||
+        (allowsContinuation && sandboxCfg.source !== "inherit"));
 
     if (shouldDeferDestroy) {
       pendingDestroys.set(childWorkflowId, childHandle);
@@ -231,9 +236,10 @@ export function createSubagentHandler<
     let finalToolResponse: JsonValue = toolResponse;
 
     if (allowsContinuation && childThreadId) {
-      const responseStr = typeof toolResponse === "string"
-        ? toolResponse
-        : JSON.stringify(toolResponse);
+      const responseStr =
+        typeof toolResponse === "string"
+          ? toolResponse
+          : JSON.stringify(toolResponse);
       finalToolResponse = `${responseStr}\n\n[${config.agentName} Thread ID: ${childThreadId}]`;
     }
 

package/src/lib/subagent/register.ts

@@ -6,7 +6,11 @@ import type {
 } from "../tool-router/types";
 import type { SubagentConfig, SubagentHooks } from "./types";
 import type { z } from "zod";
-import { createSubagentTool, SUBAGENT_TOOL_NAME, type SubagentArgs } from "./tool";
+import {
+  createSubagentTool,
+  SUBAGENT_TOOL_NAME,
+  type SubagentArgs,
+} from "./tool";
 import { createSubagentHandler } from "./handler";
 
 /**
@@ -19,12 +23,7 @@ import { createSubagentHandler } from "./handler";
  *
  * Returns null if no subagents are configured.
  */
-export function buildSubagentRegistration(
-  subagents: SubagentConfig[],
-  options?: {
-    getSandboxStateForInheritance?: () => Record<string, unknown> | undefined;
-  },
-): {
+export function buildSubagentRegistration(subagents: SubagentConfig[]): {
   registration: ToolMap[string];
   destroySubagentSandboxes: () => Promise<void>;
 } | null {
@@ -32,7 +31,7 @@ export function buildSubagentRegistration(
 
   const getEnabled = (): SubagentConfig[] =>
     subagents.filter((s) =>
-      typeof s.enabled === "function" ? s.enabled() : (s.enabled ?? true),
+      typeof s.enabled === "function" ? s.enabled() : (s.enabled ?? true)
     );
 
   const subagentHooksMap = new Map<string, SubagentHooks>();
@@ -43,15 +42,15 @@ export function buildSubagentRegistration(
   const resolveSubagentName = (args: unknown): string =>
     (args as SubagentArgs).subagent;
 
-  const { handler, destroySubagentSandboxes } = createSubagentHandler(subagents, {
-    getSandboxStateForInheritance: options?.getSandboxStateForInheritance,
-  });
+  const { handler, destroySubagentSandboxes } =
+    createSubagentHandler(subagents);
 
   const registration: ToolMap[string] = {
     name: SUBAGENT_TOOL_NAME,
     enabled: (): boolean => getEnabled().length > 0,
     description: (): string => createSubagentTool(getEnabled()).description,
-    schema: (): z.ZodObject<z.ZodRawShape> => createSubagentTool(getEnabled()).schema,
+    schema: (): z.ZodObject<z.ZodRawShape> =>
+      createSubagentTool(getEnabled()).schema,
     handler,
     ...(subagentHooksMap.size > 0 && {
       hooks: {

package/src/lib/types.ts

@@ -1,4 +1,5 @@
 import type { JsonValue } from "./state/types";
+import type { FileEntry } from "./virtual-fs/types";
 
 // ============================================================================
 // Agent core types
@@ -23,6 +24,9 @@ export interface BaseAgentState {
   version: number;
   turns: number;
   tasks: Map<string, WorkflowTask>;
+  fileTree: FileEntry[];
+  /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+  inlineFiles?: Record<string, string>;
   systemPrompt?: string;
   totalInputTokens: number;
   totalOutputTokens: number;

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

@@ -60,17 +60,28 @@ export class VirtualFileSystem<
   private directories: Set<string>;
   private mutations: TreeMutation<TMeta>[] = [];
 
+  private inlineFiles: Map<string, string>;
+
   constructor(
     tree: FileEntry<TMeta>[],
     private resolver: FileResolver<TCtx, TMeta>,
     private ctx: TCtx,
     workspaceBase = "/",
+    inlineFiles?: Record<string, string>,
   ) {
     this.workspaceBase = normalisePath(workspaceBase);
     this.entries = new Map(
       tree.map((e) => [normalisePath(e.path, this.workspaceBase), e])
     );
     this.directories = inferDirectories(tree, this.workspaceBase);
+    this.inlineFiles = new Map(
+      inlineFiles
+        ? Object.entries(inlineFiles).map(([p, c]) => [
+            normalisePath(p, this.workspaceBase),
+            c,
+          ])
+        : []
+    );
   }
 
   /** Return all mutations accumulated during this invocation. */
@@ -89,6 +100,8 @@ export class VirtualFileSystem<
 
   async readFile(path: string): Promise<string> {
     const norm = normalisePath(path, this.workspaceBase);
+    const inline = this.inlineFiles.get(norm);
+    if (inline !== undefined) 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);
@@ -96,6 +109,8 @@ export class VirtualFileSystem<
 
   async readFileBuffer(path: string): Promise<Uint8Array> {
     const norm = normalisePath(path, this.workspaceBase);
+    const inline = this.inlineFiles.get(norm);
+    if (inline !== undefined) return new TextEncoder().encode(inline);
     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);

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

@@ -81,15 +81,9 @@ export interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
  * Unlike {@link SandboxOps}, this only exposes what is actually needed:
  * resolving the initial file tree from the consumer's data layer.
  */
-export interface VirtualFsOps<
-  TCtx = unknown,
-  TMeta = FileEntryMetadata,
-> {
-  resolveFileTree(
-    ctx: TCtx,
-  ): Promise<{
+export interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
+  resolveFileTree(ctx: TCtx): Promise<{
     fileTree: FileEntry<TMeta>[];
-    stateUpdate?: Record<string, unknown>;
   }>;
 }
 
@@ -107,7 +101,10 @@ export type PrefixedVirtualFsOps<
   TCtx = unknown,
   TMeta = FileEntryMetadata,
 > = {
-  [K in keyof VirtualFsOps<TCtx, TMeta> as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+  [K in keyof VirtualFsOps<
+    TCtx,
+    TMeta
+  > as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
 };
 
 // ============================================================================
@@ -119,13 +116,12 @@ export type PrefixedVirtualFsOps<
  * {@link queryParentWorkflowState}. Populated automatically by the session
  * when `virtualFs` config is provided.
  */
-export interface VirtualFsState<
-  TCtx = unknown,
-  TMeta = FileEntryMetadata,
-> {
+export interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
   fileTree: FileEntry<TMeta>[];
-  resolverContext: TCtx;
+  ctx: TCtx;
   workspaceBase?: string;
+  /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+  inlineFiles?: Record<string, string>;
 }
 
 // ============================================================================

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

@@ -325,6 +325,70 @@ describe("VirtualFileSystem", () => {
   });
 });
 
+// ============================================================================
+// VirtualFileSystem — inlineFiles
+// ============================================================================
+
+describe("VirtualFileSystem — inlineFiles", () => {
+  const skillEntry: FileEntry = {
+    id: "skill:code-review:checklist.md",
+    path: "/skills/code-review/checklist.md",
+    size: 18,
+    mtime: "2025-01-01T00:00:00.000Z",
+    metadata: {},
+  };
+
+  const inlineFiles: Record<string, string> = {
+    "/skills/code-review/checklist.md": "# Review checklist",
+  };
+
+  function createFsWithInline() {
+    const { resolver } = createMockResolver();
+    return new VirtualFileSystem(
+      [...sampleTree, skillEntry],
+      resolver,
+      ctx,
+      "/",
+      inlineFiles,
+    );
+  }
+
+  it("readFile returns inline content instead of hitting the resolver", async () => {
+    const fs = createFsWithInline();
+    const content = await fs.readFile("/skills/code-review/checklist.md");
+    expect(content).toBe("# Review checklist");
+  });
+
+  it("readFileBuffer returns inline content as Uint8Array", async () => {
+    const fs = createFsWithInline();
+    const buf = await fs.readFileBuffer("/skills/code-review/checklist.md");
+    expect(new TextDecoder().decode(buf)).toBe("# Review checklist");
+  });
+
+  it("inline files are visible in readdir", async () => {
+    const fs = createFsWithInline();
+    const names = await fs.readdir("/skills/code-review");
+    expect(names).toContain("checklist.md");
+  });
+
+  it("inline file directories are inferred", async () => {
+    const fs = createFsWithInline();
+    expect(await fs.exists("/skills")).toBe(true);
+    expect(await fs.exists("/skills/code-review")).toBe(true);
+  });
+
+  it("readFile still falls back to resolver for non-inline files", async () => {
+    const fs = createFsWithInline();
+    const content = await fs.readFile("/src/index.ts");
+    expect(content).toBe('console.log("hello");');
+  });
+
+  it("readFile throws ENOENT for paths not in tree or inline", async () => {
+    const fs = createFsWithInline();
+    await expect(fs.readFile("/nope.txt")).rejects.toThrow("ENOENT");
+  });
+});
+
 // ============================================================================
 // createVirtualFsActivities
 // ============================================================================

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

@@ -16,7 +16,7 @@ import { VirtualFileSystem } from "./filesystem";
  * 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`
+ * 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
@@ -66,7 +66,7 @@ export function withVirtualFs<
     const state =
       await queryParentWorkflowState<VirtualFsState<TCtx, TMeta>>(client);
 
-    const { fileTree, resolverContext, workspaceBase } = state;
+    const { fileTree, ctx, workspaceBase, inlineFiles } = state;
     if (!fileTree) {
       return {
         toolResponse: `Error: No fileTree in agent state. The ${context.toolName} tool requires a virtual filesystem.`,
@@ -77,8 +77,9 @@ export function withVirtualFs<
     const virtualFs = new VirtualFileSystem(
       fileTree,
       resolver,
-      resolverContext,
+      ctx,
       workspaceBase ?? "/",
+      inlineFiles,
     );
     const response = await handler(args, { ...context, virtualFs });
     const mutations = virtualFs.getMutations();

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);
   });