@poncho-ai/harness 0.43.1 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.43.1",
+  "version": "0.45.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "mustache": "^4.2.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.10.0"
+    "@poncho-ai/sdk": "1.11.0"
   },
   "peerDependencies": {
     "esbuild": ">=0.17.0",

package/src/config.ts

@@ -37,7 +37,26 @@ export interface UploadsConfig {
   endpoint?: string;
 }
 
-export type ToolAccess = boolean | "approval";
+export type ToolAccess =
+  | boolean
+  | "approval"
+  | { access?: "approval"; dispatch?: "device" };
+
+/**
+ * Normalize any ToolAccess value into a {access, dispatch} struct.
+ * `boolean` collapses to no special handling — the boolean only encodes
+ * enable/disable, not dispatch — callers gate behavior on `dispatch` and
+ * `access`.
+ */
+export const normalizeToolAccess = (
+  value: ToolAccess | undefined,
+): { access?: "approval"; dispatch?: "device" } => {
+  if (value === "approval") return { access: "approval" };
+  if (value && typeof value === "object") {
+    return { access: value.access, dispatch: value.dispatch };
+  }
+  return {};
+};
 
 /** @deprecated Use flat tool keys on `tools` instead. Kept for backward compat. */
 export type BuiltInToolToggles = {

package/src/harness.ts

@@ -20,7 +20,7 @@ const costLog = createLogger("cost");
 const mcpLog = createLogger("mcp");
 const modelLog = createLogger("model");
 import type { UploadStore } from "./upload-store.js";
-import { PONCHO_UPLOAD_SCHEME, VFS_SCHEME, deriveUploadKey } from "./upload-store.js";
+import { PONCHO_UPLOAD_SCHEME, VFS_SCHEME, decodeFileInputData, deriveUploadKey } from "./upload-store.js";
 import type { StorageEngine } from "./storage/engine.js";
 import { createStorageEngine, type StorageProvider } from "./storage/index.js";
 import {
@@ -30,13 +30,15 @@ import {
   createReminderStoreFromEngine,
 } from "./storage/store-adapters.js";
 import { BashEnvironmentManager } from "./vfs/bash-manager.js";
+import type { VirtualMount } from "./vfs/poncho-fs-adapter.js";
+export type { VirtualMount } from "./vfs/poncho-fs-adapter.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 { loadPonchoConfig, normalizeToolAccess, resolveMemoryConfig, resolveStateConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
 import { ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
@@ -123,6 +125,15 @@ export interface HarnessOptions {
    * `resolveStateConfig`, etc.) run as today regardless of source.
    */
   config?: PonchoConfig;
+  /**
+   * Read-only virtual mounts overlaid on the VFS. Each mount maps a VFS
+   * prefix (e.g. "/system/") to a local filesystem directory; reads under
+   * the prefix are served from local disk, writes are rejected. Used by
+   * platforms like PonchOS to expose deployment-shipped defaults (system
+   * jobs, system skills) without storing them in each tenant's VFS.
+   * Empty by default — no system mounts in the CLI / dev workflow.
+   */
+  virtualMounts?: VirtualMount[];
 }
 
 export interface HarnessRunOutput {
@@ -855,6 +866,8 @@ export class AgentHarness {
   storageEngine?: StorageEngine;
   /** Bash environment manager (creates per-tenant bash instances). */
   private bashManager?: BashEnvironmentManager;
+  /** Read-only virtual mounts overlaid on the VFS. Empty by default. */
+  private virtualMounts: VirtualMount[] = [];
 
   private resolveToolAccess(toolName: string): ToolAccess {
     const tools = this.loadedConfig?.tools;
@@ -865,7 +878,17 @@ export class AgentHarness {
     if (envOverride !== undefined) return envOverride;
 
     const flatValue = tools[toolName];
-    if (typeof flatValue === "boolean" || flatValue === "approval") return flatValue;
+    if (
+      typeof flatValue === "boolean" ||
+      flatValue === "approval" ||
+      (flatValue !== null && typeof flatValue === "object" && !Array.isArray(flatValue) &&
+        // distinguish a ToolAccess object from the nested `defaults` /
+        // `byEnvironment` sibling fields by checking it has only the
+        // expected ToolAccess keys.
+        Object.keys(flatValue as object).every((k) => k === "access" || k === "dispatch"))
+    ) {
+      return flatValue as ToolAccess;
+    }
 
     const legacyValue = tools.defaults?.[toolName as keyof BuiltInToolToggles];
     if (legacyValue !== undefined) return legacyValue;
@@ -873,6 +896,11 @@ export class AgentHarness {
     return true;
   }
 
+  /** Returns the normalized {access, dispatch} mode for the tool. */
+  private resolveToolMode(toolName: string): { access?: "approval"; dispatch?: "device" } {
+    return normalizeToolAccess(this.resolveToolAccess(toolName));
+  }
+
   private isToolEnabled(name: string): boolean {
     const access = this.resolveToolAccess(name);
     if (access === false) return false;
@@ -1048,6 +1076,7 @@ export class AgentHarness {
       this.storageEngine = options.storageEngine;
       this.injectedStorageEngine = true;
     }
+    this.virtualMounts = options.virtualMounts ?? [];
 
     if (options.toolDefinitions?.length) {
       this.dispatcher.registerMany(options.toolDefinitions);
@@ -1255,6 +1284,21 @@ export class AgentHarness {
     // "__default__" so dev-mode (no auth) conversations see the same VFS
     // namespace the Files sidebar writes to.
     const effectiveTenant = tenantId || "__default__";
+    // Refresh the engine's path cache before fingerprinting. The cache is
+    // the only thing `computeVfsSkillFingerprint` reads, and historically
+    // it was only populated by `bash-manager.refreshPathCache` — chat-only
+    // flows (no bash) left it empty, the patched writeFile's incremental
+    // update became a no-op (it skips when the cache isn't loaded), the
+    // fingerprint stuck at "" across runs, and any skill the agent (or a
+    // client like PonchOS's iOS Files browser) authored after the harness
+    // was first instantiated was invisible from the next turn onward.
+    // One SELECT per turn is the cost of correctness here.
+    const engineWithRefresh = this.storageEngine as unknown as {
+      refreshPathCache?: (tenantId: string) => Promise<void>;
+    };
+    if (typeof engineWithRefresh.refreshPathCache === "function") {
+      await engineWithRefresh.refreshPathCache(effectiveTenant);
+    }
     const fingerprint = this.computeVfsSkillFingerprint(effectiveTenant);
     const cached = this.skillCache.get(effectiveTenant);
     if (cached && cached.fingerprint === fingerprint) {
@@ -1441,7 +1485,7 @@ export class AgentHarness {
     toolName: string,
     input: Record<string, unknown>,
   ): boolean {
-    if (this.resolveToolAccess(toolName) === "approval") {
+    if (this.resolveToolMode(toolName).access === "approval") {
       return true;
     }
     if (toolName === "run_skill_script") {
@@ -1695,6 +1739,7 @@ export class AgentHarness {
       bashWorkingDir,
       config?.bash,
       config?.network,
+      this.virtualMounts,
     );
     // Register VFS tools
     this.registerIfMissing(createBashTool(this.bashManager));
@@ -2256,7 +2301,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         ];
         for (const file of input.files) {
           if (this.uploadStore) {
-            const buf = Buffer.from(file.data, "base64");
+            const buf = await decodeFileInputData(file.data);
             const key = deriveUploadKey(buf, file.mediaType);
             const ref = await this.uploadStore.put(key, buf, file.mediaType);
             parts.push({
@@ -3089,8 +3134,19 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         name: string;
         input: Record<string, unknown>;
       }> = [];
+      const deviceNeeded: Array<{
+        approvalId: string;
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+      }> = [];
 
-      // Phase 1: classify all tool calls
+      // Phase 1: classify all tool calls.
+      // Approval gates run first; device dispatch fires only after approval is
+      // cleared. On a device+approval tool the first dispatch pass yields the
+      // approval, and the post-resume pass (where access is no longer required
+      // because the message stream has the approve decision baked in) sees
+      // dispatch="device" still set and falls into deviceNeeded below.
       for (const call of toolCalls) {
         if (isCancelled()) {
           yield emitCancellation();
@@ -3105,6 +3161,13 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
             name: runtimeToolName,
             input: call.input,
           });
+        } else if (this.resolveToolMode(runtimeToolName).dispatch === "device") {
+          deviceNeeded.push({
+            approvalId: `device_${randomUUID()}`,
+            id: call.id,
+            name: runtimeToolName,
+            input: call.input,
+          });
         } else {
           approvedCalls.push({
             id: call.id,
@@ -3157,6 +3220,52 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         return;
       }
 
+      // Phase 2a': if any tools must dispatch to a connected device, emit
+      // tool:device:required events for each and checkpoint with kind="device".
+      // Consumers (e.g. PonchOS) route the events to the right WS and POST
+      // the resulting tool output back through resumeRunFromCheckpoint.
+      if (deviceNeeded.length > 0) {
+        for (const dn of deviceNeeded) {
+          yield pushEvent({
+            type: "tool:device:required",
+            tool: dn.name,
+            input: dn.input,
+            requestId: dn.approvalId,
+          });
+        }
+
+        const assistantContent = JSON.stringify({
+          text: fullText,
+          tool_calls: toolCalls.map(tc => ({
+            id: tc.id,
+            name: exposedToolNames.get(tc.name) ?? tc.name,
+            input: tc.input,
+          })),
+        });
+        const assistantMsg: Message = {
+          role: "assistant",
+          content: assistantContent,
+          metadata: { timestamp: now(), id: randomUUID(), step, runId },
+        };
+        const deltaMessages = [...messages.slice(inputMessageCount), assistantMsg];
+        yield pushEvent({
+          type: "tool:device:checkpoint",
+          approvals: deviceNeeded.map(dn => ({
+            approvalId: dn.approvalId,
+            tool: dn.name,
+            toolCallId: dn.id,
+            input: dn.input,
+          })),
+          checkpointMessages: deltaMessages,
+          pendingToolCalls: toolCalls.map(tc => ({
+            id: tc.id,
+            name: exposedToolNames.get(tc.name) ?? tc.name,
+            input: tc.input,
+          })),
+        });
+        return;
+      }
+
       // Phase 2b: no approvals needed — execute all auto-approved calls
       const batchStart = now();
       if (isCancelled()) {

package/src/index.ts

@@ -21,7 +21,7 @@ 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 { PonchoFsAdapter, type VirtualMount } 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";

package/src/orchestrator/orchestrator.ts

@@ -1511,6 +1511,52 @@ export class AgentOrchestrator {
         }
         return results;
       },
+
+      getTranscript: async (opts) => {
+        const conversation = await this.conversationStore.get(opts.subagentId);
+        if (!conversation) {
+          throw new Error(`Subagent "${opts.subagentId}" not found.`);
+        }
+        if (!conversation.parentConversationId) {
+          throw new Error(`Conversation "${opts.subagentId}" is not a subagent.`);
+        }
+        if (conversation.parentConversationId !== opts.parentConversationId) {
+          throw new Error(`Subagent "${opts.subagentId}" was not spawned by this conversation.`);
+        }
+
+        const all = conversation.messages;
+        let filtered: Message[];
+        if (opts.mode === "final") {
+          let lastAssistant: Message | undefined;
+          for (let i = all.length - 1; i >= 0; i--) {
+            if (all[i]!.role === "assistant") {
+              lastAssistant = all[i];
+              break;
+            }
+          }
+          filtered = lastAssistant ? [lastAssistant] : [];
+        } else if (opts.mode === "assistant") {
+          filtered = all.filter((m) => m.role === "assistant");
+        } else {
+          filtered = all;
+        }
+
+        const startIndex = Math.max(0, opts.sinceIndex ?? 0);
+        const sliced = filtered.slice(startIndex);
+        const cap = opts.maxMessages !== undefined && opts.maxMessages >= 0 ? opts.maxMessages : sliced.length;
+        const messages = sliced.slice(0, cap);
+        const truncated = startIndex + messages.length < filtered.length;
+
+        return {
+          subagentId: conversation.conversationId,
+          task: conversation.subagentMeta?.task ?? conversation.title,
+          status: conversation.subagentMeta?.status ?? "stopped",
+          totalMessages: filtered.length,
+          startIndex,
+          messages,
+          truncated,
+        };
+      },
     };
   }
 

package/src/orchestrator/run-conversation-turn.ts

@@ -24,7 +24,7 @@ import type { AgentEvent, FileInput, Message } from "@poncho-ai/sdk";
 import { createLogger } from "@poncho-ai/sdk";
 import type { AgentHarness } from "../harness.js";
 import type { ConversationStore } from "../state.js";
-import { deriveUploadKey } from "../upload-store.js";
+import { decodeFileInputData, deriveUploadKey } from "../upload-store.js";
 import { withToolResultArchiveParam } from "./continuation.js";
 import { resolveRunRequest } from "./history.js";
 import {
@@ -104,7 +104,7 @@ export const runConversationTurn = async (
   if (opts.files && opts.files.length > 0 && opts.harness.uploadStore) {
     const uploadedParts = await Promise.all(
       opts.files.map(async (f) => {
-        const buf = Buffer.from(f.data, "base64");
+        const buf = await decodeFileInputData(f.data);
         const key = deriveUploadKey(buf, f.mediaType);
         const ref = await opts.harness.uploadStore!.put(key, buf, f.mediaType);
         return {
@@ -257,6 +257,34 @@ export const runConversationTurn = async (
                 checkpointMessages: undefined,
                 baseMessageCount: historyMessages.length,
                 pendingToolCalls: [],
+                kind: "approval",
+              },
+            ];
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+          await persistDraft();
+        }
+        if (event.type === "tool:device:required") {
+          const toolText = `- device dispatch \`${event.tool}\``;
+          draft.toolTimeline.push(toolText);
+          draft.currentTools.push(toolText);
+          const existing = Array.isArray(conversation.pendingApprovals)
+            ? conversation.pendingApprovals
+            : [];
+          if (!existing.some((a) => a.approvalId === event.requestId)) {
+            conversation.pendingApprovals = [
+              ...existing,
+              {
+                approvalId: event.requestId,
+                runId: latestRunId || conversation.runtimeRunId || "",
+                tool: event.tool,
+                toolCallId: undefined,
+                input: (event.input ?? {}) as Record<string, unknown>,
+                checkpointMessages: undefined,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: [],
+                kind: "device",
               },
             ];
             conversation.updatedAt = Date.now();
@@ -272,6 +300,24 @@ export const runConversationTurn = async (
             checkpointMessages: event.checkpointMessages,
             baseMessageCount: historyMessages.length,
             pendingToolCalls: event.pendingToolCalls,
+            kind: "approval",
+          });
+          conversation._toolResultArchive = opts.harness.getToolResultArchive(
+            opts.conversationId,
+          );
+          conversation.updatedAt = Date.now();
+          await opts.conversationStore.update(conversation);
+          checkpointedRun = true;
+        }
+        if (event.type === "tool:device:checkpoint") {
+          conversation.messages = buildMessages();
+          conversation.pendingApprovals = buildApprovalCheckpoints({
+            approvals: event.approvals,
+            runId: latestRunId,
+            checkpointMessages: event.checkpointMessages,
+            baseMessageCount: historyMessages.length,
+            pendingToolCalls: event.pendingToolCalls,
+            kind: "device",
           });
           conversation._toolResultArchive = opts.harness.getToolResultArchive(
             opts.conversationId,

package/src/orchestrator/turn.ts

@@ -304,12 +304,14 @@ export const buildApprovalCheckpoints = ({
   checkpointMessages,
   baseMessageCount,
   pendingToolCalls,
+  kind = "approval",
 }: {
   approvals: ApprovalEventItem[];
   runId: string;
   checkpointMessages: Message[];
   baseMessageCount: number;
   pendingToolCalls: PendingToolCall[];
+  kind?: "approval" | "device";
 }): NonNullable<Conversation["pendingApprovals"]> =>
   approvals.map((approval) => ({
     approvalId: approval.approvalId,
@@ -320,6 +322,7 @@ export const buildApprovalCheckpoints = ({
     checkpointMessages,
     baseMessageCount,
     pendingToolCalls,
+    kind,
   }));
 
 // ── Turn metadata persistence ──

package/src/state.ts

@@ -47,6 +47,15 @@ export interface Conversation {
     baseMessageCount?: number;
     pendingToolCalls?: Array<{ id: string; name: string; input: Record<string, unknown> }>;
     decision?: "approved" | "denied";
+    /**
+     * Checkpoint kind discriminator.
+     * - "approval" (default for legacy rows): user approve/deny gate.
+     * - "device":   tool executes on a connected client device (e.g. iOS); the
+     *               consumer of the harness POSTs a tool result back to resume.
+     * Treat `undefined` as "approval" for backward compatibility with rows
+     * persisted before this field existed.
+     */
+    kind?: "approval" | "device";
   }>;
   runStatus?: "running" | "idle";
   ownerId: string;

package/src/storage/schema.ts

@@ -195,4 +195,23 @@ export const migrations: Migration[] = [
          WHERE parent_message_id IS NOT NULL`,
     ],
   },
+  {
+    version: 7,
+    name: "fix_reminder_scheduled_at_precision",
+    // Postgres maps `REAL` to float4 (4 bytes, ~7 digit precision),
+    // which silently rounds millisecond epochs (13 digits) — every
+    // reminder write+read on Postgres returned a different value than
+    // it stored. SQLite's REAL is float8 (15+ digit precision) so it
+    // was always fine there.
+    //
+    // Convert the Postgres column to BIGINT so future writes are exact
+    // (already-stored rounded values aren't recoverable but they were
+    // never correct in the first place).
+    up: (d) => {
+      if (d === "sqlite") return [];
+      return [
+        `ALTER TABLE reminders ALTER COLUMN scheduled_at TYPE BIGINT USING scheduled_at::bigint`,
+      ];
+    },
+  },
 ];

package/src/storage/sql-dialect.ts

@@ -1195,7 +1195,10 @@ export abstract class SqlStorageEngine implements StorageEngine {
     return {
       id: row.id as string,
       task: row.task as string,
-      scheduledAt: row.scheduled_at as number,
+      // Postgres-js returns BIGINT columns as strings to avoid silent
+      // precision loss in JS. Coerce to Number — ms epochs max out at
+      // ~10^16 in year 2286, well under Number.MAX_SAFE_INTEGER (2^53).
+      scheduledAt: Number(row.scheduled_at),
       timezone: (row.timezone as string) ?? undefined,
       status: row.status as Reminder["status"],
       createdAt: new Date(row.created_at as string).getTime(),
@@ -1203,7 +1206,7 @@ export abstract class SqlStorageEngine implements StorageEngine {
       ownerId: (row.owner_id as string) ?? undefined,
       tenantId: tid === DEFAULT_TENANT ? null : tid,
       recurrence,
-      occurrenceCount: (row.occurrence_count as number) ?? 0,
+      occurrenceCount: Number(row.occurrence_count ?? 0),
     };
   }
 

package/src/subagent-manager.ts

@@ -19,6 +19,18 @@ export interface SubagentSpawnResult {
   subagentId: string;
 }
 
+export type SubagentTranscriptMode = "final" | "assistant" | "full";
+
+export interface SubagentTranscript {
+  subagentId: string;
+  task: string;
+  status: string;
+  totalMessages: number;
+  startIndex: number;
+  messages: Message[];
+  truncated: boolean;
+}
+
 export interface SubagentManager {
   spawn(opts: {
     task: string;
@@ -32,4 +44,12 @@ export interface SubagentManager {
   stop(subagentId: string): Promise<void>;
 
   list(parentConversationId: string): Promise<SubagentSummary[]>;
+
+  getTranscript(opts: {
+    subagentId: string;
+    parentConversationId: string;
+    mode: SubagentTranscriptMode;
+    sinceIndex?: number;
+    maxMessages?: number;
+  }): Promise<SubagentTranscript>;
 }

package/src/subagent-tools.ts

@@ -131,4 +131,66 @@ export const createSubagentTools = (
       return { subagents };
     },
   }),
+
+  defineTool({
+    name: "read_subagent",
+    description:
+      "Fetch the conversation transcript of a subagent you spawned. Use this to inspect a " +
+      "subagent's intermediate reasoning, tool calls, or full output -- instead of asking it " +
+      "to repeat its work via message_subagent.\n\n" +
+      "Modes:\n" +
+      "- 'final' (default): just the last assistant message. Cheap.\n" +
+      "- 'assistant': all assistant messages, no tool calls/results.\n" +
+      "- 'full': every message including tool calls and results. Can be large.\n\n" +
+      "Use since_index / max_messages to page through long transcripts. Only works on " +
+      "subagents directly spawned by this conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagent_id: {
+          type: "string",
+          description: "The subagent ID (from spawn_subagent or list_subagents).",
+        },
+        mode: {
+          type: "string",
+          enum: ["final", "assistant", "full"],
+          description: "How much of the transcript to return. Defaults to 'final'.",
+        },
+        since_index: {
+          type: "number",
+          description: "Skip messages before this index (applied after mode filter).",
+        },
+        max_messages: {
+          type: "number",
+          description: "Cap the number of messages returned.",
+        },
+      },
+      required: ["subagent_id"],
+      additionalProperties: false,
+    },
+    handler: async (input: Record<string, unknown>, context: ToolContext) => {
+      const subagentId = typeof input.subagent_id === "string" ? input.subagent_id : "";
+      if (!subagentId) {
+        return { error: "subagent_id is required" };
+      }
+      const parentConversationId = context.conversationId;
+      if (!parentConversationId) {
+        return { error: "no active conversation" };
+      }
+      const rawMode = typeof input.mode === "string" ? input.mode : "final";
+      const mode: "final" | "assistant" | "full" =
+        rawMode === "assistant" || rawMode === "full" ? rawMode : "final";
+      try {
+        return await manager.getTranscript({
+          subagentId,
+          parentConversationId,
+          mode,
+          sinceIndex: typeof input.since_index === "number" ? input.since_index : undefined,
+          maxMessages: typeof input.max_messages === "number" ? input.max_messages : undefined,
+        });
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  }),
 ];

package/src/upload-store.ts

@@ -108,6 +108,33 @@ export const deriveUploadKey = (
   return `${hash}${ext}`;
 };
 
+const DATA_URI_PREFIX = /^data:[^,]*?;base64,/;
+
+/**
+ * Decode the `FileInput.data` field per its documented contract: it may be a
+ * raw base64 string, a `data:<mime>;base64,<…>` URI, or an `https?://` URL.
+ * Returns the decoded bytes. Older versions of the harness called
+ * `Buffer.from(data, "base64")` unconditionally; that silently produced
+ * garbage bytes for data URIs (the `:` / `;` / `,` in the prefix are not
+ * valid base64 chars but Node's decoder ignores them rather than throwing).
+ */
+export const decodeFileInputData = async (data: string): Promise<Buffer> => {
+  if (data.startsWith("http://") || data.startsWith("https://")) {
+    const resp = await fetch(data);
+    if (!resp.ok) {
+      throw new Error(
+        `uploads: failed to fetch file at ${data}: ${resp.status} ${resp.statusText}`,
+      );
+    }
+    return Buffer.from(await resp.arrayBuffer());
+  }
+  const match = data.match(DATA_URI_PREFIX);
+  if (match) {
+    return Buffer.from(data.slice(match[0].length), "base64");
+  }
+  return Buffer.from(data, "base64");
+};
+
 const MIME_EXT_MAP: Record<string, string> = {
   "image/jpeg": ".jpg",
   "image/png": ".png",

package/src/vfs/bash-manager.ts

@@ -11,7 +11,7 @@ import type {
 } from "just-bash";
 import type { StorageEngine } from "../storage/engine.js";
 import type { BashConfig, NetworkConfig } from "../config.js";
-import { PonchoFsAdapter } from "./poncho-fs-adapter.js";
+import { PonchoFsAdapter, type VirtualMount } from "./poncho-fs-adapter.js";
 import { createBashFs } from "./create-bash-fs.js";
 import type { PostgresEngine } from "../storage/postgres-engine.js";
 
@@ -69,6 +69,7 @@ export class BashEnvironmentManager {
   private filesystems = new Map<string, IFileSystem>();
   private readonly workingDir: string | null;
   private readonly bashOptions: Partial<BashOptions>;
+  private readonly virtualMounts: VirtualMount[];
 
   constructor(
     private engine: StorageEngine,
@@ -76,16 +77,18 @@ export class BashEnvironmentManager {
     workingDir: string | null,
     bashConfig?: BashConfig,
     network?: NetworkConfig,
+    virtualMounts: VirtualMount[] = [],
   ) {
     this.workingDir = workingDir;
     this.bashOptions = toBashOptions(bashConfig, network);
+    this.virtualMounts = virtualMounts;
   }
 
   /** Return the combined IFileSystem (VFS + optional /project mount) for a tenant. */
   getFs(tenantId: string): IFileSystem {
     let fs = this.filesystems.get(tenantId);
     if (!fs) {
-      const adapter = new PonchoFsAdapter(this.engine, tenantId, this.limits);
+      const adapter = new PonchoFsAdapter(this.engine, tenantId, this.limits, this.virtualMounts);
       fs = createBashFs(adapter, this.workingDir);
       this.filesystems.set(tenantId, fs);
     }
@@ -107,7 +110,7 @@ export class BashEnvironmentManager {
   }
 
   getAdapter(tenantId: string): PonchoFsAdapter {
-    return new PonchoFsAdapter(this.engine, tenantId, this.limits);
+    return new PonchoFsAdapter(this.engine, tenantId, this.limits, this.virtualMounts);
   }
 
   /** Refresh the PostgreSQL path cache before a bash.exec() call. */