@poncho-ai/harness 0.49.0 → 0.50.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.49.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.50.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM dist/index.js            528.58 KB
-ESM ⚡️ Build success in 197ms
+ESM dist/index.js            530.75 KB
+ESM dist/isolate-BNQ6P3HI.js 51.41 KB
+ESM ⚡️ Build success in 224ms
 DTS Build start
-DTS ⚡️ Build success in 5685ms
-DTS dist/index.d.ts 87.88 KB
+DTS ⚡️ Build success in 6878ms
+DTS dist/index.d.ts 89.28 KB

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @poncho-ai/harness
 
+## 0.50.1
+
+### Patch Changes
+
+- [#131](https://github.com/cesr/poncho-ai/pull/131) [`9e0ccd8`](https://github.com/cesr/poncho-ai/commit/9e0ccd8307ab056f94b7efc3e25a0cb71ee75625) Thanks [@cesr](https://github.com/cesr)! - harness: strip `poncho-upload://` scheme in `S3UploadStore.get` / `.delete`
+
+  `createUploadStore({ provider: "s3" })` wraps `S3UploadStore` in
+  `CachedUploadStore`, whose `put` returns a `poncho-upload://<key>` ref
+  and stores the underlying S3 object at the bare `<key>`. On read,
+  `CachedUploadStore.get` checks an in-memory cache (10-minute TTL); on
+  miss it falls through to `S3UploadStore.get(<ref>)`. Pre-fix, the S3
+  store treated the scheme-prefixed ref as a literal S3 key and hit the
+  backend with `poncho-upload://<key>` — guaranteed `NoSuchKey`.
+
+  In practice this meant a chat message with an attached image worked on
+  the turn it was uploaded (cache hit) and then started showing as
+  "[Attached file: … — file is no longer available]" on every follow-up
+  turn ~10 minutes later (cache miss → S3 NoSuchKey → outer catch in the
+  harness resolver). The same path worked for the local-fs store, which
+  strips the scheme in both `get` and `delete`.
+
+  `S3UploadStore.get` now strips the scheme before issuing
+  `GetObjectCommand`. `S3UploadStore.delete` already stripped `https://`
+  and now strips `poncho-upload://` too.
+
+## 0.50.0
+
+### Minor Changes
+
+- [#129](https://github.com/cesr/poncho-ai/pull/129) [`85b8eec`](https://github.com/cesr/poncho-ai/commit/85b8eeca593b1043e2f7da01d681db6d32b1a969) Thanks [@cesr](https://github.com/cesr)! - harness: provider-backed VFS mounts + binary fetch bodies
+
+  Two additive isolate/VFS changes.
+
+  **`MountProvider` for `VirtualMount`.** A virtual mount can now be backed
+  by a custom data source instead of a local-disk directory. Set
+  `provider: { readdir, stat, readFileBuffer }` instead of `source` on a
+  `VirtualMount`. The adapter routes read operations through the provider
+  and rejects writes the same way it does for disk-backed mounts. Lets a
+  host expose database rows / object-store keys as a VFS subtree without
+  materialising them on disk (e.g. PonchOS exposing user uploads at
+  `/uploads`). `getAllPaths` advertises only the mount root for provider
+  mounts (deep listing would require sync IO over a remote backend);
+  shallow listing is sufficient for bash glob/find at the mount root.
+
+  **Binary `fetch()` bodies in `run_code`.** The isolate fetch polyfill
+  used to coerce `init.body` to a string before sending it to the
+  `__poncho_fetch` binding, so passing a `Uint8Array`, `ArrayBuffer`, or
+  `Blob` arrived server-side as `"1,2,3,..."` — every binary upload
+  (image-edit APIs, file uploads) was corrupted. The polyfill now
+  base64-encodes binary bodies with a new `bodyEncoding: "base64"` field
+  on the binding input; the built-in `createFetchBinding` decodes back to
+  raw bytes before fetching. Custom bindings that replace `__poncho_fetch`
+  should add the same decoding (cf. PonchOS `createSecretAwareFetchBinding`).
+  String bodies are unchanged.
+
 ## 0.49.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { LanguageModel } from 'ai';
 import * as _poncho_ai_sdk from '@poncho-ai/sdk';
 import { Message, ToolContext, ToolDefinition, JsonSchema, RunResult, AgentFailure, RunInput, AgentEvent, FileInput } from '@poncho-ai/sdk';
 export { ToolDefinition, defineTool } from '@poncho-ai/sdk';
-import { IFileSystem, BufferEncoding, FsStat, FileContent, MkdirOptions, RmOptions, CpOptions, Bash } from 'just-bash';
+import { FsStat, IFileSystem, BufferEncoding, FileContent, MkdirOptions, RmOptions, CpOptions, Bash } from 'just-bash';
 import { z } from 'zod';
 
 interface AgentModelConfig {
@@ -977,9 +977,34 @@ interface StorageEngine {
 }
 
 /**
- * Read-only virtual mount mapping a VFS path prefix to a local filesystem
- * directory. All read operations under the prefix resolve via local FS;
- * writes throw. The prefix is normalised internally to end with "/".
+ * Read-only data source for a virtual mount whose contents don't live on
+ * local disk. Lets a host (e.g. PonchOS) back a VFS prefix with a database
+ * row set, object-store keys, or anything else expressible as
+ * `(tenantId, relative) -> bytes/listing/stat`.
+ *
+ * All three methods are read-only; writes through the adapter still throw
+ * `EROFS` for routed mounts the same way disk-backed mounts do (see
+ * `routeToMount` checks in writeFile/mkdir/rm/cp/mv/chmod/utimes/symlink/link).
+ * `relative` is the path within the mount; `""` means the mount root.
+ */
+interface MountProvider {
+    /** List entries directly under `relative`. The mount root is `""`. */
+    readdir(tenantId: string, relative: string): Promise<Array<{
+        name: string;
+        isFile: boolean;
+        isDirectory: boolean;
+    }>>;
+    /** Stat a single entry. Throw ENOENT-like for missing paths. */
+    stat(tenantId: string, relative: string): Promise<FsStat>;
+    /** Read raw bytes for a file entry. */
+    readFileBuffer(tenantId: string, relative: string): Promise<Uint8Array>;
+}
+/**
+ * Read-only virtual mount mapping a VFS path prefix to either a local
+ * filesystem directory (`source`) OR a custom provider (`provider`).
+ * Exactly one of the two must be set. All read operations under the prefix
+ * resolve via the chosen backend; writes throw. The prefix is normalised
+ * internally to end with "/".
  */
 interface VirtualMount {
     /** VFS prefix, e.g. "/system/". Leading slash required; trailing slash
@@ -987,7 +1012,11 @@ interface VirtualMount {
      *  but no validation is enforced here. */
     prefix: string;
     /** Absolute local FS path to serve from, e.g. "/srv/poncho/system". */
-    source: string;
+    source?: string;
+    /** Custom backend serving reads for this mount. Mutually exclusive with
+     *  `source` — set exactly one. Use when the data doesn't live on local
+     *  disk (e.g. database-backed upload listings). */
+    provider?: MountProvider;
 }
 declare class PonchoFsAdapter implements IFileSystem {
     private engine;
@@ -2109,4 +2138,4 @@ interface RunConversationTurnResult {
 }
 declare const runConversationTurn: (opts: RunConversationTurnOpts) => Promise<RunConversationTurnResult>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -2612,16 +2612,17 @@ var S3UploadStore = class {
       }
       return Buffer.from(await response.arrayBuffer());
     }
+    const key = urlOrKey.startsWith(PONCHO_UPLOAD_SCHEME) ? urlOrKey.slice(PONCHO_UPLOAD_SCHEME.length) : urlOrKey;
     await this.ensureClient();
     const result = await this.client.send(
-      new this.s3Sdk.GetObjectCommand({ Bucket: this.bucket, Key: urlOrKey })
+      new this.s3Sdk.GetObjectCommand({ Bucket: this.bucket, Key: key })
     );
-    if (!result.Body) throw new Error(`uploads: empty body for S3 key ${urlOrKey}`);
+    if (!result.Body) throw new Error(`uploads: empty body for S3 key ${key}`);
     return Buffer.from(await result.Body.transformToByteArray());
   }
   async delete(urlOrKey) {
     await this.ensureClient();
-    const key = urlOrKey.startsWith("https://") ? new URL(urlOrKey).pathname.slice(1) : urlOrKey;
+    const key = urlOrKey.startsWith("https://") ? new URL(urlOrKey).pathname.slice(1) : urlOrKey.startsWith(PONCHO_UPLOAD_SCHEME) ? urlOrKey.slice(PONCHO_UPLOAD_SCHEME.length) : urlOrKey;
     await this.client.send(
       new this.s3Sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key })
     );
@@ -4691,10 +4692,18 @@ var PonchoFsAdapter = class {
     this.limits = limits;
     this.mounts = mounts.map((m) => {
       const prefix = m.prefix.endsWith("/") ? m.prefix : m.prefix + "/";
+      const hasSource = typeof m.source === "string";
+      const hasProvider = m.provider != null;
+      if (hasSource === hasProvider) {
+        throw new Error(
+          `VirtualMount '${m.prefix}': set exactly one of 'source' or 'provider'`
+        );
+      }
       return {
         prefix,
         prefixNoSlash: prefix.slice(0, -1),
-        source: m.source.replace(/\/+$/, "")
+        source: hasSource ? m.source.replace(/\/+$/, "") : void 0,
+        provider: m.provider
       };
     });
   }
@@ -4757,6 +4766,10 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const buf3 = await route.mount.provider.readFileBuffer(this.tenantId, route.relative);
+        return new TextDecoder().decode(buf3);
+      }
       const buf2 = await nodeFs.readFile(this.toLocal(route.mount, route.relative));
       return buf2.toString("utf8");
     }
