sandboxedjs 0.1.36 → 0.1.38

package/dist/agent.cjs

@@ -0,0 +1,609 @@
+'use strict';
+
+// src/agent/backend.ts
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "ico",
+  "bmp",
+  "pdf",
+  "zip",
+  "gz",
+  "tar",
+  "wasm",
+  "so",
+  "dylib",
+  "dll",
+  "exe",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "mp3",
+  "mp4",
+  "mov",
+  "avi",
+  "bin",
+  "db",
+  "sqlite"
+]);
+var MIME_BY_EXTENSION = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  json: "application/json",
+  js: "text/javascript",
+  ts: "text/x-typescript",
+  html: "text/html",
+  css: "text/css",
+  md: "text/markdown",
+  wasm: "application/wasm"
+};
+function extensionOf(filePath) {
+  const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+function globToRegExp(pattern) {
+  let out = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        i += 1;
+        if (pattern[i + 1] === "/") {
+          i += 1;
+          out += "(?:.*/)?";
+        } else {
+          out += ".*";
+        }
+      } else {
+        out += "[^/]*";
+      }
+    } else if (ch === "?") {
+      out += "[^/]";
+    } else {
+      out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+function joinPath(base, name) {
+  return base.endsWith("/") ? `${base}${name}` : `${base}/${name}`;
+}
+function requireAbsolute(filePath) {
+  return filePath.startsWith("/") ? null : `Path must be absolute: ${filePath}`;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function looksBinary(data, filePath) {
+  if (BINARY_EXTENSIONS.has(extensionOf(filePath))) return true;
+  const window = data.subarray(0, 1024);
+  for (const byte of window) if (byte === 0) return true;
+  return false;
+}
+var SandboxedJsBackend = class {
+  constructor(container, options = {}) {
+    this.container = container;
+    this.id = options.id ?? `sandboxedjs-${Math.random().toString(36).slice(2, 10)}`;
+    this.cwd = options.cwd;
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.maxOutputChars = options.maxOutputChars ?? 3e4;
+    this.defaultReadLimit = options.defaultReadLimit ?? 500;
+    this.maxGlobResults = options.maxGlobResults ?? 1e3;
+    this.defaultGrepMaxCount = options.defaultGrepMaxCount ?? 200;
+  }
+  container;
+  id;
+  cwd;
+  timeoutMs;
+  maxOutputChars;
+  defaultReadLimit;
+  maxGlobResults;
+  defaultGrepMaxCount;
+  async execute(command) {
+    try {
+      const result = await this.container.exec(command, {
+        cwd: this.cwd,
+        timeoutMs: this.timeoutMs
+      });
+      let output = result.output;
+      let truncated = false;
+      if (output.length > this.maxOutputChars) {
+        output = `[output truncated to the last ${this.maxOutputChars} characters]
+${output.slice(-this.maxOutputChars)}`;
+        truncated = true;
+      }
+      if (result.timedOut) {
+        output += `
+[command timed out after ${this.timeoutMs}ms]`;
+      }
+      return { output, exitCode: result.exitCode, truncated };
+    } catch (error) {
+      return { output: errorMessage(error), exitCode: 1, truncated: false };
+    }
+  }
+  async ls(path) {
+    const invalid = requireAbsolute(path);
+    if (invalid) return { error: invalid };
+    try {
+      const entries = await this.container.fs.readdir(path);
+      const files = [];
+      for (const name of entries) {
+        const full = joinPath(path, name);
+        try {
+          const stats = await this.container.fs.stat(full);
+          const isDir = stats.isDirectory();
+          files.push({
+            path: isDir ? `${full}/` : full,
+            is_dir: isDir,
+            size: isDir ? void 0 : stats.size,
+            modified_at: new Date(stats.mtimeMs).toISOString()
+          });
+        } catch {
+          files.push({ path: full });
+        }
+      }
+      return { files };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async read(filePath, offset = 0, limit) {
+    const invalid = requireAbsolute(filePath);
+    if (invalid) return { error: invalid };
+    try {
+      const raw = await this.container.fs.readFile(filePath);
+      const mimeType = MIME_BY_EXTENSION[extensionOf(filePath)];
+      if (looksBinary(raw, filePath)) {
+        return { content: raw, mimeType: mimeType ?? "application/octet-stream" };
+      }
+      const text = new TextDecoder().decode(raw);
+      const lines = text.split("\n");
+      if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+      const start = Math.max(0, offset);
+      const end = Math.min(lines.length, start + (limit ?? this.defaultReadLimit));
+      return {
+        content: lines.slice(start, end).join("\n"),
+        mimeType: mimeType ?? "text/plain",
+        totalLines: lines.length,
+        startLine: start,
+        endLine: end,
+        nextOffset: end < lines.length ? end : void 0
+      };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async readRaw(filePath) {
+    const invalid = requireAbsolute(filePath);
+    if (invalid) return { error: invalid };
+    try {
+      const raw = await this.container.fs.readFile(filePath);
+      const mimeType = MIME_BY_EXTENSION[extensionOf(filePath)];
+      if (looksBinary(raw, filePath)) {
+        return { data: { content: raw, mimeType: mimeType ?? "application/octet-stream" } };
+      }
+      return {
+        data: { content: new TextDecoder().decode(raw), mimeType: mimeType ?? "text/plain" }
+      };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async write(filePath, content) {
+    const invalid = requireAbsolute(filePath);
+    if (invalid) return { error: invalid };
+    try {
+      const parent = filePath.slice(0, filePath.lastIndexOf("/")) || "/";
+      await this.container.fs.mkdir(parent, { recursive: true });
+      await this.container.fs.writeFile(filePath, content);
+      return { path: filePath };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async edit(filePath, oldString, newString, replaceAll = false) {
+    const invalid = requireAbsolute(filePath);
+    if (invalid) return { error: invalid };
+    try {
+      const text = await this.container.fs.readFile(filePath, "utf8");
+      const occurrences = oldString === "" ? 0 : text.split(oldString).length - 1;
+      if (occurrences === 0) {
+        return { error: `String not found in ${filePath}: ${JSON.stringify(oldString)}` };
+      }
+      if (occurrences > 1 && !replaceAll) {
+        return {
+          error: `String appears ${occurrences} times in ${filePath}. Provide more surrounding context to make it unique, or pass replaceAll.`
+        };
+      }
+      const updated = replaceAll ? text.split(oldString).join(newString) : text.replace(oldString, newString);
+      await this.container.fs.writeFile(filePath, updated);
+      return { path: filePath, occurrences };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async delete(filePath) {
+    const invalid = requireAbsolute(filePath);
+    if (invalid) return { error: invalid };
+    try {
+      await this.container.fs.rm(filePath, { recursive: true, force: false });
+      return { path: filePath };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async glob(pattern, path = "/") {
+    try {
+      const matcher = globToRegExp(pattern.startsWith("/") ? pattern : joinPath(path, pattern));
+      const files = [];
+      let truncated = false;
+      for (const candidate of await this.container.fs.walk(path)) {
+        if (!matcher.test(candidate)) continue;
+        if (files.length >= this.maxGlobResults) {
+          truncated = true;
+          break;
+        }
+        files.push({ path: candidate });
+      }
+      return { files, truncated };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async grep(pattern, path, glob, maxCount) {
+    const root = path ?? "/";
+    const cap = maxCount ?? this.defaultGrepMaxCount;
+    try {
+      const filter = glob ? globToRegExp(glob.includes("/") ? glob : `**/${glob}`) : null;
+      const matches = [];
+      let truncated = false;
+      outer: for (const candidate of await this.container.fs.walk(root)) {
+        if (filter && !filter.test(candidate)) continue;
+        let raw;
+        try {
+          raw = await this.container.fs.readFile(candidate);
+        } catch {
+          continue;
+        }
+        if (looksBinary(raw, candidate)) continue;
+        const lines = new TextDecoder().decode(raw).split("\n");
+        for (let i = 0; i < lines.length; i += 1) {
+          if (!lines[i].includes(pattern)) continue;
+          if (matches.length >= cap) {
+            truncated = true;
+            break outer;
+          }
+          matches.push({ path: candidate, line: i + 1, text: lines[i] });
+        }
+      }
+      return { matches, truncated };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
+  async uploadFiles(files) {
+    const results = [];
+    for (const [filePath, content] of files) {
+      if (!filePath.startsWith("/")) {
+        results.push({ path: filePath, error: "invalid_path" });
+        continue;
+      }
+      try {
+        const parent = filePath.slice(0, filePath.lastIndexOf("/")) || "/";
+        await this.container.fs.mkdir(parent, { recursive: true });
+        await this.container.fs.writeFile(filePath, content);
+        results.push({ path: filePath, error: null });
+      } catch {
+        results.push({ path: filePath, error: "permission_denied" });
+      }
+    }
+    return results;
+  }
+  async downloadFiles(paths) {
+    const results = [];
+    for (const filePath of paths) {
+      if (!filePath.startsWith("/")) {
+        results.push({ path: filePath, content: null, error: "invalid_path" });
+        continue;
+      }
+      try {
+        const stats = await this.container.fs.stat(filePath);
+        if (stats.isDirectory()) {
+          results.push({ path: filePath, content: null, error: "is_directory" });
+          continue;
+        }
+        results.push({
+          path: filePath,
+          content: await this.container.fs.readFile(filePath),
+          error: null
+        });
+      } catch {
+        results.push({ path: filePath, content: null, error: "file_not_found" });
+      }
+    }
+    return results;
+  }
+};
+
+// src/agent/prompts.ts
+var SANDBOX_ENVIRONMENT_PROMPT = `# Your environment
+
+You are working inside a sandboxedjs container: a Linux-like environment that
+runs entirely inside a JavaScript process. There is no Docker, no VM, and no
+host machine you can reach. Everything below is real and available to you.
+
+## What you have
+
+- A POSIX shell (\`sh\`/\`bash\` syntax): pipes, redirection, \`&&\`, \`||\`,
+  subshells, globs, heredocs, variables, functions, \`for\`/\`while\`/\`case\`.
+- Around 140 coreutils: \`ls cat cp mv rm mkdir find grep sed awk head tail
+  sort uniq wc diff patch tar gzip curl chmod ln touch echo printf test\` and
+  the rest of the usual set.
+- Node.js, with \`node\`, \`npm\` and \`npx\`. \`npm install\` resolves against
+  the real npm registry when outbound network is enabled.
+- Python 3 via \`python3\` and \`pip\`, when the host enabled the Python runtime.
+- A writable virtual filesystem rooted at \`/\`, persistent for the life of the
+  container.
+- A virtual network stack. Servers you start inside the container really listen
+  on their ports and can really be requested.
+
+## What you do not have
+
+- No Docker, no VM, no \`systemctl\`, no \`service\`, no \`apt\`/\`apt-get\`,
+  no \`yum\`, no \`brew\`. Never try to install system packages.
+- No \`sudo\` and no reason for it: you already run as the container's user and
+  the filesystem is yours.
+- No access to the host machine, its files, its network interfaces, or its
+  environment variables. Nothing outside the container exists for you.
+- No GUI, no browser, no interactive editors. Do not run \`vim\`, \`nano\`,
+  \`less\`, or \`top\`; they will hang or fail. Read files by reading them and
+  edit them by editing them.
+- No long-running foreground commands. A command that never exits will hit the
+  execution timeout and the turn is wasted.
+
+## Running servers
+
+Start servers in the background and never block on them:
+
+\`\`\`sh
+node server.js > /tmp/server.log 2>&1 &
+\`\`\`
+
+Then poll the log for readiness rather than requesting the port immediately.
+Do not run a dev server in the foreground. Do not use \`curl localhost:PORT\`
+to prove a server works unless you started it in the background first \u2014 the
+host, not you, is the one that will connect to it.
+
+## How your work is used
+
+The container is the deliverable. Files you write to the filesystem are what
+the user receives and what a preview will serve. Write real, complete files to
+real paths \u2014 do not print a project to stdout and call it done.`;
+var SANDBOX_AGENT_RULES = `# Rules
+
+1. Verify before you claim. If you say a server runs or a build passes, you
+   ran it in this container and read the output. Never report success you have
+   not observed.
+2. One command, one purpose. Chain with \`&&\` when steps depend on each other
+   so a failure stops the chain instead of hiding under a later success.
+3. Read a file before editing it. Edits are literal string replacements; they
+   fail when you are guessing at the current contents.
+4. Use absolute paths in file tools. Use \`cd\` inside a single shell command
+   when a command needs a working directory.
+5. Install dependencies with \`npm install <pkg>\`, in the directory that has
+   the \`package.json\`. Do not hand-write \`node_modules\` or invent versions
+   in \`package.json\` \u2014 let the installer resolve them.
+6. Background every server and long task, redirect its output to a log file,
+   then poll the log. Never leave a command running in the foreground.
+7. Keep command output small. Pipe noisy commands through \`tail\`, \`head\`
+   or \`grep\`. Output is truncated past the backend's limit and you will lose
+   the part you needed.
+8. When a command fails, read stderr and fix the cause. Do not retry the same
+   command unchanged, and do not work around a failure by faking its result.
+9. Prefer the project's own tooling \u2014 \`npm run build\`, \`npm test\`,
+   \`npx vite\` \u2014 over reimplementing what it already does.
+10. Do not attempt to escape the container, reach the host, or disable the
+    network policy. Outbound access is the host's decision, not yours.
+11. Prefer the non-interactive form of a command when one exists \u2014 pass the
+    flags that pre-answer its questions. A generator that asks nothing is
+    faster and its result is the same every run.
+12. An interactive prompt is not a failure. If a command stops on a question
+    or a menu, answer it: send the text, or the arrow keys and Enter that the
+    prompt names. Read what is on screen before answering, and do not send a
+    second answer until the screen has changed.`;
+function skill(name, description, body) {
+  return {
+    name,
+    description,
+    content: `---
+name: ${name}
+description: ${description}
+---
+
+${body}
+`
+  };
+}
+var SANDBOX_SKILLS = [
+  skill(
+    "node-service",
+    "Scaffold, install, run and verify a Node.js HTTP service (Express, Fastify, plain http) inside the sandbox.",
+    `# Building a Node HTTP service
+
+Follow these steps in order. Do not skip verification.
+
+1. Create the project directory and manifest:
+
+   \`\`\`sh
+   mkdir -p /app && cd /app && npm init -y
+   \`\`\`
+
+2. Install dependencies in one command:
+
+   \`\`\`sh
+   cd /app && npm install express
+   \`\`\`
+
+   Read the output. If it ends in an \`ENOTFOUND\` or network error, outbound
+   access is disabled for this container \u2014 say so and stop, rather than
+   inventing a dependency-free rewrite the user did not ask for.
+
+3. Write the server to a real file. Bind to \`0.0.0.0\` and log a line on
+   listen, so readiness is observable:
+
+   \`\`\`js
+   const express = require("express");
+   const app = express();
+   app.get("/", (_req, res) => res.send("hello world"));
+   const port = Number(process.env.PORT) || 3000;
+   app.listen(port, "0.0.0.0", () => console.log(\`listening on \${port}\`));
+   \`\`\`
+
+4. Start it in the background and wait for the log line:
+
+   \`\`\`sh
+   cd /app && node server.js > /tmp/server.log 2>&1 &
+   sleep 1 && cat /tmp/server.log
+   \`\`\`
+
+5. Verify it answers:
+
+   \`\`\`sh
+   curl -s -i http://127.0.0.1:3000/ | head -20
+   \`\`\`
+
+   A non-2xx status or an empty response means the server is not working. Read
+   \`/tmp/server.log\` and fix the cause before reporting anything.`
+  ),
+  skill(
+    "frontend-app",
+    "Create and run a Vite frontend (React, Vue, Svelte, vanilla) inside the sandbox without an interactive scaffolder.",
+    `# Building a frontend app
+
+A generator works here \u2014 the sandbox can answer its prompts \u2014 but writing the
+files yourself is faster and deterministic, and you control exactly what the
+project contains. Prefer it unless the framework's initializer does real work
+you would otherwise have to reproduce. If you do run one, answer its prompts.
+
+1. Write \`/app/package.json\`. Give the dependencies real version ranges and
+   let the installer resolve them:
+
+   \`\`\`json
+   {
+     "name": "app",
+     "private": true,
+     "type": "module",
+     "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" },
+     "dependencies": { "react": "^19.0.0", "react-dom": "^19.0.0" },
+     "devDependencies": { "@vitejs/plugin-react": "^5.0.0", "vite": "^7.0.0" }
+   }
+   \`\`\`
+
+2. Write the four files a Vite app actually needs: \`index.html\` with
+   \`<div id="root">\` and a module script pointing at \`/src/main.jsx\`,
+   \`vite.config.js\` registering the framework plugin, \`src/main.jsx\`
+   mounting the root, and \`src/App.jsx\`.
+
+3. Install once, and read the output:
+
+   \`\`\`sh
+   cd /app && npm install
+   \`\`\`
+
+4. Prove it compiles before claiming anything works:
+
+   \`\`\`sh
+   cd /app && npm run build 2>&1 | tail -30
+   \`\`\`
+
+5. Only if a live preview is wanted, start the dev server in the background
+   and confirm it came up:
+
+   \`\`\`sh
+   cd /app && npx vite --host 0.0.0.0 --port 5173 > /tmp/vite.log 2>&1 &
+   sleep 3 && tail -20 /tmp/vite.log
+   \`\`\`
+
+Check the installed major versions before using an API from a package \u2014
+\`cat /app/node_modules/react/package.json\`. A remembered API from a
+different major is the most common cause of a build failure here.`
+  ),
+  skill(
+    "verify-work",
+    "Check that generated code actually builds, runs and passes its tests before reporting completion.",
+    `# Verifying before reporting
+
+Never report a task complete on the strength of having written files.
+
+- If the project has tests: \`cd <dir> && npm test 2>&1 | tail -40\`
+- If it has a build: \`cd <dir> && npm run build 2>&1 | tail -40\`
+- If it has neither and it is a script: run it and read the output.
+- If it is a service: start it in the background and request it (see the
+  \`node-service\` skill).
+
+Then state what you ran and what it printed. If something fails and you cannot
+fix it, say exactly what fails and what you tried. A wrong claim of success is
+worse than an honest failure.`
+  ),
+  skill(
+    "debug-failure",
+    "Diagnose a failing command, build, install or server inside the sandbox instead of retrying blindly.",
+    `# Debugging inside the sandbox
+
+1. Re-read the actual error. The cause is usually the first error line, not
+   the last.
+2. Confirm the state you assumed: \`ls -la\` the directory, \`cat\` the config,
+   \`cat package.json\`. Most failures are a wrong path or a missing install.
+3. Check the log of anything backgrounded: \`tail -50 /tmp/*.log\`.
+4. For a module resolution error, verify the package is installed where you
+   think: \`ls /app/node_modules/<pkg>/package.json\`.
+5. For a port that will not answer, check the process is alive (\`ps\`) and the
+   log shows a listen line. A crashed server leaves no port behind.
+6. Change exactly one thing, then re-run. Do not retry an unchanged command,
+   and do not delete the work to start over unless nothing else is left.`
+  )
+];
+function sandboxSystemPrompt(options = {}) {
+  const parts = [SANDBOX_ENVIRONMENT_PROMPT, SANDBOX_AGENT_RULES];
+  if (options.skills !== false) {
+    parts.push(
+      `# Skills
+
+${SANDBOX_SKILLS.map(
+        (entry) => `## ${entry.name}
+
+${entry.description}
+
+${entry.content.split("---\n")[2].trim()}`
+      ).join("\n\n")}`
+    );
+  }
+  return parts.join("\n\n");
+}
+async function installSandboxSkills(container, directory = "/skills") {
+  for (const entry of SANDBOX_SKILLS) {
+    const dir = `${directory}/${entry.name}`;
+    await container.fs.mkdir(dir, { recursive: true });
+    await container.fs.writeFile(`${dir}/SKILL.md`, entry.content);
+  }
+  return directory;
+}
+
+exports.SANDBOX_AGENT_RULES = SANDBOX_AGENT_RULES;
+exports.SANDBOX_ENVIRONMENT_PROMPT = SANDBOX_ENVIRONMENT_PROMPT;
+exports.SANDBOX_SKILLS = SANDBOX_SKILLS;
+exports.SandboxedJsBackend = SandboxedJsBackend;
+exports.installSandboxSkills = installSandboxSkills;
+exports.sandboxSystemPrompt = sandboxSystemPrompt;
+//# sourceMappingURL=agent.cjs.map
+//# sourceMappingURL=agent.cjs.map