Feat execute bash

.gitignore

@@ -52,4 +52,6 @@ plugins/shared/*.js
 plugins/plugin-schema-types.d.ts
 plugins/plugin-schema-types.js
 plugins/host-modules.d.ts
-output-hyperagent**/**
+output-hyperagent**/**scripts/bash-bundle/_tmp_bundle.js
+output-hyperagent-*/
+scripts/bash-bundle/_tmp_bundle.js

Justfile

@@ -148,6 +148,10 @@ setup: ensure-tools install
 build: install
     @echo "✅ Build complete — run 'just start' to launch the agent"
 
+# Rebuild the ha:bash bundle from just-bash (only needed when just-bash updates)
+build-bash:
+    node scripts/bash-bundle/build.mjs
+
 # Build everything in release mode (hyperlight-js, guest runtime, NAPI addon)
 build-release: install-release
     @echo "✅ Release build complete — run 'just start-release' to launch"

README.md

@@ -125,6 +125,7 @@ The sandbox has no direct filesystem, network, shell, or process access. Capabil
 | ---------------- | ---------------------------------------------------------------- |
 | Files            | `fs-read` and `fs-write` plugins with path jails                 |
 | HTTP             | `fetch` plugin with domain allowlists and SSRF checks            |
+| Bash commands    | `execute_bash` — sandboxed pure-JS interpreter (ls, grep, jq, curl, etc.) |
 | Reusable code    | `ha:*` system and user modules                                   |
 | External systems | MCP servers exposed as typed `host:mcp-*` modules                |
 | Bigger jobs      | Profiles that raise limits; profile tools can enable plugin sets |
@@ -235,7 +236,7 @@ MCP servers are not Hyperlight-sandboxed; they run as normal host processes. Rev
 HyperAgent is designed to make generated-code execution less terrifying, not magically safe.
 
 - **Hardware isolation:** JavaScript runs in Hyperlight micro-VMs.
-- **Tool gating:** SDK built-ins like shell, edit, and grep are blocked; the model gets HyperAgent-specific tools.
+- **Tool gating:** SDK built-ins like shell, edit, and grep are blocked; the model gets HyperAgent-specific tools including a sandboxed bash interpreter (`execute_bash`).
 - **Code validation:** Generated JavaScript is checked before execution.
 - **No ambient host access:** Files, network, and external systems require explicit plugins or MCP connections.
 - **Plugin auditing:** Plugin code is audited before use.

builtin-modules/bash.json

@@ -0,0 +1,11 @@
+{
+  "name": "bash",
+  "description": "Sandboxed bash interpreter powered by just-bash. Provides 40+ Unix commands (ls, grep, jq, curl, sed, awk, etc.) running entirely in JavaScript inside the Hyperlight micro-VM.",
+  "author": "system",
+  "mutable": false,
+  "type": "script",
+  "sourceHash": "sha256:31219cbf85cf26d1",
+  "hints": {
+    "overview": "Pure-JS bash interpreter for the sandbox. Used internally by the execute_bash tool — not intended for direct import in handlers."
+  }
+}

docs/ARCHITECTURE.md

@@ -12,7 +12,7 @@ This document describes Hyperagent's system architecture.
 │    streaming | infinite sessions | multi-model        │
 ├───────────────────────────────────────────────────────┤
 │                  Tool Gating Layer                    │
-│    (blocks all SDK built-in tools like bash/edit)     │
+│    (blocks SDK built-in tools like edit/grep/write)    │
 ├───────────────────────────────────────────────────────┤
 │                   Custom Tools                        │
 │    register_handler, execute_javascript, ask_user     │
@@ -51,8 +51,9 @@ The main agent file handles:
 ### Tool Gating (`src/agent/tool-gating.ts`)
 
 Intercepts all tool calls from the LLM and:
-- Blocks most GitHub Copilot SDK built-in tools (bash, edit, grep, read, write)
-- Allows only registered custom tools
+- Blocks most GitHub Copilot SDK built-in tools (edit, grep, read, write)
+- Allows only registered custom tools (including `execute_bash` which runs
+  a sandboxed pure-JS bash interpreter, not a host shell)
 - Logs blocked attempts for debugging
 
 ### Sandbox Tool (`src/sandbox/tool.js`)

docs/HOW-IT-WORKS.md

@@ -105,9 +105,10 @@ All code runs in Hyperlight micro-VMs:
 
 The LLM cannot escape the sandbox:
 
-- Most GitHub Copilot SDK built-in tools (bash, edit, grep, read, write) are **blocked** the exceptions being `ask_user` (questions) and `report_intent` (protocol)
-- All functionality comes from custom Hyperagent tools (`execute_javascript`, `register_handler`, etc.)
-- Even if the LLM tries to use bash, it won't work
+- Most GitHub Copilot SDK built-in tools (edit, grep, read, write) are **blocked** the exceptions being `ask_user` (questions) and `report_intent` (protocol)
+- The SDK's built-in bash tool is also blocked — HyperAgent provides its own `execute_bash` which runs a pure-JS bash interpreter inside the sandbox
+- All functionality comes from custom Hyperagent tools (`execute_javascript`, `register_handler`, `execute_bash`, etc.)
+- Even if the LLM tries to use the SDK's bash, it won't work — but `execute_bash` is available for shell-style data processing
 
 ### Code Validation
 

docs/SECURITY.md

@@ -12,13 +12,15 @@ Hyperagent implements defense-in-depth security through multiple layers. No sing
 
 The Copilot SDK provides built-in tools (bash, edit, grep, read, write) that would allow arbitrary code execution. Hyperagent blocks most of them, allowing only safe tools like `ask_user` (for user interaction) and `report_intent` (protocol).
 
+Hyperagent provides its own `execute_bash` tool — a pure-JS bash interpreter (just-bash) running **inside** the Hyperlight sandbox. This is NOT the SDK's bash tool and does NOT have host shell access. It supports ~50 common commands (ls, grep, jq, curl, sed, awk, etc.) with the same isolation guarantees as `execute_javascript`.
+
 **Implementation** (`src/agent/tool-gating.ts`):
 - Intercepts all tool calls from the LLM
 - Maintains an allowlist of custom tools plus safe SDK tools
 - Rejects any tool not on the allowlist
 - Logs blocked attempts for debugging
 
-**Effect**: The LLM cannot escape the sandbox by calling SDK tools. Even if prompted to "run bash", the tool call is rejected.
+**Effect**: The LLM cannot escape the sandbox by calling SDK tools. Even if prompted to "run bash", the SDK's bash tool is rejected. The sandboxed `execute_bash` runs inside a micro-VM with no host shell access.
 
 ### Layer 2: Hyperlight Micro-VMs
 

docs/USAGE.md

@@ -108,13 +108,15 @@ Toggle options at runtime without restarting. Type `/` and press Tab for complet
 
 ## LLM Tools
 
-The agent registers custom tools that the LLM can call. All SDK built-in tools
-(bash, grep, edit, etc.) are **blocked** by the tool gating layer.
+The agent registers custom tools that the LLM can call. Most SDK built-in tools
+(grep, edit, etc.) are **blocked** by the tool gating layer. The SDK's bash tool
+is also blocked — `execute_bash` is Hyperagent's own sandboxed bash interpreter.
 
 | Tool                 | Purpose                                                              |
 | -------------------- | -------------------------------------------------------------------- |
 | `register_handler`   | Register named JavaScript handler code in the sandbox                |
 | `execute_javascript` | Execute a registered handler with optional event data                |
+| `execute_bash`       | Run bash commands in a sandboxed pure-JS interpreter (just-bash)     |
 | `delete_handler`     | Remove a handler from the sandbox                                    |
 | `get_handler_source` | Retrieve handler source for inspection or editing                    |
 | `edit_handler`       | Surgically edit an existing handler                                  |