@@ -4767,6 +4780,9 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        return route.mount.provider.readFileBuffer(this.tenantId, route.relative);
+      }
       const buf = await nodeFs.readFile(this.toLocal(route.mount, route.relative));
       return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     }
@@ -4776,6 +4792,14 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        try {
+          await route.mount.provider.stat(this.tenantId, route.relative);
+          return true;
+        } catch {
+          return false;
+        }
+      }
       try {
         await nodeFs.access(this.toLocal(route.mount, route.relative));
         return true;
@@ -4791,6 +4815,13 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        try {
+          return await route.mount.provider.stat(this.tenantId, route.relative);
+        } catch {
+          throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+        }
+      }
       try {
         const s2 = await nodeFs.stat(this.toLocal(route.mount, route.relative));
         return this.toFsStat(s2);
@@ -4816,6 +4847,10 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const entries = await route.mount.provider.readdir(this.tenantId, route.relative);
+        return entries.map((e) => e.name);
+      }
       return nodeFs.readdir(this.toLocal(route.mount, route.relative));
     }
     let engineNames = [];
@@ -4834,6 +4869,15 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const entries2 = await route.mount.provider.readdir(this.tenantId, route.relative);
+        return entries2.map((e) => ({
+          name: e.name,
+          isFile: e.isFile,
+          isDirectory: e.isDirectory,
+          isSymbolicLink: false
+        }));
+      }
       const entries = await nodeFs.readdir(this.toLocal(route.mount, route.relative), { withFileTypes: true });
       return entries.map((e) => ({
         name: e.name,
@@ -4939,8 +4983,12 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        return np;
+      }
       const localResolved = await nodeFs.realpath(this.toLocal(route.mount, route.relative));
-      const localRoot = await nodeFs.realpath(route.mount.source).catch(() => route.mount.source);
+      const source = route.mount.source;
+      const localRoot = await nodeFs.realpath(source).catch(() => source);
       if (localResolved === localRoot) return route.mount.prefixNoSlash;
       if (localResolved.startsWith(localRoot + nodePath.sep)) {
         const rel = localResolved.slice(localRoot.length + 1).split(nodePath.sep).join("/");
@@ -4966,6 +5014,7 @@ var PonchoFsAdapter = class {
     const out = new Set(enginePaths);
     for (const m of this.mounts) {
       out.add(m.prefixNoSlash);
+      if (m.provider) continue;
       try {
         const stack = [
           { abs: m.source, vfs: m.prefixNoSlash }
@@ -5019,6 +5068,9 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        throw new Error(`EINVAL: not a symbolic link, readlink '${path}'`);
+      }
       return nodeFs.readlink(this.toLocal(route.mount, route.relative));
     }
     return this.engine.vfs.readlink(this.tenantId, np);
@@ -5027,6 +5079,13 @@ var PonchoFsAdapter = class {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        try {
+          return await route.mount.provider.stat(this.tenantId, route.relative);
+        } catch {
+          throw new Error(`ENOENT: no such file or directory, lstat '${path}'`);
+        }
+      }
       try {
         const s2 = await nodeFs.lstat(this.toLocal(route.mount, route.relative));
         return this.toFsStat(s2);
@@ -9892,7 +9951,7 @@ var AgentHarness = class _AgentHarness {
     this.registerIfMissing(createEditFileTool(getFs));
     this.registerIfMissing(createWriteFileTool(getFs));
     if (config?.isolate) {
-      const { createRunCodeTool, buildRunCodeDescription, bundleLibraries } = await import("./isolate-VY35DGLM.js");
+      const { createRunCodeTool, buildRunCodeDescription, bundleLibraries } = await import("./isolate-BNQ6P3HI.js");
       let libraryPreamble = null;
       if (config.isolate.libraries?.length) {
         libraryPreamble = await bundleLibraries(config.isolate.libraries, this.workingDir);
@@ -10268,7 +10327,7 @@ Examples:${this.environment !== "production" ? `
 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.` : "";
     let isolateContext = "";
     if (this.loadedConfig?.isolate && this.dispatcher.get("run_code")) {
-      const { generateIsolateTypeStubs } = await import("./isolate-VY35DGLM.js");
+      const { generateIsolateTypeStubs } = await import("./isolate-BNQ6P3HI.js");
       const typeStubs = generateIsolateTypeStubs(this.loadedConfig.isolate);
       isolateContext = `
 

package/dist/{isolate-VY35DGLM.js → isolate-BNQ6P3HI.js}

@@ -324,6 +324,11 @@ function createFetchBinding(allowedDomains, network) {
         method: { type: "string" },
         headers: { type: "object", additionalProperties: { type: "string" } },
         body: { type: "string" },
+        // "base64" => `body` is base64-encoded raw bytes. The polyfill sets
+        // this when init.body is a Uint8Array/ArrayBuffer/Blob, so binary
+        // uploads (image-edit APIs, file uploads) reach the server intact
+        // instead of being mangled by String(...) coercion.
+        bodyEncoding: { type: "string", enum: ["base64"] },
         binary: { type: "boolean" }
       },
       required: ["url"]
@@ -335,10 +340,14 @@ function createFetchBinding(allowedDomains, network) {
           `Fetch blocked: domain "${url.hostname}" is not in the allowed list [${allowedDomains.join(", ")}]`
         );
       }
+      const rawBody = input.body;
+      const reqBody = rawBody !== void 0 && input.bodyEncoding === "base64" ? new Uint8Array(Buffer.from(rawBody, "base64")) : rawBody;
       const resp = await fetch(input.url, {
         method: input.method ?? "GET",
         headers: input.headers ?? void 0,
-        body: input.body ?? void 0,
+        // Cast: Node's undici fetch accepts Uint8Array at runtime, but the
+        // BodyInit type in this lib version doesn't list it.
+        body: reqBody,
         redirect: "follow"
       });
       const headers = {};
@@ -846,6 +855,36 @@ var POLYFILL_FETCH = `
     return arr;
   }
 
+  function _fetchUint8ToB64(u8) {
+    let bin = "";
+    for (let i = 0; i < u8.length; i++) bin += String.fromCharCode(u8[i]);
+    return btoa(bin);
+  }
+
+  // Normalise the init.body into { body, bodyEncoding } the binding accepts.
+  // Strings go through as text. Binary inputs (Uint8Array / ArrayBuffer /
+  // typed-array views / Blob) are base64-encoded with bodyEncoding="base64"
+  // so the host decodes back to the exact bytes before fetch() \u2014 without
+  // this branch, String(uint8Array) gave "1,2,3,..." and corrupted every
+  // binary upload (image-edit APIs, file uploads, etc.).
+  function _fetchEncodeBody(raw) {
+    if (raw == null) return { body: undefined };
+    if (typeof raw === "string") return { body: raw };
+    if (raw instanceof ArrayBuffer) {
+      return { body: _fetchUint8ToB64(new Uint8Array(raw)), bodyEncoding: "base64" };
+    }
+    if (ArrayBuffer.isView(raw)) {
+      const u8 = raw instanceof Uint8Array
+        ? raw
+        : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+      return { body: _fetchUint8ToB64(u8), bodyEncoding: "base64" };
+    }
+    if (typeof Blob !== "undefined" && raw instanceof Blob && raw._data) {
+      return { body: _fetchUint8ToB64(raw._data), bodyEncoding: "base64" };
+    }
+    return { body: String(raw) };
+  }
+
   globalThis.fetch = async function(input, init) {
     const url = typeof input === "string" ? input : (input?.url || String(input));
     const method = init?.method || "GET";
@@ -856,10 +895,17 @@ var POLYFILL_FETCH = `
         : Object.entries(init.headers);
       for (const [k, v] of entries) headers[k] = String(v);
     }
-    const body = init?.body ? String(init.body) : undefined;
+    const encoded = _fetchEncodeBody(init?.body);
 
     // Always fetch as binary to preserve data integrity
-    const result = await __poncho_fetch({ url, method, headers, body, binary: true });
+    const result = await __poncho_fetch({
+      url,
+      method,
+      headers,
+      body: encoded.body,
+      bodyEncoding: encoded.bodyEncoding,
+      binary: true,
+    });
     return new Response(result, true);
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.49.0",
+  "version": "0.50.1",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -21,7 +21,11 @@ export * from "./telemetry.js";
 export * from "./secrets-store.js";
 export * from "./storage/index.js";
 export * from "./storage/store-adapters.js";
-export { PonchoFsAdapter, type VirtualMount } from "./vfs/poncho-fs-adapter.js";
+export {
+  PonchoFsAdapter,
+  type VirtualMount,
+  type MountProvider,
+} 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/isolate/bindings.ts

@@ -161,6 +161,11 @@ export function createFetchBinding(
         method: { type: "string" },
         headers: { type: "object", additionalProperties: { type: "string" } },
         body: { type: "string" },
+        // "base64" => `body` is base64-encoded raw bytes. The polyfill sets
+        // this when init.body is a Uint8Array/ArrayBuffer/Blob, so binary
+        // uploads (image-edit APIs, file uploads) reach the server intact
+        // instead of being mangled by String(...) coercion.
+        bodyEncoding: { type: "string", enum: ["base64"] },
         binary: { type: "boolean" },
       },
       required: ["url"],
@@ -173,10 +178,18 @@ export function createFetchBinding(
         );
       }
 
+      const rawBody = input.body as string | undefined;
+      const reqBody: string | Uint8Array | undefined =
+        rawBody !== undefined && input.bodyEncoding === "base64"
+          ? new Uint8Array(Buffer.from(rawBody, "base64"))
+          : rawBody;
+
       const resp = await fetch(input.url as string, {
         method: (input.method as string) ?? "GET",
         headers: (input.headers as Record<string, string>) ?? undefined,
-        body: (input.body as string) ?? undefined,
+        // Cast: Node's undici fetch accepts Uint8Array at runtime, but the
+        // BodyInit type in this lib version doesn't list it.
+        body: reqBody as unknown as BodyInit | undefined,
         redirect: "follow",
       });
 

package/src/isolate/polyfills.ts

@@ -532,6 +532,36 @@ const POLYFILL_FETCH = `
     return arr;
   }
 
+  function _fetchUint8ToB64(u8) {
+    let bin = "";
+    for (let i = 0; i < u8.length; i++) bin += String.fromCharCode(u8[i]);
+    return btoa(bin);
+  }
+
+  // Normalise the init.body into { body, bodyEncoding } the binding accepts.
+  // Strings go through as text. Binary inputs (Uint8Array / ArrayBuffer /
+  // typed-array views / Blob) are base64-encoded with bodyEncoding="base64"
+  // so the host decodes back to the exact bytes before fetch() — without
+  // this branch, String(uint8Array) gave "1,2,3,..." and corrupted every
+  // binary upload (image-edit APIs, file uploads, etc.).
+  function _fetchEncodeBody(raw) {
+    if (raw == null) return { body: undefined };
+    if (typeof raw === "string") return { body: raw };
+    if (raw instanceof ArrayBuffer) {
+      return { body: _fetchUint8ToB64(new Uint8Array(raw)), bodyEncoding: "base64" };
+    }
+    if (ArrayBuffer.isView(raw)) {
+      const u8 = raw instanceof Uint8Array
+        ? raw
+        : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+      return { body: _fetchUint8ToB64(u8), bodyEncoding: "base64" };
+    }
+    if (typeof Blob !== "undefined" && raw instanceof Blob && raw._data) {
+      return { body: _fetchUint8ToB64(raw._data), bodyEncoding: "base64" };
+    }
+    return { body: String(raw) };
+  }
+
   globalThis.fetch = async function(input, init) {
     const url = typeof input === "string" ? input : (input?.url || String(input));
     const method = init?.method || "GET";
@@ -542,10 +572,17 @@ const POLYFILL_FETCH = `
         : Object.entries(init.headers);
       for (const [k, v] of entries) headers[k] = String(v);
     }
-    const body = init?.body ? String(init.body) : undefined;
+    const encoded = _fetchEncodeBody(init?.body);
 
     // Always fetch as binary to preserve data integrity
-    const result = await __poncho_fetch({ url, method, headers, body, binary: true });
+    const result = await __poncho_fetch({
+      url,
+      method,
+      headers,
+      body: encoded.body,
+      bodyEncoding: encoded.bodyEncoding,
+      binary: true,
+    });
     return new Response(result, true);
   };
 

package/src/upload-store.ts

@@ -349,11 +349,19 @@ export class S3UploadStore implements UploadStore {
       }
       return Buffer.from(await response.arrayBuffer());
     }
+    // Strip the `poncho-upload://` scheme — LocalUploadStore does this for
+    // both get/delete but S3 used to treat the full URI as a literal S3
+    // key, so resolving a persisted file part (data: "poncho-upload://…")
+    // on a follow-up turn 404'd against R2 and the harness emitted a
+    // "file is no longer available" placeholder.
+    const key = urlOrKey.startsWith(PONCHO_UPLOAD_SCHEME)
+      ? urlOrKey.slice(PONCHO_UPLOAD_SCHEME.length)
+      : urlOrKey;
     await this.ensureClient();
     const result = await this.client.send(
-      new this.s3Sdk.GetObjectCommand({ Bucket: this.bucket, Key: urlOrKey }),
+      new this.s3Sdk.GetObjectCommand({ Bucket: this.bucket, Key: key }),
     );
-    if (!result.Body) throw new Error(`uploads: empty body for S3 key ${urlOrKey}`);
+    if (!result.Body) throw new Error(`uploads: empty body for S3 key ${key}`);
     return Buffer.from(await result.Body.transformToByteArray());
   }
 
@@ -361,7 +369,9 @@ export class S3UploadStore implements UploadStore {
     await this.ensureClient();
     const key = urlOrKey.startsWith("https://")
       ? new URL(urlOrKey).pathname.slice(1)
-      : urlOrKey;
+      : urlOrKey.startsWith(PONCHO_UPLOAD_SCHEME)
+        ? urlOrKey.slice(PONCHO_UPLOAD_SCHEME.length)
+        : urlOrKey;
     await this.client.send(
       new this.s3Sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key }),
     );

package/src/vfs/poncho-fs-adapter.ts

@@ -85,9 +85,34 @@ const normalize = (path: string): string => {
 };
 
 /**
- * Read-only virtual mount mapping a VFS path prefix to a local filesystem
- * directory. All read operations under the prefix resolve via local FS;
- * writes throw. The prefix is normalised internally to end with "/".
+ * Read-only data source for a virtual mount whose contents don't live on
+ * local disk. Lets a host (e.g. PonchOS) back a VFS prefix with a database
+ * row set, object-store keys, or anything else expressible as
+ * `(tenantId, relative) -> bytes/listing/stat`.
+ *
+ * All three methods are read-only; writes through the adapter still throw
+ * `EROFS` for routed mounts the same way disk-backed mounts do (see
+ * `routeToMount` checks in writeFile/mkdir/rm/cp/mv/chmod/utimes/symlink/link).
+ * `relative` is the path within the mount; `""` means the mount root.
+ */
+export interface MountProvider {
+  /** List entries directly under `relative`. The mount root is `""`. */
+  readdir(
+    tenantId: string,
+    relative: string,
+  ): Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean }>>;
+  /** Stat a single entry. Throw ENOENT-like for missing paths. */
+  stat(tenantId: string, relative: string): Promise<FsStat>;
+  /** Read raw bytes for a file entry. */
+  readFileBuffer(tenantId: string, relative: string): Promise<Uint8Array>;
+}
+
+/**
+ * Read-only virtual mount mapping a VFS path prefix to either a local
+ * filesystem directory (`source`) OR a custom provider (`provider`).
+ * Exactly one of the two must be set. All read operations under the prefix
+ * resolve via the chosen backend; writes throw. The prefix is normalised
+ * internally to end with "/".
  */
 export interface VirtualMount {
   /** VFS prefix, e.g. "/system/". Leading slash required; trailing slash
@@ -95,15 +120,20 @@ export interface VirtualMount {
    *  but no validation is enforced here. */
   prefix: string;
   /** Absolute local FS path to serve from, e.g. "/srv/poncho/system". */
-  source: string;
+  source?: string;
+  /** Custom backend serving reads for this mount. Mutually exclusive with
+   *  `source` — set exactly one. Use when the data doesn't live on local
+   *  disk (e.g. database-backed upload listings). */
+  provider?: MountProvider;
 }
 
-/** Internal normalised form: prefix always ends with "/", source has no
- *  trailing slash. */
+/** Internal normalised form: prefix always ends with "/", source (when set)
+ *  has no trailing slash. Exactly one of source/provider is populated. */
 interface NormalisedMount {
   prefix: string;
   prefixNoSlash: string;
-  source: string;
+  source?: string;
+  provider?: MountProvider;
 }
 
 const READ_ONLY_ERROR = (path: string, op: string): Error =>
@@ -120,10 +150,18 @@ export class PonchoFsAdapter implements IFileSystem {
   ) {
     this.mounts = mounts.map((m) => {
       const prefix = m.prefix.endsWith("/") ? m.prefix : m.prefix + "/";
+      const hasSource = typeof m.source === "string";
+      const hasProvider = m.provider != null;
+      if (hasSource === hasProvider) {
+        throw new Error(
+          `VirtualMount '${m.prefix}': set exactly one of 'source' or 'provider'`,
+        );
+      }
       return {
         prefix,
         prefixNoSlash: prefix.slice(0, -1),
-        source: m.source.replace(/\/+$/, ""),
+        source: hasSource ? m.source!.replace(/\/+$/, "") : undefined,
+        provider: m.provider,
       };
     });
   }
@@ -157,8 +195,9 @@ export class PonchoFsAdapter implements IFileSystem {
   }
 
   private toLocal(mount: NormalisedMount, relative: string): string {
-    // nodePath.join handles empty relative -> source dir
-    return nodePath.join(mount.source, relative);
+    // Only callable for disk-backed mounts; provider mounts never call this.
+    // nodePath.join handles empty relative -> source dir.
+    return nodePath.join(mount.source!, relative);
   }
 
   /** Build an FsStat from a node fs.Stats. */
@@ -193,6 +232,10 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const buf = await route.mount.provider.readFileBuffer(this.tenantId, route.relative);
+        return new TextDecoder().decode(buf);
+      }
       const buf = await nodeFs.readFile(this.toLocal(route.mount, route.relative));
       return buf.toString("utf8");
     }
@@ -204,6 +247,9 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        return route.mount.provider.readFileBuffer(this.tenantId, route.relative);
+      }
       const buf = await nodeFs.readFile(this.toLocal(route.mount, route.relative));
       return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     }
@@ -214,6 +260,14 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        try {
+          await route.mount.provider.stat(this.tenantId, route.relative);
+          return true;
+        } catch {
+          return false;
+        }
+      }
       try {
         await nodeFs.access(this.toLocal(route.mount, route.relative));
         return true;
@@ -232,6 +286,13 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        try {
+          return await route.mount.provider.stat(this.tenantId, route.relative);
+        } catch {
+          throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+        }
+      }
       try {
         const s = await nodeFs.stat(this.toLocal(route.mount, route.relative));
         return this.toFsStat(s);
@@ -259,6 +320,10 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const entries = await route.mount.provider.readdir(this.tenantId, route.relative);
+        return entries.map((e) => e.name);
+      }
       return nodeFs.readdir(this.toLocal(route.mount, route.relative));
     }
     // Engine-backed read; also inject any mount-root segments whose parent
@@ -282,6 +347,15 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        const entries = await route.mount.provider.readdir(this.tenantId, route.relative);
+        return entries.map((e) => ({
+          name: e.name,
+          isFile: e.isFile,
+          isDirectory: e.isDirectory,
+          isSymbolicLink: false,
+        }));
+      }
       const entries = await nodeFs.readdir(this.toLocal(route.mount, route.relative), { withFileTypes: true });
       return entries.map((e) => ({
         name: e.name,
@@ -411,11 +485,17 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        // Provider mounts have no real disk path and don't support symlinks.
+        // The VFS path is its own canonical form.
+        return np;
+      }
       // Mount contents on local disk: resolve via node, but report back
       // in VFS-namespace terms (don't leak the on-disk source path to the
       // agent — that would be confusing and non-portable).
       const localResolved = await nodeFs.realpath(this.toLocal(route.mount, route.relative));
-      const localRoot = await nodeFs.realpath(route.mount.source).catch(() => route.mount.source);
+      const source = route.mount.source!;
+      const localRoot = await nodeFs.realpath(source).catch(() => source);
       if (localResolved === localRoot) return route.mount.prefixNoSlash;
       if (localResolved.startsWith(localRoot + nodePath.sep)) {
         const rel = localResolved.slice(localRoot.length + 1).split(nodePath.sep).join("/");
@@ -448,12 +528,16 @@ export class PonchoFsAdapter implements IFileSystem {
     for (const m of this.mounts) {
       // Always advertise the mount root itself as a directory.
       out.add(m.prefixNoSlash);
-      // Walk the local source once and add all paths under the mount.
+      // Provider mounts: deep listing would need async IO; advertise the
+      // mount root only. Bash glob/find over the mount falls back to a
+      // shallow listing — acceptable per the v1 spec (corner case).
+      if (m.provider) continue;
+      // Disk-backed mount: walk the local source once and add all paths.
       // Sync IO is acceptable here: bash glob/find call this sporadically and
       // the source is a small static asset directory on the API container.
       try {
         const stack: Array<{ abs: string; vfs: string }> = [
-          { abs: m.source, vfs: m.prefixNoSlash },
+          { abs: m.source!, vfs: m.prefixNoSlash },
         ];
         while (stack.length > 0) {
           const { abs, vfs } = stack.pop()!;
@@ -514,6 +598,9 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        throw new Error(`EINVAL: not a symbolic link, readlink '${path}'`);
+      }
       // Mount contents are real files; readlink only makes sense for symlinks
       // we don't expect to have on disk. Node will throw EINVAL for non-links.
       return nodeFs.readlink(this.toLocal(route.mount, route.relative));
@@ -525,6 +612,14 @@ export class PonchoFsAdapter implements IFileSystem {
     const np = normalize(path);
     const route = this.routeToMount(np);
     if (route) {
+      if (route.mount.provider) {
+        // Provider mounts can't host symlinks; lstat == stat.
+        try {
+          return await route.mount.provider.stat(this.tenantId, route.relative);
+        } catch {
+          throw new Error(`ENOENT: no such file or directory, lstat '${path}'`);
+        }
+      }
       try {
         const s = await nodeFs.lstat(this.toLocal(route.mount, route.relative));
         return this.toFsStat(s);