@poncho-ai/harness 0.35.0 → 0.36.1

package/src/config.ts

@@ -1,12 +1,13 @@
 import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createJiti } from "jiti";
+import type { JsonSchema } from "@poncho-ai/sdk";
 import type { MemoryConfig } from "./memory.js";
 import type { McpConfig } from "./mcp.js";
 import type { StateConfig } from "./state.js";
 
 export interface StorageConfig {
-  provider?: "local" | "memory" | "redis" | "upstash" | "dynamodb";
+  provider?: "local" | "memory" | "sqlite" | "postgresql" | "redis" | "upstash" | "dynamodb";
   urlEnv?: string;
   tokenEnv?: string;
   table?: string;
@@ -21,6 +22,10 @@ export interface StorageConfig {
     enabled?: boolean;
     maxRecallConversations?: number;
   };
+  limits?: {
+    maxFileSize?: number;
+    maxTotalStorage?: number;
+  };
 }
 
 export interface UploadsConfig {
@@ -68,6 +73,97 @@ export interface MessagingChannelConfig {
   allowedUserIds?: number[];
 }
 
+export interface IsolateBinding {
+  description: string;
+  inputSchema: JsonSchema;
+  handler: (input: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+
+/**
+ * Network access configuration for the bash sandbox (curl, wget).
+ * Network access is disabled by default — you must explicitly allow URLs.
+ */
+export interface NetworkConfig {
+  /**
+   * List of allowed URL prefixes. Each entry must be a full origin (scheme + host),
+   * optionally followed by a path prefix.
+   *
+   * Examples:
+   * - `"https://api.example.com"` — allows all paths on this origin
+   * - `"https://api.example.com/v1/"` — allows only paths starting with /v1/
+   *
+   * Entries can be plain strings or objects with header transforms for credentials brokering:
+   * ```
+   * { url: "https://api.example.com", transform: [{ headers: { "Authorization": "Bearer ..." } }] }
+   * ```
+   */
+  allowedUrls?: (string | { url: string; transform?: { headers: Record<string, string> }[] })[];
+  /** Allowed HTTP methods. Defaults to `["GET", "HEAD"]`. */
+  allowedMethods?: ("GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS")[];
+  /** Bypass the allow-list and permit all URLs and methods. Only use in trusted environments. */
+  dangerouslyAllowAll?: boolean;
+  /** Maximum number of redirects to follow. Default: 20. */
+  maxRedirects?: number;
+  /** Request timeout in milliseconds. Default: 30000. */
+  timeoutMs?: number;
+  /** Maximum response body size in bytes. Default: 10MB. */
+  maxResponseSize?: number;
+  /** Reject URLs resolving to private/loopback IPs (SSRF protection). Default: false. */
+  denyPrivateRanges?: boolean;
+}
+
+export interface BashExecutionLimits {
+  /** Maximum function call/recursion depth. Default: 100. */
+  maxCallDepth?: number;
+  /** Maximum number of commands to execute. Default: 10000. */
+  maxCommandCount?: number;
+  /** Maximum loop iterations for while/for/until. Default: 10000. */
+  maxLoopIterations?: number;
+  /** Maximum total output size (stdout + stderr) in bytes. Default: 10MB. */
+  maxOutputSize?: number;
+  /** Maximum string length in bytes. Default: 10MB. */
+  maxStringLength?: number;
+  /** Maximum array elements. Default: 100000. */
+  maxArrayElements?: number;
+}
+
+export interface BashConfig {
+  /**
+   * Whitelist of allowed commands. When set, only these commands are available.
+   * Omit to allow all built-in commands.
+   *
+   * @example ["cat", "grep", "jq", "echo", "ls", "head", "tail", "wc", "sort"]
+   */
+  commands?: string[];
+  /** Execution limits to prevent runaway scripts. */
+  executionLimits?: BashExecutionLimits;
+  /** Enable python3/python commands in the sandbox. Default: false. */
+  python?: boolean;
+  /** Enable js-exec/node commands via QuickJS in the sandbox. Default: false. */
+  javascript?: boolean;
+  /** Environment variables injected into every bash session. */
+  env?: Record<string, string>;
+}
+
+export interface IsolateConfig {
+  /** V8 isolate memory limit in MB. Default: 128 */
+  memoryLimit?: number;
+  /** Execution timeout in ms. Default: 10000 */
+  timeLimit?: number;
+  /** Max combined stdout+stderr in bytes. Default: 65536 */
+  outputLimit?: number;
+  /** Max code input size in bytes. Default: 102400 (100KB) */
+  codeLimit?: number;
+  /** npm packages to bundle and make available via require() */
+  libraries?: string[];
+  /** External API access */
+  apis?: {
+    fetch?: { allowedDomains: string[] };
+  };
+  /** Builder-defined custom bindings injected into the isolate */
+  bindings?: Record<string, IsolateBinding>;
+}
+
 export interface PonchoConfig extends McpConfig {
   harness?: string;
   messaging?: MessagingChannelConfig[];
@@ -142,6 +238,15 @@ export interface PonchoConfig extends McpConfig {
   tenantSecrets?: Record<string, string>;
   /** Set to `false` to disable the built-in web UI (headless / API-only mode). */
   webUi?: false;
+  /** Enable sandboxed V8 isolate code execution. */
+  isolate?: IsolateConfig;
+  /**
+   * Network access for sandboxed tools (bash curl/wget, isolate fetch).
+   * Disabled by default — you must explicitly allow URLs.
+   */
+  network?: NetworkConfig;
+  /** Bash sandbox configuration. */
+  bash?: BashConfig;
   /** Enable browser automation tools. Set `true` for defaults, or provide config. */
   browser?:
     | boolean

package/src/harness.ts

@@ -14,10 +14,24 @@ import type {
 } from "@poncho-ai/sdk";
 import { defineTool, getTextContent } from "@poncho-ai/sdk";
 import type { UploadStore } from "./upload-store.js";
-import { PONCHO_UPLOAD_SCHEME, deriveUploadKey } from "./upload-store.js";
+import { PONCHO_UPLOAD_SCHEME, VFS_SCHEME, deriveUploadKey } from "./upload-store.js";
+import type { StorageEngine } from "./storage/engine.js";
+import { createStorageEngine, type StorageProvider } from "./storage/index.js";
+import {
+  createConversationStoreFromEngine,
+  createMemoryStoreFromEngine,
+  createTodoStoreFromEngine,
+  createReminderStoreFromEngine,
+} from "./storage/store-adapters.js";
+import { BashEnvironmentManager } from "./vfs/bash-manager.js";
+import { createBashTool } from "./vfs/bash-tool.js";
+import { createReadFileTool } from "./vfs/read-file-tool.js";
+import { createEditFileTool } from "./vfs/edit-file-tool.js";
+import { createWriteFileTool } from "./vfs/write-file-tool.js";
+import { PonchoFsAdapter } from "./vfs/poncho-fs-adapter.js";
 import { parseAgentFile, parseAgentMarkdown, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
 import { loadPonchoConfig, resolveMemoryConfig, resolveStateConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
-import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createWriteTool, ponchoDocsTool } from "./default-tools.js";
+import { ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
   createMemoryTools,
@@ -612,14 +626,14 @@ function extractMediaFromToolOutput(output: unknown): {
         obj.type === "file" &&
         typeof obj.data === "string" &&
         typeof obj.mediaType === "string" &&
-        (obj.mediaType as string).startsWith("image/")
+        ((obj.mediaType as string).startsWith("image/") || obj.mediaType === "application/pdf")
       ) {
         mediaItems.push({
           type: "media",
           data: obj.data as string,
           mediaType: obj.mediaType as string,
         });
-        return { type: "file", mediaType: obj.mediaType, filename: obj.filename ?? "image", _stripped: true };
+        return { type: "file", mediaType: obj.mediaType, filename: obj.filename ?? "file", _stripped: true };
       }
       const out: Record<string, unknown> = {};
       for (const [k, v] of Object.entries(obj)) out[k] = walk(v);
@@ -667,6 +681,11 @@ export class AgentHarness {
   private subagentManager?: SubagentManager;
   private readonly archivedToolResultsByConversation = new Map<string, Record<string, ArchivedToolResult>>();
 
+  /** Unified storage engine (replaces individual KV-backed stores). */
+  storageEngine?: StorageEngine;
+  /** Bash environment manager (creates per-tenant bash instances). */
+  private bashManager?: BashEnvironmentManager;
+
   private resolveToolAccess(toolName: string): ToolAccess {
     const tools = this.loadedConfig?.tools;
     if (!tools) return true;
@@ -723,23 +742,8 @@ export class AgentHarness {
   }
 
   private registerConfiguredBuiltInTools(config: PonchoConfig | undefined): void {
-    for (const tool of createDefaultTools(this.workingDir)) {
-      if (this.isToolEnabled(tool.name)) {
-        this.registerIfMissing(tool);
-      }
-    }
-    if (this.isToolEnabled("write_file")) {
-      this.registerIfMissing(createWriteTool(this.workingDir));
-    }
-    if (this.isToolEnabled("edit_file")) {
-      this.registerIfMissing(createEditTool(this.workingDir));
-    }
-    if (this.isToolEnabled("delete_file")) {
-      this.registerIfMissing(createDeleteTool(this.workingDir));
-    }
-    if (this.isToolEnabled("delete_directory")) {
-      this.registerIfMissing(createDeleteDirectoryTool(this.workingDir));
-    }
+    // Old file tools (read_file, write_file, etc.) are replaced by the bash tool.
+    // Only register search tools, poncho_docs, and get_tool_result_by_id.
     for (const tool of createSearchTools()) {
       if (this.isToolEnabled(tool.name)) {
         this.registerIfMissing(tool);
@@ -804,6 +808,33 @@ export class AgentHarness {
     });
   }
 
+  private createVfsAccess(tenantId: string): NonNullable<ToolContext["vfs"]> {
+    const adapter = this.bashManager!.getAdapter(tenantId);
+    return {
+      readFile: (path: string) => adapter.readFileBuffer(path),
+      readText: (path: string) => adapter.readFile(path),
+      writeFile: (path: string, content: Uint8Array, mimeType?: string) =>
+        adapter.writeFile(path, content),
+      writeText: (path: string, content: string) =>
+        adapter.writeFile(path, content),
+      exists: (path: string) => adapter.exists(path),
+      stat: async (path: string) => {
+        const s = await adapter.stat(path);
+        return {
+          size: s.size,
+          isDirectory: s.isDirectory,
+          mimeType: undefined,
+          updatedAt: s.mtime.getTime(),
+        };
+      },
+      readdir: (path: string) => adapter.readdir(path),
+      mkdir: (path: string, options?: { recursive?: boolean }) =>
+        adapter.mkdir(path, options),
+      rm: (path: string, options?: { recursive?: boolean }) =>
+        adapter.rm(path, options),
+    };
+  }
+
   private shouldEnableWriteTool(): boolean {
     const override = process.env.PONCHO_FS_WRITE?.toLowerCase();
     if (override === "1" || override === "true" || override === "yes") {
@@ -990,11 +1021,15 @@ export class AgentHarness {
 
     let store = this.tenantMemoryStores.get(tenantId);
     if (!store) {
-      const agentId = this.parsedAgent?.frontmatter.id ?? this.parsedAgent?.frontmatter.name ?? "unknown";
-      store = createMemoryStore(agentId, this.memoryConfig, {
-        workingDir: this.workingDir,
-        tenantId,
-      });
+      if (this.storageEngine) {
+        store = createMemoryStoreFromEngine(this.storageEngine, tenantId);
+      } else {
+        const agentId = this.parsedAgent?.frontmatter.id ?? this.parsedAgent?.frontmatter.name ?? "unknown";
+        store = createMemoryStore(agentId, this.memoryConfig, {
+          workingDir: this.workingDir,
+          tenantId,
+        });
+      }
       this.tenantMemoryStores.set(tenantId, store);
       // Evict oldest entries if cache grows too large
       if (this.tenantMemoryStores.size > 100) {
@@ -1385,13 +1420,55 @@ export class AgentHarness {
     this.registerSkillTools(skillMetadata);
     const agentId = this.parsedAgent.frontmatter.id ?? this.parsedAgent.frontmatter.name;
 
+    // --- Unified Storage Engine ---
+    const storageProvider = (config?.storage?.provider ?? "sqlite") as StorageProvider;
+    const engine = createStorageEngine({
+      provider: storageProvider,
+      workingDir: this.workingDir,
+      agentId,
+      urlEnv: config?.storage?.urlEnv,
+    });
+    await engine.initialize();
+    this.storageEngine = engine;
+
+    // --- Bash Environment Manager ---
+    const maxFileSize = config?.storage?.limits?.maxFileSize ?? 100 * 1024 * 1024; // 100MB
+    const maxTotalStorage = config?.storage?.limits?.maxTotalStorage ?? 1024 * 1024 * 1024; // 1GB
+    const bashWorkingDir = this.environment === "production" ? null : this.workingDir;
+    this.bashManager = new BashEnvironmentManager(
+      engine,
+      { maxFileSize, maxTotalStorage },
+      bashWorkingDir,
+      config?.bash,
+      config?.network,
+    );
+    // Register VFS tools
+    this.registerIfMissing(createBashTool(this.bashManager));
+    this.registerIfMissing(createReadFileTool(engine));
+    this.registerIfMissing(createEditFileTool(engine));
+    this.registerIfMissing(createWriteFileTool(engine));
+
+    // --- Isolate (V8 sandboxed code execution) ---
+    if (config?.isolate) {
+      const { createRunCodeTool, buildRunCodeDescription, bundleLibraries } = await import("./isolate/index.js");
+      let libraryPreamble: string | null = null;
+      if (config.isolate.libraries?.length) {
+        libraryPreamble = await bundleLibraries(config.isolate.libraries, this.workingDir);
+      }
+      const runCodeTool = createRunCodeTool({
+        config: config.isolate,
+        bashManager: this.bashManager,
+        libraryPreamble,
+        description: buildRunCodeDescription(config.isolate, !!config.network),
+        network: config.network,
+      });
+      this.registerIfMissing(runCodeTool);
+    }
+
+    // --- Memory (engine-backed or legacy fallback) ---
     this.memoryConfig = memoryConfig ?? undefined;
     if (memoryConfig?.enabled) {
-      this.memoryStore = createMemoryStore(
-        agentId,
-        memoryConfig,
-        { workingDir: this.workingDir },
-      );
+      this.memoryStore = createMemoryStoreFromEngine(engine);
       this.dispatcher.registerMany(
         createMemoryTools(
           (ctx) => this.getMemoryStore(ctx.tenantId) ?? this.memoryStore!,
@@ -1400,16 +1477,17 @@ export class AgentHarness {
       );
     }
 
-    const stateConfig = resolveStateConfig(config);
-    this.todoStore = createTodoStore(agentId, stateConfig, { workingDir: this.workingDir });
+    // --- Todos (engine-backed) ---
+    this.todoStore = createTodoStoreFromEngine(engine);
     for (const tool of createTodoTools(this.todoStore)) {
       if (this.isToolEnabled(tool.name)) {
         this.registerIfMissing(tool);
       }
     }
 
+    // --- Reminders (engine-backed) ---
     if (config?.reminders?.enabled) {
-      this.reminderStore = createReminderStore(agentId, stateConfig, { workingDir: this.workingDir });
+      this.reminderStore = createReminderStoreFromEngine(engine);
       for (const tool of createReminderTools(this.reminderStore)) {
         if (this.isToolEnabled(tool.name)) {
           this.registerIfMissing(tool);
@@ -1427,6 +1505,7 @@ export class AgentHarness {
     }
 
     // Secrets store for per-tenant env var overrides
+    const stateConfig = resolveStateConfig(config);
     const authTokenEnv = config?.auth?.tokenEnv ?? "PONCHO_AUTH_TOKEN";
     const authToken = process.env[authTokenEnv];
     if (authToken) {
@@ -1487,60 +1566,22 @@ export class AgentHarness {
       };
     }
 
-    if (provider === "upstash") {
-      const urlEnv = config.storage?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
-      const tokenEnv = config.storage?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
-      const baseUrl = (process.env[urlEnv] ?? "").replace(/\/+$/, "");
-      const token = process.env[tokenEnv] ?? "";
-      if (!baseUrl || !token) return undefined;
-      const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
-      return {
-        async save(json: string) {
-          await fetch(`${baseUrl}/set/${encodeURIComponent(stateKey)}/${encodeURIComponent(json)}`, { method: "POST", headers });
-        },
-        async load() {
-          const res = await fetch(`${baseUrl}/get/${encodeURIComponent(stateKey)}`, { headers });
-          if (!res.ok) return undefined;
-          const body = await res.json() as { result?: string | null };
-          return body.result ?? undefined;
-        },
-      };
-    }
-
-    if (provider === "redis") {
-      const urlEnv = config.storage?.urlEnv ?? "REDIS_URL";
-      const url = process.env[urlEnv] ?? "";
-      if (!url) return undefined;
-      let clientPromise: Promise<{ get(k: string): Promise<string | null>; set(k: string, v: string): Promise<unknown> } | undefined> | undefined;
-      const getClient = () => {
-        if (!clientPromise) {
-          clientPromise = (async () => {
-            try {
-              const mod = (await import("redis")) as unknown as {
-                createClient: (opts: { url: string }) => {
-                  connect(): Promise<unknown>;
-                  get(k: string): Promise<string | null>;
-                  set(k: string, v: string): Promise<unknown>;
-                };
-              };
-              const c = mod.createClient({ url });
-              await c.connect();
-              return c;
-            } catch { return undefined; }
-          })();
-        }
-        return clientPromise;
-      };
+    // For sqlite, postgresql, and all other providers: use local file persistence
+    // (same as "local" above). The old upstash/redis branches have been removed.
+    if (provider === "sqlite" || provider === "postgresql") {
+      const { resolve: pathResolve } = await import("node:path");
+      const { homedir: home } = await import("node:os");
+      const stateDir = pathResolve(home(), ".poncho", "browser-state");
+      const filePath = pathResolve(stateDir, `${sessionId}.json`);
       return {
         async save(json: string) {
-          const c = await getClient();
-          if (c) await c.set(stateKey, json);
+          const { mkdir, writeFile } = await import("node:fs/promises");
+          await mkdir(stateDir, { recursive: true });
+          await writeFile(filePath, json, "utf8");
         },
         async load() {
-          const c = await getClient();
-          if (!c) return undefined;
-          const val = await c.get(stateKey);
-          return val ?? undefined;
+          const { readFile } = await import("node:fs/promises");
+          try { return await readFile(filePath, "utf8"); } catch { return undefined; }
         },
       };
     }
@@ -1632,12 +1673,20 @@ export class AgentHarness {
       this.otlpTracerProvider = undefined;
     }
     this.hasOtlpExporter = false;
+
+    // Cleanup bash environments and storage engine
+    this.bashManager?.destroyAll();
+    await this.storageEngine?.close();
   }
 
   listTools(): ToolDefinition[] {
     return this.dispatcher.list();
   }
 
+  listSkills(): Array<{ name: string; description: string }> {
+    return this.loadedSkills.map((s) => ({ name: s.name, description: s.description }));
+  }
+
   /**
    * Wraps the run() generator with an OTel root span (invoke_agent) so all
    * child spans (LLM calls via AI SDK, tool execution) group under one trace.
@@ -1818,11 +1867,56 @@ ${boundedMainMemory.trim()}`
         ? `\n\n## Open Tasks\n\n${openTodos.map((t) => `- [${t.status === "in_progress" ? "IN PROGRESS" : "PENDING"}] ${t.content} (id: ${t.id})`).join("\n")}`
         : "";
 
+    const fsContext = this.bashManager
+      ? `\n\n## Filesystem
+
+You have a persistent virtual filesystem at \`/\`. Files you create are durable across conversations.
+Use the \`bash\` tool for all file operations (cat, echo, grep, awk, jq, sed, find, etc.).
+
+Filesystem layout:
+- \`/\` — your working directory (persistent, database-backed)${
+          this.environment !== "production"
+            ? `\n- \`/project/\` — the project source code (read-write in dev; protected paths like .env, .git/ are blocked)`
+            : ""
+        }
+
+Examples:${
+          this.environment !== "production"
+            ? `\n- Read a project file: \`cat /project/src/index.ts\``
+            : ""
+        }
+- Write a working file: \`echo "data" > /notes.txt\`
+- Process data: \`cat /data.csv | awk -F, '{print $2}' | sort | uniq -c\`
+
+Files in the VFS are accessible to the user via \`/api/vfs/{path}\`. For example, a file at \`/downloads/report.pdf\` can be linked as \`/api/vfs/downloads/report.pdf\`. Use this to share downloadable files with the user.`
+      : "";
+
+    // Isolate context (code execution guidance + type stubs)
+    let isolateContext = "";
+    if (this.loadedConfig?.isolate && this.dispatcher.get("run_code")) {
+      const { generateIsolateTypeStubs } = await import("./isolate/index.js");
+      const typeStubs = generateIsolateTypeStubs(this.loadedConfig.isolate);
+      isolateContext = `\n\n## Code Execution
+
+You have a \`run_code\` tool for executing JavaScript/TypeScript in a sandboxed V8 isolate.
+
+**When to use \`run_code\` vs \`bash\`:**
+- \`bash\`: file manipulation, text processing with unix tools, shell pipelines
+- \`run_code\`: complex data processing, structured data, npm libraries, multi-step logic, binary file generation
+
+**API reference (available inside the isolate):**
+\`\`\`typescript
+${typeStubs}
+\`\`\`
+
+Code is wrapped in an async IIFE — use \`return\` to return a value to the tool result.`;
+    }
+
     const buildSystemPrompt = (): string => {
       const agentPrompt = renderCurrentAgentPrompt();
       const promptWithSkills = this.skillContextWindow
-        ? `${agentPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}`
-        : `${agentPrompt}${developmentContext}${browserContext}`;
+        ? `${agentPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}${fsContext}${isolateContext}`
+        : `${agentPrompt}${developmentContext}${browserContext}${fsContext}${isolateContext}`;
       const timeContext = this.reminderStore
         ? `\n\nCurrent UTC time: ${new Date().toISOString()}`
         : "";
@@ -2025,9 +2119,37 @@ ${boundedMainMemory.trim()}`
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const rich = (meta as any)?._richToolResults as unknown[] | undefined;
             if (rich && rich.length > 0) {
-              // The rich array already conforms to the AI SDK ToolContent shape
-              // (tool-result parts with multi-part content outputs).  Cast
-              // through `any` because the exact generic types are internal.
+              // Resolve any vfs:// references in media items before sending
+              // to the model. This keeps conversation history lightweight
+              // (only stores the reference) while materializing the actual
+              // bytes on demand at model-request time.
+              if (this.storageEngine) {
+                const tid = input.tenantId ?? "__default__";
+                for (const part of rich) {
+                  const p = part as Record<string, unknown>;
+                  if (p.output && typeof p.output === "object") {
+                    const out = p.output as Record<string, unknown>;
+                    if (Array.isArray(out.value)) {
+                      for (let i = 0; i < out.value.length; i++) {
+                        const item = out.value[i] as Record<string, unknown>;
+                        if (
+                          item.type === "media" &&
+                          typeof item.data === "string" &&
+                          (item.data as string).startsWith(VFS_SCHEME)
+                        ) {
+                          try {
+                            const vfsPath = (item.data as string).slice(VFS_SCHEME.length);
+                            const buf = await this.storageEngine.vfs.readFile(tid, vfsPath);
+                            item.data = Buffer.from(buf).toString("base64");
+                          } catch {
+                            // File no longer available; leave as-is
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
               // eslint-disable-next-line @typescript-eslint/no-explicit-any
               return [{ role: "tool" as const, content: rich as any }];
             }
@@ -2181,7 +2303,11 @@ ${boundedMainMemory.trim()}`
                 if (!isSupportedImage && !isSupportedFile && isTextBasedMime(part.mediaType)) {
                   let textContent: string;
                   try {
-                    if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
+                    if (part.data.startsWith(VFS_SCHEME) && this.storageEngine) {
+                      const vfsPath = part.data.slice(VFS_SCHEME.length);
+                      const buf = await this.storageEngine.vfs.readFile(input.tenantId ?? "__default__", vfsPath);
+                      textContent = Buffer.from(buf).toString("utf8");
+                    } else if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
                       const buf = await this.uploadStore.get(part.data);
                       textContent = buf.toString("utf8");
                     } else if (part.data.startsWith("https://") || part.data.startsWith("http://")) {
@@ -2210,7 +2336,11 @@ ${boundedMainMemory.trim()}`
                 // fetch URLs itself (which fails for private blob stores).
                 let resolvedData: string;
                 try {
-                  if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
+                  if (part.data.startsWith(VFS_SCHEME) && this.storageEngine) {
+                    const vfsPath = part.data.slice(VFS_SCHEME.length);
+                    const buf = await this.storageEngine.vfs.readFile(input.tenantId ?? "__default__", vfsPath);
+                    resolvedData = Buffer.from(buf).toString("base64");
+                  } else if (part.data.startsWith(PONCHO_UPLOAD_SCHEME) && this.uploadStore) {
                     const buf = await this.uploadStore.get(part.data);
                     resolvedData = buf.toString("base64");
                   } else if (part.data.startsWith("https://") || part.data.startsWith("http://")) {
@@ -2649,6 +2779,9 @@ ${boundedMainMemory.trim()}`
         abortSignal: input.abortSignal,
         conversationId: input.conversationId,
         tenantId: input.tenantId,
+        vfs: this.bashManager
+          ? this.createVfsAccess(input.tenantId ?? "__default__")
+          : undefined,
       };
 
       const toolResultsForModel: Array<{
@@ -2841,6 +2974,7 @@ ${boundedMainMemory.trim()}`
         return;
       }
 
+      const callInputMap = new Map(approvedCalls.map((c) => [c.id, c.input]));
       for (const result of batchResults) {
         const span = toolSpans.get(result.callId);
         if (result.error) {
@@ -2894,6 +3028,7 @@ ${boundedMainMemory.trim()}`
           yield pushEvent({
             type: "tool:completed",
             tool: result.tool,
+            input: callInputMap.get(result.callId),
             output: result.output,
             duration: now() - batchStart,
             outputTokenEstimate,

package/src/index.ts

@@ -18,6 +18,11 @@ export * from "./state.js";
 export * from "./upload-store.js";
 export * from "./telemetry.js";
 export * from "./secrets-store.js";
+export * from "./storage/index.js";
+export * from "./storage/store-adapters.js";
+export { PonchoFsAdapter } from "./vfs/poncho-fs-adapter.js";
+export { BashEnvironmentManager } from "./vfs/bash-manager.js";
+export { createBashTool } from "./vfs/bash-tool.js";
 export * from "./tenant-token.js";
 export * from "./tool-dispatcher.js";
 export * from "./subagent-manager.js";