sandboxedjs 0.2.19 → 0.2.20

package/docs/agent/README.md

@@ -1,77 +1,52 @@
-# SandboxedJS native Python package platform
+# SandboxedJS for AI Agents
 
-This folder is an executable work specification for a coding agent. Its goal is
-not to port NumPy. Its goal is to make native Python packages a platform
-capability of SandboxedJS, with NumPy eventually serving as one demanding
-acceptance case.
+SandboxedJS provides a high-fidelity, zero-infrastructure execution environment specifically designed for AI agents. Instead of limiting your agent to a handful of tool-calling functions, SandboxedJS gives your model a real POSIX shell, a virtual filesystem, and full Node.js and Python runtimes.
 
-## Start here
+Whether you are building a coding assistant, an automated researcher, or a complex agentic workflow, SandboxedJS ensures that the code your agent writes and executes is isolated from your host system while remaining functionally complete.
 
-At the beginning of every turn, read only these files:
+## Why a Real Shell for Agents?
 
-1. `README.md` (this file).
-2. `STATE.md`.
-3. The one task file named by `STATE.md`.
+Most agent sandboxes provide a restricted set of APIs (e.g., `read_file`, `write_file`). While safe, this creates a "capability gap" where agents struggle with real-world tasks. 
 
-Do not reread every document on every turn. Open `INVARIANTS.md`,
-`DECISION-TREE.md`, or `COMMANDS.md` only when the current task points to them
-or an observed failure requires them. This is intentional: the folder is also
-a context and token budget.
+By providing a full shell, your agent can:
+- **Manage Complex Projects**: Use `mkdir`, `find`, and `grep` to navigate and analyze large codebases.
+- **Install Dependencies**: Use `npm install` or `pip install` to bring in the exact libraries needed for a task.
+- **Execute Pipelines**: Chain commands using pipes (`|`) and redirections (`>`), allowing the agent to use standard Unix tools for data processing.
+- **Run Multi-Language Workflows**: Seamlessly switch between JavaScript for the frontend and Python for data science within the same container.
 
-Then execute the loop in `LOOP.md`. Continue until the current task's exit gate
-passes or a stop condition requires the user or a stronger model.
+## Integration
 
