sandboxedjs 0.2.22 → 0.2.23

package/docs/to_implement/agent.md

@@ -1,17 +1,151 @@
-# Agent feature
+# Agent support — running other people's agents on SandboxedJs
 
-I want `agent` command in the sandbox. it is a seperate app like officesuit and vireo, we have to provide all the dependencies for it to run here in Sandboxedjs module but we don't provide the .sbjs package here, it will be downloaded from sandboxedjswheels.pages.dev site, the code of that site is in /Users/shazi/Projects/sandboxedjswheels.
+> Status: **plan**. Nothing here claims existing support unless it links to code.
 
-# First Phase
+## 1. What this is, and is not
 
-## Objective and scope
+SandboxedJs is a Linux alternative for the browser. It does not ship an agent,
+a model adapter, a prompt, or an API key. The goal of this plan is that agents
+which already exist — Claude Code, Codex, Gemini CLI, opencode, Aider, and
+local model servers such as Ollama — **install and run inside a container the
+way they do on a Linux machine**, and that frameworks which drive a sandbox
+from outside (Deep Agents and the like) find a complete one.
 
-Provide the runtime dependencies of the future `agent` application and the
-transitive dependencies needed to install and execute them. The application stays
-an independently downloaded `.sbjs` package from `sandboxedjswheels.pages.dev`;
-SandboxedJs provides its execution environment, dependency resolver, and optional
-runtime packs. Model creation, training, publication, and agent implementation are
-separate work. This section is an implementation plan, not a claim of existing
+An agent brings its own model, its own credentials and its own loop. What it
+needs from us is an operating system: a place to install, a terminal, a
+filesystem, processes, a network, and somewhere to keep a login.
+
+Not in scope: an agent loop, provider adapters, a model router, context
+management, prompts, evals. An earlier draft of this document planned those;
+they belong to the agents.
+
+## 2. What the agents actually are (npm metadata, 2026-10-02)
+
+How each one is distributed decides which of our runtimes has to carry it.
+
+| Agent | Package | What is in it | Runs on |
+| --- | --- | --- | --- |
+| Claude Code | `@anthropic-ai/claude-code` 2.1.287 | a native executable per platform (`linux-x64`, `linux-arm64`, musl variants), selected through `optionalDependencies` | native Linux binaries (§4) |
+| Codex | `@openai/codex` 0.160.0 | a small JS launcher plus a native executable per platform | native Linux binaries (§4) |
+| opencode | `opencode-ai` 1.18.34 | a native executable per platform | native Linux binaries (§4) |
+| Gemini CLI | `@google/gemini-cli` 0.62.0 | a JavaScript bundle (98 MB unpacked), Node ≥ 20, optional `node-pty` and keytar | the Node runtime (§3) |
+| Aider and other Python agents | PyPI | Python, with compiled dependencies | the Python runtime (§3) |
+| Ollama | upstream Linux release | Go and C++ executables | native Linux binaries (§4) |
+
+The consequence is the centre of this plan: **three of the four coding agents,
+and Ollama, are Linux executables.** Our Node and Python runtimes cannot run
+them however complete they become. Supporting them means executing unmodified
+Linux binaries, which is the Linux-guest work in Appendix D — until now filed
+as a side workstream for local models.
+
+This table is from package metadata only. Nothing in it has been installed or
+run in a container yet; doing that is M0.
+
+## 3. Track A — agents written in JavaScript or Python
+
+These run on the runtimes that exist today, to the extent those runtimes are
+complete. Expected gaps, to be confirmed by running them (M0):
+
+- **Node version and API surface.** Gemini CLI requires Node ≥ 20; the
+  container must report and behave as a version it accepts, including the
+  ESM, `fetch`, streams, `worker_threads` and `child_process` behaviour a
+  98 MB bundle exercises.
+- **A real terminal.** Agent CLIs are full-screen TUIs: raw mode, cursor
+  addressing, resize, bracketed paste, colour detection. `src/container/terminal.ts`
+  and the tty line discipline have to carry that.
+- **Pseudo-terminals.** `node-pty` is a native addon. It needs an in-kernel pty
+  and a shim that answers the addon's interface, or the agent falls back to
+  plain pipes where it can.
+- **Credential storage.** keytar and its equivalents are native too; the
+  fallback is files under the home directory, which must persist (below).
+- **Streaming HTTP out.** Server-sent events and long-lived responses through
+  the egress path, including through the proxy a browser needs for hosts that
+  send no CORS headers.
+- **Install size and time.** `npm install -g` of a package this large, in a
+  tab, with a persistent store so it happens once.
+
+## 4. Track B — agents that are Linux executables
+
+Claude Code, Codex, opencode and Ollama. Two ways to run them, and the first
+has to be measured before the second is considered:
+
+1. **The Linux guest of Appendix D**: a CPU emulator compiled to Wasm, a real
+   kernel and a glibc root filesystem. Unmodified binaries run because it is
+   Linux. Costs: download size, memory, speed, and a network bridge (a browser
+   has no raw sockets, so TLS from inside the guest needs a relay).
+2. **Extending our own ELF execution** (`src/native`, `docs/original-x64.md`)
+   to dynamic linking and a Linux syscall surface. Today it handles a small
+   freestanding subset. This is a far larger project and is not proposed
+   unless the guest proves unusable.
+
+What the guest must provide for an agent specifically, beyond Appendix D:
+
+- A terminal bridged to the page's terminal, with resize.
+- The container's files visible to the guest, so the agent edits the same
+  project the rest of SandboxedJs sees. Appendix D keeps the disks separate
+  with explicit transfer; an agent needs a shared mount, and that design is
+  open (§8).
+- Outbound HTTPS to the agent's provider under the container's egress policy.
+- Its login persisted across reloads.
+
+## 5. What every agent needs from the OS
+
+Mechanisms, each useful without an agent and each tested without one:
+
+| Need | State |
+| --- | --- |
+| Sealed secrets: a credential a process can use and cannot read | first version in `src/net/secrets.ts` (`network.secrets`), for guest `fetch`/`http`/`https`; not yet `curl`, Python sockets or the Linux guest |
+| Outbound policy, proxy for CORS, streaming | `src/net/policy.ts`, `sandboxedjs-egress`; streaming through the proxy unverified |
+| Persistent home directory (logins, config, session history) | to do: which volume, and what survives a reload |
+| Login flows: OAuth in a browser window, device codes, a localhost callback inside the container | to do; the callback needs the preview router to accept an external redirect |
+| Snapshots and undo of the filesystem | to do; lets a host offer "undo what the agent did" for any agent |
+| Per-process limits on files, hosts and commands | to do; the same for every agent, enforced by the kernel rather than by each agent's own permission prompts |
+| Playwright without Chromium, for agents that test web apps | `src/browser/*`, `vireo`; see `docs/virtual-browser.md` |
+| MCP servers from npm and PyPI as container processes | should follow from the Node and Python runtimes; unverified |
+| Driving the container from outside | `src/agent/backend.ts` implements Deep Agents' `SandboxBackendProtocolV2`; exposing the container as an MCP server is to do |
+
+## 6. Milestones
+
+| M | Scope | Done when |
+| --- | --- | --- |
+| M0 | Install and start each agent in §2 in a container, in Node and in a browser. Record exactly where each stops. | A compatibility report in `docs/agent/` replaces the guesses in §3 and §4 |
+| M1 | Track A: Gemini CLI runs a real task end to end, with the user's own key | `gemini` edits a file and runs a command, in Node and in a tab |
+| M2 | OS needs of §5: persistent home, login flows, sealed secrets on every exit | An agent stays logged in across a reload, with its key sealed |
+| M3 | Linux guest foundation (Appendix D, steps 1–2) | A dynamically linked Linux program runs in a tab |
+| M4 | Track B: Claude Code and Codex in the guest, on the container's files | Each completes a task in a tab |
+| M5 | Ollama in the guest (Appendix D, step 3), reachable by agents in the container on port 11434 | A Track A agent uses a guest-hosted model with no network |
+| M6 | Snapshots and per-process limits | A host undoes an agent's changes and confines it, for any agent |
+
+M0 comes first because every later row rests on assumptions it tests.
+
+## 7. Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| An emulated Linux guest is too slow or too large for an interactive agent | Measure in M3 before building M4 on it |
+| Agents change packaging between releases (Claude Code moved from JavaScript to native) | Pin and test named versions; publish the compatibility report per version |
+| Providers refuse browser origins | The egress proxy; document it as a requirement, not an option, where it is one |
+| A vendor's terms restrict where its agent may run | Check each before publishing a claim of support |
+
+## 8. Open questions
+
+1. How the guest sees the container's files: a shared mount (9p or similar)
+   or synchronisation, and who owns consistency.
+2. Whether a pty belongs in the kernel now, for Track A, or arrives with the guest.
+3. Which storage backs a persistent home in a tab, and its size limits.
+4. Which agent and version is the first target for M1 and M4.
+
+---
+
+### Appendix D — Local-model runtime dependencies (original phase one, kept)
+
+#### Objective and scope
+
+Provide the runtime dependencies that agents and local model runtimes need, and
+the transitive dependencies needed to install and execute them. SandboxedJs
+provides the execution environment, dependency resolver, and optional runtime
+packs. Model creation, training, publication, and writing an agent are not part
+of this project. This section is an implementation plan, not a claim of existing
 package support.
 
 Required targets:
