@poncho-ai/harness 0.35.0 → 0.36.1

package/src/isolate/bindings.ts

@@ -0,0 +1,206 @@
+// ---------------------------------------------------------------------------
+// Isolate Bindings – factory functions that create IsolateBinding objects
+// for VFS operations, scoped fetch, and builder custom bindings.
+//
+// All bindings use __poncho_ prefix to avoid colliding with the standard
+// API polyfills that wrap them (see polyfills.ts).
+// ---------------------------------------------------------------------------
+
+import type { IsolateBinding, IsolateConfig, NetworkConfig } from "../config.js";
+import type { PonchoFsAdapter } from "../vfs/poncho-fs-adapter.js";
+
+// ---------------------------------------------------------------------------
+// VFS bindings (created per-invocation with a tenant-scoped adapter)
+// ---------------------------------------------------------------------------
+
+export function createVfsBindings(
+  adapter: PonchoFsAdapter,
+): Record<string, IsolateBinding> {
+  return {
+    __poncho_fs_read: {
+      description: "Read a text file from the VFS",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        return await adapter.readFile(input.path as string);
+      },
+    },
+
+    __poncho_fs_write: {
+      description: "Write a text file to the VFS",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["path", "content"],
+      },
+      handler: async (input) => {
+        await adapter.writeFile(input.path as string, input.content as string);
+      },
+    },
+
+    __poncho_fs_read_binary: {
+      description: "Read a binary file (returns base64)",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        const buf = await adapter.readFileBuffer(input.path as string);
+        return Buffer.from(buf).toString("base64");
+      },
+    },
+
+    __poncho_fs_write_binary: {
+      description: "Write a binary file (content is base64)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["path", "content"],
+      },
+      handler: async (input) => {
+        const buf = Buffer.from(input.content as string, "base64");
+        await adapter.writeFile(input.path as string, buf);
+      },
+    },
+
+    __poncho_fs_list: {
+      description: "List directory entries",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        return await adapter.readdir(input.path as string);
+      },
+    },
+
+    __poncho_fs_exists: {
+      description: "Check if path exists",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        return await adapter.exists(input.path as string);
+      },
+    },
+
+    __poncho_fs_delete: {
+      description: "Delete a file or directory",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        await adapter.rm(input.path as string, { force: true });
+      },
+    },
+
+    __poncho_fs_mkdir: {
+      description: "Create a directory (recursive)",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        await adapter.mkdir(input.path as string, { recursive: true });
+      },
+    },
+
+    __poncho_fs_stat: {
+      description: "Get file metadata",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: async (input) => {
+        const stat = await adapter.stat(input.path as string);
+        return {
+          isFile: stat.isFile,
+          isDirectory: stat.isDirectory,
+          size: stat.size,
+          mtime: stat.mtime.toISOString(),
+        };
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scoped fetch binding (created once at registration time)
+// ---------------------------------------------------------------------------
+
+export function createFetchBinding(
+  allowedDomains: string[],
+  network?: NetworkConfig,
+): IsolateBinding {
+  const allowAll = network?.dangerouslyAllowAll === true;
+  const domainSet = new Set(allowedDomains.map((d) => d.toLowerCase()));
+
+  return {
+    description: "Internal fetch binding",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        method: { type: "string" },
+        headers: { type: "object", additionalProperties: { type: "string" } },
+        body: { type: "string" },
+        binary: { type: "boolean" },
+      },
+      required: ["url"],
+    },
+    handler: async (input) => {
+      const url = new URL(input.url as string);
+      if (!allowAll && !domainSet.has(url.hostname.toLowerCase())) {
+        throw new Error(
+          `Fetch blocked: domain "${url.hostname}" is not in the allowed list [${allowedDomains.join(", ")}]`,
+        );
+      }
+
+      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,
+        redirect: "follow",
+      });
+
+      const headers: Record<string, string> = {};
+      resp.headers.forEach((v, k) => { headers[k] = v; });
+
+      if (input.binary) {
+        const buf = await resp.arrayBuffer();
+        const base64 = Buffer.from(buf).toString("base64");
+        return { status: resp.status, statusText: resp.statusText, headers, body: base64, encoding: "base64" };
+      }
+
+      const body = await resp.text();
+      return { status: resp.status, statusText: resp.statusText, headers, body };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Builder custom bindings (adapt from config format)
+// ---------------------------------------------------------------------------
+
+export function mergeBuilderBindings(
+  configBindings: NonNullable<IsolateConfig["bindings"]>,
+): Record<string, IsolateBinding> {
+  return { ...configBindings };
+}

package/src/isolate/bundler.ts

@@ -0,0 +1,179 @@
+// ---------------------------------------------------------------------------
+// Library Bundler – esbuild-based npm library bundling with require() shim.
+//
+// Bundles each declared library into a self-contained IIFE, then generates
+// a module map + require() shim that the isolate can use.
+// ---------------------------------------------------------------------------
+
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Dynamic import
+// ---------------------------------------------------------------------------
+
+let esbuildBuild: typeof import("esbuild").build | undefined;
+
+async function loadEsbuild(): Promise<typeof import("esbuild").build> {
+  if (esbuildBuild) return esbuildBuild;
+  try {
+    const mod = await import("esbuild");
+    esbuildBuild = mod.build;
+    return esbuildBuild;
+  } catch {
+    throw new Error(
+      "Library bundling requires esbuild. Run: pnpm add esbuild",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Node built-in stubs
+// ---------------------------------------------------------------------------
+
+/** Node built-ins that we refuse to polyfill — they need real OS access. */
+const BLOCKED_BUILTINS = new Set([
+  "fs",
+  "fs/promises",
+  "net",
+  "tls",
+  "child_process",
+  "cluster",
+  "dgram",
+  "dns",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "os",
+  "perf_hooks",
+  "readline",
+  "repl",
+  "stream",
+  "tty",
+  "v8",
+  "vm",
+  "worker_threads",
+  "wasi",
+]);
+
+/**
+ * Build an esbuild plugin that stubs out blocked Node built-ins with a
+ * throw at import time, so libraries that depend on them fail clearly.
+ */
+function blockedBuiltinsPlugin(): import("esbuild").Plugin {
+  return {
+    name: "blocked-builtins",
+    setup(build) {
+      // Match bare specifiers and node: prefixed
+      const filter = new RegExp(
+        `^(node:)?(${[...BLOCKED_BUILTINS].join("|")})$`,
+      );
+      build.onResolve({ filter }, (args) => ({
+        path: args.path,
+        namespace: "blocked-builtin",
+      }));
+      build.onLoad(
+        { filter: /.*/, namespace: "blocked-builtin" },
+        (args) => {
+          const name = args.path.replace(/^node:/, "");
+          return {
+            contents: `throw new Error("Module '${name}' is not available in the isolate. Use the injected fs_* functions instead.");`,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Bundle the declared libraries into a single JS preamble string.
+ *
+ * Each library is bundled as an IIFE with `globalName: '__lib_<safeName>'`.
+ * The preamble ends with a module map and `require()` shim.
+ *
+ * @param libraries - npm package names declared in config
+ * @param projectDir - project root for resolving node_modules
+ * @returns Concatenated JS preamble, or null if no libraries
+ */
+export async function bundleLibraries(
+  libraries: string[],
+  projectDir: string,
+): Promise<string | null> {
+  if (libraries.length === 0) return null;
+
+  const build = await loadEsbuild();
+  const chunks: string[] = [];
+  const moduleEntries: string[] = [];
+
+  for (const lib of libraries) {
+    // Verify the library is installed
+    const pkgPath = resolve(projectDir, "node_modules", lib, "package.json");
+    if (!existsSync(pkgPath)) {
+      throw new Error(
+        `Library '${lib}' is declared in isolate.libraries but not installed. Run: pnpm add ${lib}`,
+      );
+    }
+
+    // Read version for cache key (informational)
+    let version = "unknown";
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
+      version = pkg.version ?? "unknown";
+    } catch {
+      // Non-critical
+    }
+
+    const safeName = lib.replace(/[^a-zA-Z0-9_]/g, "_");
+    const globalName = `__lib_${safeName}`;
+
+    const result = await build({
+      entryPoints: [lib],
+      bundle: true,
+      write: false,
+      format: "iife",
+      globalName,
+      platform: "neutral",
+      target: "es2022",
+      // Resolve from the project's node_modules
+      nodePaths: [resolve(projectDir, "node_modules")],
+      plugins: [blockedBuiltinsPlugin()],
+      logLevel: "silent",
+      minify: false,
+    });
+
+    if (result.outputFiles?.[0]) {
+      chunks.push(
+        `// --- ${lib}@${version} ---\n${result.outputFiles[0].text}`,
+      );
+      moduleEntries.push(`  ${JSON.stringify(lib)}: ${globalName}`);
+    } else {
+      throw new Error(
+        `Failed to bundle library '${lib}': esbuild produced no output.`,
+      );
+    }
+  }
+
+  // Build the require() shim
+  const requireShim = `
+// --- require() shim ---
+var __modules = {
+${moduleEntries.join(",\n")}
+};
+function require(name) {
+  var mod = __modules[name];
+  if (!mod) throw new Error('Module "' + name + '" is not available. Available: ${libraries.join(", ")}');
+  // Handle both default and namespace exports
+  if (mod && mod.default !== undefined && Object.keys(mod).length === 1) return mod.default;
+  return mod;
+}
+`;
+
+  return chunks.join("\n\n") + "\n\n" + requireShim;
+}

package/src/isolate/index.ts

@@ -0,0 +1,10 @@
+// ---------------------------------------------------------------------------
+// Isolate module – public exports for harness integration.
+// ---------------------------------------------------------------------------
+
+export { createRunCodeTool, type CreateRunCodeToolOptions } from "./run-code-tool.js";
+export { createIsolateRuntime, type IsolateRuntime, type ExecutionResult } from "./runtime.js";
+export { generateIsolateTypeStubs, buildRunCodeDescription } from "./type-stubs.js";
+export { createVfsBindings, createFetchBinding, mergeBuilderBindings } from "./bindings.js";
+export { buildPolyfillPreamble } from "./polyfills.js";
+export { bundleLibraries } from "./bundler.js";