-## Product objective
+SandboxedJS is designed to plug into modern agent frameworks. It mirrors the `SandboxBackendProtocolV2` used by [LangChain Deep Agents](https://github.com/langchain-ai/deepagents), making it a drop-in replacement for heavier, infra-dependent backends.
 
-The eventual user experience is:
+```ts
+import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";
 
-```sh
-pip install some-package
-```
-
-The implementation may obtain a pure wheel, install an already-built
-SandboxedJS wheel, or ask an external build system to create and cache a wheel.
-It must never install a host-native artifact by relabeling it, silently omit a
-dependency, or claim support because compilation alone succeeded.
-
-## Current baseline
-
-The working tree already contains staged, uncommitted work produced in an
-earlier session:
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true },
+});
 
-- a generic setuptools cross environment;
-- package-owned `setup.py` and `pyproject.toml` builds;
-- C and Cython fixtures;
-- the existing PyO3 path;
-- side-module validation and runtime import tests;
-- `docs/python/cross-build.md`, which records ten known assumptions.
+// Equip the container with standard agent skills (ls, read, write, edit, etc.)
+await installSandboxSkills(box);
 
-Preserve those staged changes. Do not unstage, discard, rewrite wholesale, or
-commit them unless the user explicitly requests it. First verify them and
-record the result in `STATE.md`.
-
-## Scope boundary
-
-This project owns:
+const agent = createDeepAgent({
+  model,
+  backend: new SandboxedJsBackend(box, { cwd: "/app" }),
+});
+```
 
-- reproducible cross-build inputs;
-- build/host/target dependency separation;
-- package build-backend execution;
-- ABI-valid wheel construction and metadata;
-- wheel indexing, resolution, installation, and runtime verification;
-- explicit recipes and patches for irreducibly package-specific behavior;
-- compatibility evidence.
+## Security for Agents
 
-This project does not own, unless the user separately authorizes it:
+Because the container runs entirely in memory (or within a Worker thread), you can spin up a fresh, isolated instance for every single user session or agent task. 
 
-- a hosted public build service;
-- cloud accounts, deployment, billing, or package signing infrastructure;
-- pretending raw sockets, subprocesses, GPU APIs, or unavailable operating
-  system capabilities exist;
-- broad unrelated cleanup of SandboxedJS.
+- **No Host Access**: The agent cannot see your `/Users` directory or environment variables unless you explicitly mount them.
+- **Network Control**: Outbound access is off by default. You decide exactly which APIs the agent can reach.
+- **Instant Disposal**: Once the task is complete, `box.dispose()` wipes the entire environment instantly.
 
-## Definition of success
+## Technical Specification
 
-Success is a general pipeline demonstrated by several independent package
-shapes, not one famous package. The final gate is described in `ROADMAP.md`.
+For developers contributing to the agent platform or extending the runtime, see the detailed work specifications in this folder.
 
+- `STATE.md`: Current progress and active tasks.
+- `COMMANDS.md`: Available shell commands and their implementations.
+- `ROADMAP.md`: The path toward a fully compatible native Python package platform.

package/docs/vireo.md

@@ -0,0 +1,58 @@
+# Vireo browser engine
+
+SandboxedJs keeps browser automation APIs in the runtime and distributes the
+browser engine independently. The `chrome` command is a Chrome DevTools
+Protocol compatibility process used by unmodified Node and Python Playwright;
+Vireo is the Rust/WebAssembly document engine behind it.
+
+## Installation
+
+Vireo is a signed `.sbjs` application from the standard application registry:
+
+```sh
+pm install vireo
+```
+
+Playwright does not need a separate setup step. Installing `playwright-core`
+or Python `playwright` creates the executable stubs Playwright expects. The
+first launch of one of those stubs installs Vireo if it is absent, verifies its
+registry digest, package manifest, and Ed25519 signature, then loads the WASM
+module from `/opt/vireo`. Set `SBX_VIREO_AUTOINSTALL=0` to prohibit that lazy
+network installation; the compatibility process then retains its minimal
+JavaScript-only fallback.
+
+The application registry can still be replaced with `SBX_PM_REGISTRY`, which
+is useful for offline mirrors and tests.
+
+## Package contract
+
+Vireo's `app.json` advertises a versioned engine contract:
+
+```json
+{
+  "provides": ["browser-engine", "playwright-browser"],
+  "browserEngine": {
+    "abi": "sandboxedjs-browser-engine-v1",
+    "wasm": "engine/vireo.wasm",
+    "product": "Vireo/0.1.0"
+  }
+}
+```
+
+The v1 WASM ABI transfers a fetched HTML document and its final URL into
+Vireo, and receives a serialized, browser-parsed document tree. Networking
+stays in SandboxedJs so the same outbound policy, proxy, loopback isolation,
+and accounting apply to browser navigation as to `curl` and guest `fetch`.
+
+## Current compatibility
+
+Vireo 0.1 supplies standards-based HTML5 parsing, real HTTP navigation,
+redirect handling, document titles, text, attributes, and basic CSS selector
+queries in page evaluation. `page.goto()`, `page.title()`, and direct
+`page.evaluate()` document access work through unmodified Playwright.
+
+This is the first engine ABI, not a claim of Chromium parity. External and
+inline page scripts, subresources, complete DOM mutation, cross-world element
+adoption, layout, input actionability, frames, and screenshots remain future
+Vireo engine/runtime capabilities. Unsupported CDP methods continue to return
+`Method not found`; they are not acknowledged with fabricated results.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.19",
-  "description": "A Linux-like container that runs entirely inside Node.js — POSIX shell, ~140 coreutils, Node.js and Python runtimes, virtual filesystem and networking. No Docker, no VM, no native modules.",
+  "version": "0.2.20",
+  "description": "A zero-infra JavaScript and Python sandbox for AI agents and browser IDEs. A lightweight, secure alternative to WebContainers and NodePod for running untrusted code with a full POSIX shell.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -80,7 +80,15 @@
     "python",
     "webcontainer",
     "virtual-filesystem",
-    "emulator"
+    "emulator",
+    "ai-agent-sandbox",
+    "javascript-sandboxing",
+    "code-execution",
+    "webcontainer-alternative",
+    "nodepod-alternative",
+    "untrusted-code",
+    "browser-ide",
+    "secure-sandbox"
   ],
   "dependencies": {
     "@noble/hashes": "^1.8.0",