@@ -25,7 +159,7 @@ Required targets:
   extending package coverage. Ownership means pinned upstream tools, build recipes,
   patches, and release artifacts; it does not require inventing a compiler.
 
-## Execution architecture: prerequisite before package installation
+#### Execution architecture: prerequisite before package installation
 
 The current POSIX command layer, CPython-to-Wasm runtime, WASI host, and ELF
 dispatch hooks are useful foundations. They do not execute arbitrary Linux
@@ -36,10 +170,10 @@ Linux Python interpreter, or PyTorch. See [browser architecture](../browser-runt
 
 Use two explicit execution profiles:
 
-| Profile | Runtime | Package ABI | Initial purpose |
-| --- | --- | --- | --- |
-| Browser/Wasm | Existing JS runtime, owned Wasm CPython, compatible WASI tools | Browser JS, exact SandboxedJs Python extension ABI, supported WASI imports | Transformers.js and individually validated scientific Wasm packages |
-| Linux guest | Optional full-system CPU emulator compiled to Wasm, Linux kernel, persistent root filesystem | One selected Linux CPU architecture, glibc and native Python wheel tags | Unmodified Ollama, Python Transformers, CPU PyTorch, native compilers |
+| Profile      | Runtime                                                                                      | Package ABI                                                                | Initial purpose                                                       |
+| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Browser/Wasm | Existing JS runtime, owned Wasm CPython, compatible WASI tools                               | Browser JS, exact SandboxedJs Python extension ABI, supported WASI imports | Transformers.js and individually validated scientific Wasm packages   |
+| Linux guest  | Optional full-system CPU emulator compiled to Wasm, Linux kernel, persistent root filesystem | One selected Linux CPU architecture, glibc and native Python wheel tags    | Unmodified Ollama, Python Transformers, CPU PyTorch, native compilers |
 
 For the Linux profile, select a **64-bit architecture supported by the exact
 Ollama and PyTorch releases**. Start by evaluating x86-64 with a glibc-based Debian
@@ -56,23 +190,23 @@ an upstream Linux ELF binary execute in the existing Wasm runtime. Extending the
 original translator to that level is a substantial alternative engineering
 project, not a missing dependency that can simply be installed.
 
-## Dependency packs and their dependencies
+#### Dependency packs and their dependencies
 
 Pack names below are proposed distribution units, not existing npm packages.
 Heavy assets should download on demand rather than become unconditional npm
 dependencies of `sandboxedjs`.
 
-| Pack | Direct contents | Dependencies and required capabilities |
-| --- | --- | --- |
-| `agent-runtime` | `.sbjs` loader, dependency manifest/resolver, execution-profile selection, process and service supervision | Existing container APIs; runtime-pack registry; version checks; install progress, cancellation, logs and cleanup |
-| `browser-ml` | Pinned `@huggingface/transformers`, its resolved browser dependencies and matching ONNX Runtime Web assets | Correct browser export resolution; module workers; fetch, streams, typed arrays; Wasm assets; persistent model cache; optional SIMD, threads and WebGPU according to selected backend |
-| `linux-machine` | Wasm CPU emulator, boot assets, Linux kernel, initramfs where required, guest control agent | Worker isolation, virtual CPU/MMU/interrupts/timers, disk and network devices, guest RAM, persistent disk adapter, host/guest RPC and termination |
-| `linux-base` | glibc distribution rootfs, ELF loader, shell, coreutils, `apt`/`dpkg`, repository metadata/keyrings | Matching architecture and kernel; distro-resolved shared libraries; process, filesystem, clock, entropy, networking and certificate support |
-| `linux-downloads` | `curl`, CA certificates, `tar`, `zstd`, gzip/xz/unzip as required | DNS and working TCP/TLS transport, writable temporary storage, trusted artifact metadata and extraction limits |
-| `linux-python-ml` | Native CPython, `venv`, pip, CPU `torch`, `transformers` | Native wheels matching Python, architecture and glibc; full Python dependency closure and ELF library closure described below |
-| `linux-ollama` | Pinned upstream Linux Ollama release, bundled libraries and CPU runners | `linux-machine`, `linux-base`, `linux-downloads`; runner-compatible CPU features; writable model store; local HTTP server access |
-| `linux-build-tools` | Native C/C++ compiler, linker, Rust toolchain and build drivers | Linux profile, development headers, language standard libraries, build-system dependencies and package-specific source recipes |
-| `wasm-build-sdk` | Emscripten/LLVM, supported WASI SDK, Rust Wasm target, owned Python extension SDK | Separate target sysroots and ABI locks; reproducible external build environment initially; compatible Wasm outputs tested in SandboxedJs |
+| Pack                | Direct contents                                                                                            | Dependencies and required capabilities                                                                                                                                                |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pack-runtime`      | `.sbjs` loader, dependency manifest/resolver, execution-profile selection, process and service supervision | Existing container APIs; runtime-pack registry; version checks; install progress, cancellation, logs and cleanup                                                                      |
+| `browser-ml`        | Pinned `@huggingface/transformers`, its resolved browser dependencies and matching ONNX Runtime Web assets | Correct browser export resolution; module workers; fetch, streams, typed arrays; Wasm assets; persistent model cache; optional SIMD, threads and WebGPU according to selected backend |
+| `linux-machine`     | Wasm CPU emulator, boot assets, Linux kernel, initramfs where required, guest control agent                | Worker isolation, virtual CPU/MMU/interrupts/timers, disk and network devices, guest RAM, persistent disk adapter, host/guest RPC and termination                                     |
+| `linux-base`        | glibc distribution rootfs, ELF loader, shell, coreutils, `apt`/`dpkg`, repository metadata/keyrings        | Matching architecture and kernel; distro-resolved shared libraries; process, filesystem, clock, entropy, networking and certificate support                                           |
+| `linux-downloads`   | `curl`, CA certificates, `tar`, `zstd`, gzip/xz/unzip as required                                          | DNS and working TCP/TLS transport, writable temporary storage, trusted artifact metadata and extraction limits                                                                        |
+| `linux-python-ml`   | Native CPython, `venv`, pip, CPU `torch`, `transformers`                                                   | Native wheels matching Python, architecture and glibc; full Python dependency closure and ELF library closure described below                                                         |
+| `linux-ollama`      | Pinned upstream Linux Ollama release, bundled libraries and CPU runners                                    | `linux-machine`, `linux-base`, `linux-downloads`; runner-compatible CPU features; writable model store; local HTTP server access                                                      |
+| `linux-build-tools` | Native C/C++ compiler, linker, Rust toolchain and build drivers                                            | Linux profile, development headers, language standard libraries, build-system dependencies and package-specific source recipes                                                        |
+| `wasm-build-sdk`    | Emscripten/LLVM, supported WASI SDK, Rust Wasm target, owned Python extension SDK                          | Separate target sysroots and ABI locks; reproducible external build environment initially; compatible Wasm outputs tested in SandboxedJs                                              |
 
 Transformers.js uses ONNX Runtime in the browser; provide the assets matching the
 locked package release and resolve browser exports instead of accidentally loading
@@ -80,7 +214,7 @@ native Node addons. WebGPU is optional for this path and does not accelerate the
 Linux guest automatically. [Upstream Transformers.js documentation](https://huggingface.co/docs/transformers.js/en/index)
 and [asset configuration](https://huggingface.co/docs/transformers.js/custom_usage).
 
-## Linux facilities required underneath the packages
+#### Linux facilities required underneath the packages
 
 The Linux machine must supply more than command names:
 
@@ -111,7 +245,7 @@ Document this infrastructure dependency. Offline operation is possible after
 required packages and models are cached; arbitrary live registry access cannot be
 promised on a static host alone.
 
-## Python and scientific/ML dependency closure
+#### Python and scientific/ML dependency closure
 
 Use native Python inside the Linux guest for the initial full Transformers/PyTorch
 target. Choose the Python version together with the available CPU wheels, rather
@@ -119,13 +253,13 @@ than inheriting the Wasm interpreter version automatically. Resolve the exact
 dependency tree from the selected releases and extras; the following is the
 coverage inventory, not a substitute for a lockfile:
 
-| Layer | Dependencies to resolve and test |
-| --- | --- |
-| Transformers | `transformers`, `huggingface-hub`, `tokenizers`, `safetensors`, NumPy, packaging, filelock, PyYAML, regex, tqdm, and the network/filesystem dependencies declared by the selected versions |
-| PyTorch CPU | CPU-only `torch` wheel and its declared Python dependencies; included or required C/C++ runtime, OpenMP and math libraries; inspect ELF dependencies recursively |
-| Model-dependent extras | SentencePiece/protobuf, Pillow, audio libraries, torchvision/torchaudio, or other processors only when required by the supported model and task |
-| Additional science coverage | NumPy first; SciPy, pandas and scikit-learn as separately validated additions, with matching BLAS/LAPACK, OpenMP and Fortran runtimes where required |
-| Download/cache stack | The selected hub client's HTTP/TLS and filesystem packages, cache locks, resumable downloads, credentials and offline-cache behavior |
+| Layer                       | Dependencies to resolve and test                                                                                                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Transformers                | `transformers`, `huggingface-hub`, `tokenizers`, `safetensors`, NumPy, packaging, filelock, PyYAML, regex, tqdm, and the network/filesystem dependencies declared by the selected versions |
+| PyTorch CPU                 | CPU-only `torch` wheel and its declared Python dependencies; included or required C/C++ runtime, OpenMP and math libraries; inspect ELF dependencies recursively                           |
+| Model-dependent extras      | SentencePiece/protobuf, Pillow, audio libraries, torchvision/torchaudio, or other processors only when required by the supported model and task                                            |
+| Additional science coverage | NumPy first; SciPy, pandas and scikit-learn as separately validated additions, with matching BLAS/LAPACK, OpenMP and Fortran runtimes where required                                       |
+| Download/cache stack        | The selected hub client's HTTP/TLS and filesystem packages, cache locks, resumable downloads, credentials and offline-cache behavior                                                       |
 
 Rust-based `tokenizers` and `safetensors`, C/C++ extensions, and PyTorch's native
 libraries are transitive runtime artifacts even when a user only installs a
@@ -142,7 +276,7 @@ PyTorch Wasm port is separate work and is not implied by providing Clang or Rust
 See the [owned Python architecture](../python/architecture.md) and
 `python-runtime/abi/extension-abi.json` for the current ABI contract.
 
-## Real Linux Ollama installation contract
+#### Real Linux Ollama installation contract
 
 Download a pinned upstream archive for the selected guest architecture, verify
 its recorded digest, and install its binary **and required bundled libraries and
@@ -163,7 +297,7 @@ Linux processes, with backend and version reported to the user. Browser WebGPU
 does not provide CUDA or ROCm to these processes; CPU execution is the first
 target. GPU passthrough/translation is outside this phase.
 
-## Owned compiler and build dependencies
+#### Owned compiler and build dependencies
 
 Separate the machine **running a compiler** from the architecture it **produces**.
 A Linux `clang` executable needs the Linux guest; emitting Wasm does not make the
@@ -194,9 +328,9 @@ Publish recipes, patches, source hashes and target manifests for these toolchain
 Prebuilt runtime packs should remain sufficient for normal users; downloading an
 entire compiler stack must not be required merely to load a model.
 
-## Distribution and dependency resolution
+#### Distribution and dependency resolution
 
-Define a versioned manifest for each pack and the future agent package containing:
+Define a versioned manifest for each pack containing:
 
 - Pack ID/version, execution profile, CPU architecture, OS/libc, Python ABI or
   Wasm ABI as applicable, and minimum runtime capabilities.
@@ -206,7 +340,7 @@ Define a versioned manifest for each pack and the future agent package containin
   readiness checks and supported test matrix.
 - Build-only versus runtime dependencies, optional extras and model assets.
 
-The agent manifest requests these capabilities; the resolver chooses only packs
+A program's manifest requests these capabilities; the resolver chooses only packs
 compatible with its declared profile. Use separate Linux and Wasm package stores,
 and never silently switch execution profiles after an installation failure.
 Provide atomic installs, retry/resume, cache reuse, clean uninstall and rollback
@@ -215,7 +349,7 @@ CORS, worker URLs and cross-origin isolation for SharedArrayBuffer-based paths.
 Record third-party distribution obligations, including kernel/rootfs source and
 notice requirements, before publishing packs through the wheels site.
 
-## Model responsibility and documented limits
+#### Model responsibility and documented limits
 
 The user will supply approximately 120M–200M parameter models; creating and
 uploading them is outside this phase. Validate a compatible small model once one
@@ -231,7 +365,7 @@ Weights alone require roughly parameters × bits-per-weight / 8 bytes, with
 additional memory for the kernel, emulator, runtime, activations, KV cache and
 temporary copies. Resource exhaustion and cancellation must fail cleanly.
 
-## Implementation order and acceptance gates
+#### Implementation order and acceptance gates
 
 1. **Lock the architecture:** select candidate emulator, guest architecture,
    kernel/rootfs and package versions. Inventory the actual binary dependency
@@ -257,5 +391,5 @@ temporary copies. Resource exhaustion and cancellation must fail cleanly.
    installs, restart, cancellation, version conflicts and missing capabilities.
 
 Phase one is complete when these dependency paths are reproducible and their
-tests pass. The later `.sbjs` agent application can then depend on demonstrated
+tests pass. Agents and model servers can then depend on demonstrated
 capabilities instead of assumed Linux command compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandboxedjs",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "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",