@poncho-ai/harness 0.35.0 → 0.36.1

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

@@ -0,0 +1,267 @@
+// ---------------------------------------------------------------------------
+// PonchoFsAdapter – implements just-bash's IFileSystem backed by StorageEngine.
+// ---------------------------------------------------------------------------
+
+import type {
+  BufferEncoding,
+  CpOptions,
+  FileContent,
+  FsStat,
+  IFileSystem,
+  MkdirOptions,
+  RmOptions,
+} from "just-bash";
+import type { StorageEngine } from "../storage/engine.js";
+
+const MIME_MAP: Record<string, string> = {
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".csv": "text/csv",
+  ".md": "text/markdown",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".jsx": "text/javascript",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".sh": "application/x-sh",
+  ".py": "text/x-python",
+  ".rb": "text/x-ruby",
+  ".go": "text/x-go",
+  ".rs": "text/x-rust",
+  ".java": "text/x-java",
+  ".c": "text/x-c",
+  ".cpp": "text/x-c++",
+  ".h": "text/x-c",
+  ".sql": "application/sql",
+  ".wasm": "application/wasm",
+};
+
+const mimeFromExtension = (path: string): string | undefined => {
+  const dot = path.lastIndexOf(".");
+  if (dot === -1) return undefined;
+  return MIME_MAP[path.slice(dot).toLowerCase()];
+};
+
+const normalize = (path: string): string => {
+  // Resolve . and .. segments, collapse multiple slashes
+  const parts = path.split("/");
+  const out: string[] = [];
+  for (const p of parts) {
+    if (p === "" || p === ".") continue;
+    if (p === "..") {
+      out.pop();
+    } else {
+      out.push(p);
+    }
+  }
+  return "/" + out.join("/");
+};
+
+export class PonchoFsAdapter implements IFileSystem {
+  constructor(
+    private engine: StorageEngine,
+    private tenantId: string,
+    private limits: { maxFileSize: number; maxTotalStorage: number },
+  ) {}
+
+  // --- Reads ---
+
+  async readFile(path: string, _options?: { encoding?: BufferEncoding | null } | BufferEncoding): Promise<string> {
+    const buf = await this.engine.vfs.readFile(this.tenantId, normalize(path));
+    return new TextDecoder().decode(buf);
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    return this.engine.vfs.readFile(this.tenantId, normalize(path));
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const s = await this.engine.vfs.stat(this.tenantId, normalize(path));
+    return s !== undefined;
+  }
+
+  async stat(path: string): Promise<FsStat> {
+    const np = normalize(path);
+    const s = await this.engine.vfs.stat(this.tenantId, np);
+    if (!s) throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    return {
+      isFile: s.type === "file",
+      isDirectory: s.type === "directory",
+      isSymbolicLink: s.type === "symlink",
+      mode: s.mode,
+      size: s.size,
+      mtime: new Date(s.updatedAt),
+    };
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const entries = await this.engine.vfs.readdir(this.tenantId, normalize(path));
+    return entries.map((e) => e.name);
+  }
+
+  async readdirWithFileTypes(path: string): Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }>> {
+    const entries = await this.engine.vfs.readdir(this.tenantId, normalize(path));
+    return entries.map((e) => ({
+      name: e.name,
+      isFile: e.type === "file",
+      isDirectory: e.type === "directory",
+      isSymbolicLink: e.type === "symlink",
+    }));
+  }
+
+  // --- Writes ---
+
+  async writeFile(
+    path: string,
+    content: FileContent,
+    _options?: { encoding?: BufferEncoding } | BufferEncoding,
+  ): Promise<void> {
+    const buf = typeof content === "string" ? new TextEncoder().encode(content) : content;
+    if (buf.byteLength > this.limits.maxFileSize) {
+      throw new Error(
+        `File too large: ${buf.byteLength} bytes exceeds limit of ${this.limits.maxFileSize} bytes`,
+      );
+    }
+    const mime = mimeFromExtension(path);
+    await this.engine.vfs.writeFile(this.tenantId, normalize(path), buf, mime);
+  }
+
+  async appendFile(
+    path: string,
+    content: FileContent,
+    _options?: { encoding?: BufferEncoding } | BufferEncoding,
+  ): Promise<void> {
+    const buf = typeof content === "string" ? new TextEncoder().encode(content) : content;
+    await this.engine.vfs.appendFile(this.tenantId, normalize(path), buf);
+  }
+
+  async mkdir(path: string, options?: MkdirOptions): Promise<void> {
+    await this.engine.vfs.mkdir(this.tenantId, normalize(path), options?.recursive);
+  }
+
+  async rm(path: string, options?: RmOptions): Promise<void> {
+    const np = normalize(path);
+    const s = await this.engine.vfs.stat(this.tenantId, np);
+    if (!s) {
+      if (options?.force) return;
+      throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
+    }
+    if (s.type === "directory") {
+      await this.engine.vfs.deleteDir(this.tenantId, np, options?.recursive);
+    } else {
+      await this.engine.vfs.deleteFile(this.tenantId, np);
+    }
+  }
+
+  // --- Compound ops ---
+
+  async cp(src: string, dest: string, options?: CpOptions): Promise<void> {
+    const srcNorm = normalize(src);
+    const destNorm = normalize(dest);
+    const srcStat = await this.engine.vfs.stat(this.tenantId, srcNorm);
+    if (!srcStat) throw new Error(`ENOENT: no such file or directory, cp '${src}'`);
+
+    if (srcStat.type === "directory") {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: cp -r not specified; omitting directory '${src}'`);
+      }
+      await this.engine.vfs.mkdir(this.tenantId, destNorm, true);
+      const entries = await this.engine.vfs.readdir(this.tenantId, srcNorm);
+      for (const entry of entries) {
+        await this.cp(`${srcNorm}/${entry.name}`, `${destNorm}/${entry.name}`, options);
+      }
+    } else {
+      const content = await this.engine.vfs.readFile(this.tenantId, srcNorm);
+      const mime = mimeFromExtension(destNorm);
+      await this.engine.vfs.writeFile(this.tenantId, destNorm, content, mime);
+    }
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    await this.engine.vfs.rename(this.tenantId, normalize(src), normalize(dest));
+  }
+
+  // --- Path resolution ---
+
+  resolvePath(base: string, path: string): string {
+    if (path.startsWith("/")) return normalize(path);
+    return normalize(`${base}/${path}`);
+  }
+
+  async realpath(path: string): Promise<string> {
+    const np = normalize(path);
+    // Resolve symlinks in the path
+    const s = await this.engine.vfs.lstat(this.tenantId, np);
+    if (!s) throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
+    if (s.type === "symlink" && s.symlinkTarget) {
+      const target = s.symlinkTarget.startsWith("/")
+        ? s.symlinkTarget
+        : normalize(`${np.slice(0, np.lastIndexOf("/"))}/${s.symlinkTarget}`);
+      return this.realpath(target);
+    }
+    return np;
+  }
+
+  // --- Sync: required by just-bash for glob/find ---
+
+  getAllPaths(): string[] {
+    return this.engine.vfs.listAllPaths(this.tenantId);
+  }
+
+  // --- Metadata ---
+
+  async chmod(path: string, mode: number): Promise<void> {
+    await this.engine.vfs.chmod(this.tenantId, normalize(path), mode);
+  }
+
+  async utimes(path: string, _atime: Date, mtime: Date): Promise<void> {
+    await this.engine.vfs.utimes(this.tenantId, normalize(path), mtime);
+  }
+
+  // --- Symlinks ---
+
+  async symlink(target: string, linkPath: string): Promise<void> {
+    await this.engine.vfs.symlink(this.tenantId, target, normalize(linkPath));
+  }
+
+  async link(existingPath: string, newPath: string): Promise<void> {
+    // Hard link: copy content
+    const content = await this.engine.vfs.readFile(this.tenantId, normalize(existingPath));
+    const mime = mimeFromExtension(newPath);
+    await this.engine.vfs.writeFile(this.tenantId, normalize(newPath), content, mime);
+  }
+
+  async readlink(path: string): Promise<string> {
+    return this.engine.vfs.readlink(this.tenantId, normalize(path));
+  }
+
+  async lstat(path: string): Promise<FsStat> {
+    const np = normalize(path);
+    const s = await this.engine.vfs.lstat(this.tenantId, np);
+    if (!s) throw new Error(`ENOENT: no such file or directory, lstat '${path}'`);
+    return {
+      isFile: s.type === "file",
+      isDirectory: s.type === "directory",
+      isSymbolicLink: s.type === "symlink",
+      mode: s.mode,
+      size: s.size,
+      mtime: new Date(s.updatedAt),
+    };
+  }
+}

package/src/vfs/protected-fs.ts

@@ -0,0 +1,177 @@
+// ---------------------------------------------------------------------------
+// ProtectedFs – write protection wrapper for project files.
+// Blocks writes/deletes to sensitive paths. All reads pass through.
+// ---------------------------------------------------------------------------
+
+import type {
+  BufferEncoding,
+  CpOptions,
+  FileContent,
+  FsStat,
+  IFileSystem,
+  MkdirOptions,
+  RmOptions,
+} from "just-bash";
+
+const DEFAULT_PROTECTED_PATTERNS = [
+  ".env",
+  ".env.*",
+  ".git/",
+  "node_modules/",
+  ".poncho/",
+  "poncho.config.*",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+];
+
+function matchProtectedPattern(pattern: string, path: string): boolean {
+  // Normalize: strip leading /
+  const rel = path.startsWith("/") ? path.slice(1) : path;
+  const segments = rel.split("/");
+
+  if (pattern.endsWith("/")) {
+    // Directory prefix: block this dir and everything under it
+    const dir = pattern.slice(0, -1);
+    return segments[0] === dir || rel.startsWith(dir + "/");
+  }
+
+  if (pattern.includes("*")) {
+    // Wildcard: convert to regex
+    const re = new RegExp(
+      "^" + pattern.replace(/\./g, "\\.").replace(/\*/g, "[^/]*") + "$",
+    );
+    return re.test(segments[0] ?? "") || re.test(rel);
+  }
+
+  // Exact match on the first segment or full path
+  return segments[0] === pattern || rel === pattern;
+}
+
+export class ProtectedFs implements IFileSystem {
+  private inner: IFileSystem;
+  private patterns: string[];
+
+  constructor(inner: IFileSystem, patterns?: string[]) {
+    this.inner = inner;
+    this.patterns = patterns ?? DEFAULT_PROTECTED_PATTERNS;
+  }
+
+  private isProtected(path: string): boolean {
+    return this.patterns.some((p) => matchProtectedPattern(p, path));
+  }
+
+  private guard(path: string, op: string): void {
+    if (this.isProtected(path)) {
+      throw new Error(`Permission denied: ${path} is protected (${op})`);
+    }
+  }
+
+  // --- Reads: pass through ---
+
+  readFile(path: string, options?: { encoding?: BufferEncoding | null } | BufferEncoding): Promise<string> {
+    return this.inner.readFile(path, options);
+  }
+
+  readFileBuffer(path: string): Promise<Uint8Array> {
+    return this.inner.readFileBuffer(path);
+  }
+
+  exists(path: string): Promise<boolean> {
+    return this.inner.exists(path);
+  }
+
+  stat(path: string): Promise<FsStat> {
+    return this.inner.stat(path);
+  }
+
+  readdir(path: string): Promise<string[]> {
+    return this.inner.readdir(path);
+  }
+
+  readdirWithFileTypes(path: string): Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }>> {
+    if (this.inner.readdirWithFileTypes) {
+      return this.inner.readdirWithFileTypes(path);
+    }
+    throw new Error("readdirWithFileTypes not supported");
+  }
+
+  lstat(path: string): Promise<FsStat> {
+    return this.inner.lstat(path);
+  }
+
+  readlink(path: string): Promise<string> {
+    return this.inner.readlink(path);
+  }
+
+  realpath(path: string): Promise<string> {
+    return this.inner.realpath(path);
+  }
+
+  getAllPaths(): string[] {
+    return this.inner.getAllPaths();
+  }
+
+  resolvePath(base: string, path: string): string {
+    return this.inner.resolvePath(base, path);
+  }
+
+  // --- Writes: check protection ---
+
+  writeFile(
+    path: string,
+    content: FileContent,
+    options?: { encoding?: BufferEncoding } | BufferEncoding,
+  ): Promise<void> {
+    this.guard(path, "write");
+    return this.inner.writeFile(path, content, options);
+  }
+
+  appendFile(
+    path: string,
+    content: FileContent,
+    options?: { encoding?: BufferEncoding } | BufferEncoding,
+  ): Promise<void> {
+    this.guard(path, "append");
+    return this.inner.appendFile(path, content, options);
+  }
+
+  mkdir(path: string, options?: MkdirOptions): Promise<void> {
+    return this.inner.mkdir(path, options);
+  }
+
+  rm(path: string, options?: RmOptions): Promise<void> {
+    this.guard(path, "rm");
+    return this.inner.rm(path, options);
+  }
+
+  cp(src: string, dest: string, options?: CpOptions): Promise<void> {
+    this.guard(dest, "cp");
+    return this.inner.cp(src, dest, options);
+  }
+
+  mv(src: string, dest: string): Promise<void> {
+    this.guard(src, "mv");
+    this.guard(dest, "mv");
+    return this.inner.mv(src, dest);
+  }
+
+  chmod(path: string, mode: number): Promise<void> {
+    this.guard(path, "chmod");
+    return this.inner.chmod(path, mode);
+  }
+
+  utimes(path: string, atime: Date, mtime: Date): Promise<void> {
+    return this.inner.utimes(path, atime, mtime);
+  }
+
+  symlink(target: string, linkPath: string): Promise<void> {
+    this.guard(linkPath, "symlink");
+    return this.inner.symlink(target, linkPath);
+  }
+
+  link(existingPath: string, newPath: string): Promise<void> {
+    this.guard(newPath, "link");
+    return this.inner.link(existingPath, newPath);
+  }
+}

package/src/vfs/read-file-tool.ts

@@ -0,0 +1,103 @@
+// ---------------------------------------------------------------------------
+// read_file tool – read files from the VFS, returning binary files (images,
+// PDFs) as FileContentPart references that the harness resolves lazily at
+// model-request time via the vfs:// scheme.
+// ---------------------------------------------------------------------------
+
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+import type { StorageEngine } from "../storage/engine.js";
+import { VFS_SCHEME } from "../upload-store.js";
+
+const MIME_MAP: Record<string, string> = {
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".csv": "text/csv",
+  ".md": "text/markdown",
+  ".ts": "text/typescript",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".py": "text/x-python",
+  ".sh": "application/x-sh",
+  ".sql": "application/sql",
+};
+
+const mimeFromPath = (path: string): string | undefined => {
+  const dot = path.lastIndexOf(".");
+  if (dot === -1) return undefined;
+  return MIME_MAP[path.slice(dot).toLowerCase()];
+};
+
+const isTextMime = (mime: string): boolean =>
+  mime.startsWith("text/") ||
+  mime === "application/json" ||
+  mime === "application/xml" ||
+  mime === "application/sql" ||
+  mime === "application/javascript" ||
+  mime === "application/x-sh";
+
+export const createReadFileTool = (
+  engine: StorageEngine,
+): ToolDefinition => defineTool({
+  name: "read_file",
+  description:
+    "Read a file from the virtual filesystem. " +
+    "Returns text content for text-based files, or sends images and PDFs " +
+    "directly to the model for visual analysis.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Absolute path of the file to read (e.g. /data/report.pdf, /screenshots/page.png)",
+      },
+    },
+    required: ["path"],
+    additionalProperties: false,
+  },
+  handler: async (input, context) => {
+    const filePath = typeof input.path === "string" ? input.path.trim() : "";
+    if (!filePath) {
+      throw new Error("path is required");
+    }
+
+    const tenantId = context.tenantId ?? "__default__";
+    const stat = await engine.vfs.stat(tenantId, filePath);
+    if (!stat) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    if (stat.type === "directory") {
+      throw new Error(`${filePath} is a directory, not a file`);
+    }
+
+    const mediaType = stat.mimeType ?? mimeFromPath(filePath) ?? "application/octet-stream";
+    const filename = filePath.split("/").pop() ?? filePath;
+
+    // Text files: read and return inline
+    if (isTextMime(mediaType)) {
+      const buf = await engine.vfs.readFile(tenantId, filePath);
+      const text = Buffer.from(buf).toString("utf8");
+      return { filename, mediaType, content: text };
+    }
+
+    // Images and PDFs: return a vfs:// reference that the harness resolves
+    // lazily at model-request time — the actual bytes never sit in context.
+    return {
+      type: "file",
+      data: `${VFS_SCHEME}${filePath}`,
+      mediaType,
+      filename,
+    };
+  },
+});

package/src/vfs/write-file-tool.ts

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// write_file tool – create or overwrite a file in the VFS.
+// ---------------------------------------------------------------------------
+
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+import type { StorageEngine } from "../storage/engine.js";
+
+export const createWriteFileTool = (
+  engine: StorageEngine,
+): ToolDefinition => defineTool({
+  name: "write_file",
+  description:
+    "Create a new file or overwrite an existing file in the virtual filesystem. " +
+    "Parent directories are created automatically. " +
+    "Prefer edit_file for targeted changes to existing files.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Absolute path of the file to write (e.g. /data/output.json)",
+      },
+      content: {
+        type: "string",
+        description: "The full content to write to the file",
+      },
+    },
+    required: ["path", "content"],
+    additionalProperties: false,
+  },
+  handler: async (input, context) => {
+    const filePath = typeof input.path === "string" ? input.path.trim() : "";
+    const content = typeof input.content === "string" ? input.content : "";
+
+    if (!filePath) throw new Error("path is required");
+
+    const tenantId = context.tenantId ?? "__default__";
+
+    // Create parent directories
+    const dir = filePath.slice(0, filePath.lastIndexOf("/"));
+    if (dir) {
+      await engine.vfs.mkdir(tenantId, dir, true);
+    }
+
+    await engine.vfs.writeFile(tenantId, filePath, new TextEncoder().encode(content));
+
+    return { ok: true, path: filePath };
+  },
+});