diff --git a/crates/bashkit-eval/README.md b/crates/bashkit-eval/README.md index 14af27df0..97ec75670 100644 --- a/crates/bashkit-eval/README.md +++ b/crates/bashkit-eval/README.md @@ -1,4 +1,4 @@ -# BashKit Eval +# Bashkit Eval LLM evaluation harness for bashkit tool usage. Measures how well models use bashkit's bash tool in agentic workloads. diff --git a/crates/bashkit/docs/threat-model.md b/crates/bashkit/docs/threat-model.md index 1a059a370..0adacc7eb 100644 --- a/crates/bashkit/docs/threat-model.md +++ b/crates/bashkit/docs/threat-model.md @@ -563,8 +563,8 @@ Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem. | Shell escape (TM-PY-004) | `os.system()` | Monty has no os.system/subprocess | MITIGATED | | Real FS access (TM-PY-005) | `open()` | Monty has no open() builtin | MITIGATED | | Error info leak (TM-PY-006) | Errors go to stdout | Errors go to stderr, not stdout | MITIGATED | -| Real FS read (TM-PY-015) | `Path.read_text()` | VFS bridge reads only from BashKit VFS | MITIGATED | -| Real FS write (TM-PY-016) | `Path.write_text()` | VFS bridge writes only to BashKit VFS | MITIGATED | +| Real FS read (TM-PY-015) | `Path.read_text()` | VFS bridge reads only from Bashkit VFS | MITIGATED | +| Real FS write (TM-PY-016) | `Path.write_text()` | VFS bridge writes only to Bashkit VFS | MITIGATED | | Path traversal (TM-PY-017) | `../../etc/passwd` | VFS path normalization | MITIGATED | | Bash/Python VFS isolation (TM-PY-018) | Cross-tenant access | Shared VFS by design; no cross-tenant | MITIGATED | | Crash on missing file (TM-PY-019) | Missing file panic | FileNotFoundError raised, not panic | MITIGATED | @@ -581,7 +581,7 @@ Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem. **Architecture:** ```text -Python code → Monty VM → OsCall pause → BashKit VFS bridge → resume +Python code → Monty VM → OsCall pause → Bashkit VFS bridge → resume ``` Monty runs directly in the host process. Resource limits (memory, allocations, diff --git a/crates/bashkit/examples/python_scripts.rs b/crates/bashkit/examples/python_scripts.rs index fdc55da44..db553e965 100644 --- a/crates/bashkit/examples/python_scripts.rs +++ b/crates/bashkit/examples/python_scripts.rs @@ -1,9 +1,9 @@ //! Python Scripts Example //! -//! Demonstrates running Python code inside BashKit's virtual environment using the +//! Demonstrates running Python code inside Bashkit's virtual environment using the //! embedded Monty interpreter. Python runs entirely in-memory with //! resource limits. Python pathlib.Path operations are bridged to -//! BashKit's virtual filesystem. +//! Bashkit's virtual filesystem. //! //! Run with: cargo run --features python --example python_scripts @@ -11,7 +11,7 @@ use bashkit::Bash; #[tokio::main] async fn main() -> anyhow::Result<()> { - println!("=== BashKit Python Integration ===\n"); + println!("=== Bashkit Python Integration ===\n"); let mut bash = Bash::builder() .python() diff --git a/crates/bashkit/examples/typescript_scripts.rs b/crates/bashkit/examples/typescript_scripts.rs index 8cf9c2ebd..8da85351f 100644 --- a/crates/bashkit/examples/typescript_scripts.rs +++ b/crates/bashkit/examples/typescript_scripts.rs @@ -1,6 +1,6 @@ //! TypeScript Scripts Example //! -//! Demonstrates running TypeScript code inside BashKit's virtual environment +//! Demonstrates running TypeScript code inside Bashkit's virtual environment //! using the embedded ZapCode interpreter. TypeScript runs entirely in-memory //! with resource limits. VFS operations are bridged via external function //! suspend/resume. @@ -11,7 +11,7 @@ use bashkit::Bash; #[tokio::main] async fn main() -> anyhow::Result<()> { - println!("=== BashKit TypeScript Integration ===\n"); + println!("=== Bashkit TypeScript Integration ===\n"); let mut bash = Bash::builder().typescript().build(); diff --git a/crates/bashkit/src/builtins/python.rs b/crates/bashkit/src/builtins/python.rs index 0f86554a0..6a82df4cc 100644 --- a/crates/bashkit/src/builtins/python.rs +++ b/crates/bashkit/src/builtins/python.rs @@ -9,7 +9,7 @@ //! # Overview //! //! Virtual Python execution with resource limits and VFS access. -//! Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem +//! Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem //! via Monty's OsCall pause/resume mechanism. No real filesystem or network access. //! //! Supports: `python -c "code"`, `python script.py`, stdin piping. @@ -181,7 +181,7 @@ impl std::fmt::Debug for PythonExternalFns { /// The python/python3 builtin command. /// /// Executes Python code using the embedded Monty interpreter (pydantic/monty). -/// Python `pathlib.Path` operations are bridged to BashKit's VFS — files +/// Python `pathlib.Path` operations are bridged to Bashkit's VFS — files /// created by bash (`cat > file`) are readable from Python, and vice versa. /// /// # Usage @@ -456,7 +456,7 @@ impl Builtin for Python { /// Execute Python code via Monty with resource limits and VFS bridging. /// /// Uses Monty's start/resume API: execution pauses at filesystem operations -/// (OsCall), we bridge them to BashKit's VFS, then resume. +/// (OsCall), we bridge them to Bashkit's VFS, then resume. async fn run_python( code: &str, filename: &str, @@ -598,7 +598,7 @@ async fn run_python( } // --------------------------------------------------------------------------- -// VFS bridging: Monty OsCall → BashKit FileSystem +// VFS bridging: Monty OsCall → Bashkit FileSystem // --------------------------------------------------------------------------- /// Dispatch a Monty OsCall to the appropriate VFS operation. @@ -768,7 +768,7 @@ async fn handle_os_call( } } OsFunction::Resolve | OsFunction::Absolute => { - // No symlink resolution in BashKit VFS; just return absolute path + // No symlink resolution in Bashkit VFS; just return absolute path ExtFunctionResult::Return(MontyObject::Path(path.to_string_lossy().to_string())) } // Getenv/GetEnviron handled above @@ -797,7 +797,7 @@ fn resolve_python_path(path_str: &str, cwd: &Path) -> PathBuf { } } -/// Map a BashKit VFS error to a Python exception via ExtFunctionResult. +/// Map a Bashkit VFS error to a Python exception via ExtFunctionResult. fn map_vfs_error(e: crate::Error, path: &Path) -> ExtFunctionResult { let msg = e.to_string(); let path_str = path.display().to_string(); diff --git a/crates/bashkit/src/builtins/typescript.rs b/crates/bashkit/src/builtins/typescript.rs index 8df06d159..bbd19ca2c 100644 --- a/crates/bashkit/src/builtins/typescript.rs +++ b/crates/bashkit/src/builtins/typescript.rs @@ -642,7 +642,7 @@ impl Builtin for TypeScript { /// Execute TypeScript code via ZapCode with resource limits and VFS bridging. /// /// Uses ZapCode's start/resume API: execution suspends at external function calls -/// (VFS operations), we bridge them to BashKit's VFS, then resume. +/// (VFS operations), we bridge them to Bashkit's VFS, then resume. async fn run_typescript( code: &str, fs: Arc, @@ -769,7 +769,7 @@ async fn handle_external_call( } // --------------------------------------------------------------------------- -// VFS bridging: ZapCode external functions → BashKit FileSystem +// VFS bridging: ZapCode external functions → Bashkit FileSystem // --------------------------------------------------------------------------- /// Extract a path string from the first arg, resolve relative to cwd. diff --git a/crates/bashkit/src/credential.rs b/crates/bashkit/src/credential.rs index ada659ab8..c3382bc58 100644 --- a/crates/bashkit/src/credential.rs +++ b/crates/bashkit/src/credential.rs @@ -132,7 +132,7 @@ const PLACEHOLDER_PREFIX: &str = "bk_placeholder_"; /// # Security /// /// The placeholder acts like a bearer capability inside scripts: if a script -/// sends the placeholder value to a URL matching a credential rule, BashKit +/// sends the placeholder value to a URL matching a credential rule, Bashkit /// injects the real credential-owned header. The token therefore must come /// from a security-grade RNG so it cannot be predicted, brute-forced, or /// reproduced from observed program state. diff --git a/crates/bashkit/tests/threat_model_tests.rs b/crates/bashkit/tests/threat_model_tests.rs index a74abd4e8..b345f1837 100644 --- a/crates/bashkit/tests/threat_model_tests.rs +++ b/crates/bashkit/tests/threat_model_tests.rs @@ -1430,7 +1430,7 @@ mod python_security { assert_ne!(result.exit_code, 0); } - /// TM-PY-014: Python with BashKit resource limits + /// TM-PY-014: Python with Bashkit resource limits #[tokio::test] async fn threat_python_respects_bash_limits() { let limits = ExecutionLimits::new().max_commands(5); @@ -1448,7 +1448,7 @@ mod python_security { // --- VFS Security Tests --- - /// TM-PY-015: Python VFS reads only from BashKit's virtual filesystem + /// TM-PY-015: Python VFS reads only from Bashkit's virtual filesystem #[tokio::test] async fn threat_python_vfs_no_real_fs() { let mut bash = bash_with_python(); @@ -1540,7 +1540,7 @@ mod python_security { ); } - /// TM-PY-020: Python VFS operations respect BashKit sandbox boundaries + /// TM-PY-020: Python VFS operations respect Bashkit sandbox boundaries #[tokio::test] async fn threat_python_vfs_no_network() { let mut bash = bash_with_python(); @@ -4172,7 +4172,7 @@ mod typescript_security { assert_ne!(result.exit_code, 0, "Stack overflow should not succeed"); } - /// TM-TS-005: TypeScript VFS reads only from BashKit VFS + /// TM-TS-005: TypeScript VFS reads only from Bashkit VFS #[tokio::test] async fn threat_ts_vfs_no_real_fs() { let mut bash = bash_with_ts(); diff --git a/crates/bashkit/tests/typescript_security_tests.rs b/crates/bashkit/tests/typescript_security_tests.rs index f70467559..c402dce7a 100644 --- a/crates/bashkit/tests/typescript_security_tests.rs +++ b/crates/bashkit/tests/typescript_security_tests.rs @@ -315,7 +315,7 @@ mod whitebox_vfs_security { .await .unwrap(); // Verify file doesn't exist on real host (we're in VFS) - // The bash `test -f` in BashKit also operates on VFS, so this + // The bash `test -f` in Bashkit also operates on VFS, so this // verifies the write went to VFS, not a real assertion about host fs let r = bash.exec("cat /tmp/ts_escape_test").await.unwrap(); assert_eq!(r.exit_code, 0); @@ -415,7 +415,7 @@ mod whitebox_error_handling { mod whitebox_bash_integration { use super::*; - /// TM-TS-018: TypeScript respects BashKit command limits + /// TM-TS-018: TypeScript respects Bashkit command limits #[tokio::test] async fn threat_ts_respects_bash_limits() { let limits = ExecutionLimits::new().max_commands(5); diff --git a/specs/python-builtin.md b/specs/python-builtin.md index bcd49291b..a04122510 100644 --- a/specs/python-builtin.md +++ b/specs/python-builtin.md @@ -10,7 +10,7 @@ Implemented (experimental) ## Decision -BashKit provides sandboxed Python execution via `python` and `python3` builtins, +Bashkit provides sandboxed Python execution via `python` and `python3` builtins, powered by the [Monty](https://github.com/pydantic/monty) embedded Python interpreter written in Rust. @@ -82,7 +82,7 @@ python3 -V ### Resource Limits -Monty enforces its own resource limits independent of BashKit's shell limits. +Monty enforces its own resource limits independent of Bashkit's shell limits. All limits are configurable via `PythonLimits`: | Limit | Default | Builder Method | Purpose | @@ -143,7 +143,7 @@ Monty implements a subset of Python 3.12: ### VFS Bridging -Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem +Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem via Monty's OsCall pause/resume mechanism. This enables Python code to read and write files that are shared with the bash environment. @@ -181,16 +181,16 @@ python3 -c "import os; print(os.getenv('HOME'))" **Architecture:** ``` -Python code → Monty VM → OsCall(ReadText, path) → BashKit VFS → resume +Python code → Monty VM → OsCall(ReadText, path) → Bashkit VFS → resume ``` Monty pauses execution at filesystem operations, yields an `OsCall` event -with the operation type and arguments, BashKit bridges it to the VFS, and +with the operation type and arguments, Bashkit bridges it to the VFS, and resumes execution with the result (or a Python exception). > **Note:** Monty 0.0.10+ includes native filesystem mounting (`MountTable`, > `MountDir`, `MountMode`) that can handle file operations directly against -> host directories. BashKit uses the OsCall bridge instead because our VFS is +> host directories. Bashkit uses the OsCall bridge instead because our VFS is > in-memory and may not be backed by host directories. The native mount system > is suited for real-filesystem use cases where Monty is used standalone. @@ -277,11 +277,11 @@ by-design consistent with all other builtins. Use single quotes to prevent expansion: `python3 -c 'print("hello")'`. #### Threat: Resource exhaustion -Monty enforces independent resource limits. Even if BashKit's shell limits +Monty enforces independent resource limits. Even if Bashkit's shell limits are generous, Python code cannot exceed Monty's allocation/time/memory caps. #### Threat: Sandbox escape via filesystem -All `pathlib.Path` operations go through BashKit's virtual filesystem. +All `pathlib.Path` operations go through Bashkit's virtual filesystem. Python code cannot access the real host filesystem. `/etc/passwd` in Python reads from VFS (where it doesn't exist), not the host. @@ -312,13 +312,13 @@ a hint to `help()` and `system_prompt()` documenting its limitations: > python/python3: Embedded Python (Monty). Stdlib: math, pathlib, os.getenv, sys, typing. File I/O via pathlib.Path only (no open()). No HTTP/network. No classes. No third-party imports. -Regex module `re` is intentionally disabled in BashKit due to catastrophic +Regex module `re` is intentionally disabled in Bashkit due to catastrophic backtracking DoS risk in untrusted code execution. This uses the general `Builtin::llm_hint()` mechanism — any builtin can provide hints that are automatically deduplicated and included in LLM-facing documentation. -### Integration with BashKit +### Integration with Bashkit - `python`/`python3` both map to the same builtin - Works in pipelines: `echo "data" | python3 -c "import sys; ..."` diff --git a/specs/threat-model.md b/specs/threat-model.md index ba55c2d6a..5f570d40a 100644 --- a/specs/threat-model.md +++ b/specs/threat-model.md @@ -1662,19 +1662,19 @@ The following components are fuzz-tested for robustness: > undiscovered crash or security bugs. Resource limits are enforced by Monty's > runtime. This integration should be treated as experimental. -BashKit embeds the Monty Python interpreter (pydantic/monty) with VFS bridging. -Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem via +Bashkit embeds the Monty Python interpreter (pydantic/monty) with VFS bridging. +Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem via Monty's OsCall pause/resume mechanism. This section covers threats specific to the Python builtin. ### Architecture ``` -Python code → Monty VM → OsCall pause → BashKit VFS bridge → resume +Python code → Monty VM → OsCall pause → Bashkit VFS bridge → resume ``` Monty never touches the real filesystem. All `Path.*` operations yield `OsCall` -events that BashKit intercepts and dispatches to the VFS. +events that Bashkit intercepts and dispatches to the VFS. ### Threats @@ -1686,8 +1686,8 @@ events that BashKit intercepts and dispatches to the VFS. | TM-PY-004 | Shell escape via os.system/subprocess | Critical | Monty has no os.system/subprocess implementation | `threat_python_no_os_operations` | | TM-PY-005 | Real filesystem access via open() | Critical | Monty has no open() builtin | `threat_python_no_filesystem` | | TM-PY-006 | Error info leakage via stdout | Medium | Errors go to stderr, not stdout | `threat_python_error_isolation` | -| TM-PY-015 | Real filesystem read via pathlib | Critical | VFS bridge reads only from BashKit VFS, not host | `threat_python_vfs_no_real_fs` | -| TM-PY-016 | Real filesystem write via pathlib | Critical | VFS bridge writes only to BashKit VFS | `threat_python_vfs_write_sandboxed` | +| TM-PY-015 | Real filesystem read via pathlib | Critical | VFS bridge reads only from Bashkit VFS, not host | `threat_python_vfs_no_real_fs` | +| TM-PY-016 | Real filesystem write via pathlib | Critical | VFS bridge writes only to Bashkit VFS | `threat_python_vfs_write_sandboxed` | | TM-PY-017 | Path traversal (../../etc/passwd) | High | VFS resolves paths within sandbox boundaries | `threat_python_vfs_path_traversal` | | TM-PY-018 | Bash/Python VFS isolation breach | Medium | Shared VFS by design; no cross-tenant access | `threat_python_vfs_bash_python_isolation` | | TM-PY-019 | Crash on missing file | Medium | FileNotFoundError raised, not panic | `threat_python_vfs_error_handling` | @@ -1737,7 +1737,7 @@ and this information has low sensitivity. No filesystem or network access is gra ### VFS Bridge Security Properties -1. **No real filesystem access**: All Path operations go through BashKit's VFS. +1. **No real filesystem access**: All Path operations go through Bashkit's VFS. `/etc/passwd` in Python reads from VFS, not the host. 2. **Shared VFS with bash**: Files written by `echo > file` are readable by Python's `Path(file).read_text()`, and vice versa. This is intentional. @@ -1746,7 +1746,7 @@ and this information has low sensitivity. No filesystem or network access is gra 4. **Error mapping**: VFS errors are mapped to standard Python exceptions (FileNotFoundError, IsADirectoryError, etc.), not raw panics. 5. **Resource isolation**: Monty's own limits (time, memory, allocations, - recursion) are enforced independently of BashKit's shell limits. + recursion) are enforced independently of Bashkit's shell limits. ### Direct Integration @@ -1791,7 +1791,7 @@ filesystem. > explicit `.typescript()` call on the builder. Without both, these commands > are unavailable. -BashKit embeds the ZapCode TypeScript interpreter (zapcode-core) with VFS +Bashkit embeds the ZapCode TypeScript interpreter (zapcode-core) with VFS bridging via external function suspend/resume. TypeScript code can access the virtual filesystem through registered external functions. This section covers threats specific to the TypeScript builtin. @@ -1799,11 +1799,11 @@ threats specific to the TypeScript builtin. ### Architecture ``` -TypeScript code → ZapCode VM → ExternalFn suspend → BashKit VFS bridge → resume +TypeScript code → ZapCode VM → ExternalFn suspend → Bashkit VFS bridge → resume ``` ZapCode never touches the real filesystem. External function calls suspend the -VM, BashKit intercepts and dispatches to the VFS, then resumes execution. +VM, Bashkit intercepts and dispatches to the VFS, then resumes execution. ### Opt-in Design @@ -1823,20 +1823,20 @@ are not available even if compiled. This matches the Python builtin pattern. | TM-TS-002 | Memory exhaustion via large allocation | High | ZapCode max_memory (64MB) + max_allocations (1M) | `threat_ts_memory_exhaustion` | | TM-TS-003 | Stack overflow via deep recursion | High | ZapCode max_stack_depth (512) | `threat_ts_stack_overflow` | | TM-TS-004 | Allocation bomb (many small objects) | High | ZapCode max_allocations (1M) | `threat_ts_allocation_bomb` | -| TM-TS-005 | Real filesystem access via VFS | Critical | VFS bridge reads only from BashKit VFS, not host | `threat_ts_vfs_no_real_fs` | -| TM-TS-006 | VFS write escapes to host | Critical | VFS bridge writes only to BashKit VFS | `threat_ts_vfs_write_sandboxed` | +| TM-TS-005 | Real filesystem access via VFS | Critical | VFS bridge reads only from Bashkit VFS, not host | `threat_ts_vfs_no_real_fs` | +| TM-TS-006 | VFS write escapes to host | Critical | VFS bridge writes only to Bashkit VFS | `threat_ts_vfs_write_sandboxed` | | TM-TS-007 | Path traversal (../../etc/passwd) | High | VFS resolves paths within sandbox boundaries | `threat_ts_vfs_path_traversal` | | TM-TS-008 | Bash/TypeScript VFS data corruption | Medium | Shared VFS by design; no cross-tenant access | `threat_ts_vfs_bash_ts_shared` | | TM-TS-009 | Crash on missing file | Medium | Error string returned, not panic | `threat_ts_vfs_error_handling` | | TM-TS-010 | VFS mkdir escape | Medium | mkdir operates only in VFS | `threat_ts_vfs_mkdir_sandboxed` | -| TM-TS-011 | VFS operations escape to host /tmp | Critical | All operations go through BashKit VFS | `threat_ts_vfs_no_host_escape` | +| TM-TS-011 | VFS operations escape to host /tmp | Critical | All operations go through Bashkit VFS | `threat_ts_vfs_no_host_escape` | | TM-TS-012 | Error info leakage via stdout | Medium | Errors go to stderr, not stdout | `threat_ts_error_isolation` | | TM-TS-013 | Syntax error crashes host | Medium | Non-zero exit code, error on stderr | `threat_ts_syntax_error_exit` | | TM-TS-014 | Exit code not propagated | Low | Exit code flows to bash $? | `threat_ts_exit_code_propagation` | | TM-TS-015 | Empty code crashes | Low | Non-zero exit, error message | `threat_ts_empty_code` | | TM-TS-016 | Pipeline error leakage | Medium | Errors on stderr, not passed to pipe | `threat_ts_pipeline_error_handling` | | TM-TS-017 | Unknown options accepted | Low | Unknown flags return non-zero | `threat_ts_unknown_options` | -| TM-TS-018 | TypeScript bypasses BashKit limits | Medium | Command budget still enforced | `threat_ts_respects_bash_limits` | +| TM-TS-018 | TypeScript bypasses Bashkit limits | Medium | Command budget still enforced | `threat_ts_respects_bash_limits` | | TM-TS-019 | Command subst captures errors | Medium | Only stdout captured by $() | `threat_ts_subst_captures_stdout` | | TM-TS-020 | Bash var expansion injection | Medium | By-design; use single quotes to prevent | `threat_ts_variable_expansion` | | TM-TS-021 | Shell command execution from TS | Critical | No process/subprocess/exec globals | `threat_ts_no_shell_exec` | @@ -1860,7 +1860,7 @@ ZapCode blocks these at the language level (not just runtime): ### VFS Bridge Security Properties -1. **No real filesystem access**: All VFS-bridged functions go through BashKit's +1. **No real filesystem access**: All VFS-bridged functions go through Bashkit's VFS. `/etc/passwd` in TypeScript reads from VFS, not the host. 2. **Shared VFS with bash**: Files written by `echo > file` are readable by TypeScript's `readFile()`, and vice versa. This is intentional. @@ -1868,7 +1868,7 @@ ZapCode blocks these at the language level (not just runtime): Path traversal (`../..`) is constrained by VFS path normalization. 4. **Error handling**: VFS errors return error strings to TypeScript, not panics. 5. **Resource isolation**: ZapCode's own limits (time, memory, stack, allocations) - are enforced independently of BashKit's shell limits. + are enforced independently of Bashkit's shell limits. ### Supported VFS Operations diff --git a/specs/zapcode-runtime.md b/specs/zapcode-runtime.md index c6ea0ee55..da8bf390e 100644 --- a/specs/zapcode-runtime.md +++ b/specs/zapcode-runtime.md @@ -9,7 +9,7 @@ Implemented (experimental) ## Decision -BashKit provides sandboxed TypeScript/JavaScript execution via `typescript`, +Bashkit provides sandboxed TypeScript/JavaScript execution via `typescript`, `ts`, `node`, `deno`, and `bun` builtins, powered by the [ZapCode](https://github.com/TheUncharted/zapcode) embedded TypeScript interpreter written in Rust. @@ -114,7 +114,7 @@ The `-c` and `-e` flags are both accepted by all aliases for convenience. ### Resource Limits -ZapCode enforces its own resource limits independent of BashKit's shell limits. +ZapCode enforces its own resource limits independent of Bashkit's shell limits. All limits are configurable via `TypeScriptLimits`: | Limit | Default | Builder Method | Purpose | @@ -162,7 +162,7 @@ ZapCode implements a TypeScript/JavaScript subset: ### VFS Bridging -TypeScript code can access BashKit's virtual filesystem through external +TypeScript code can access Bashkit's virtual filesystem through external functions registered by the builtin. These functions are available as globals in the TypeScript environment: @@ -193,10 +193,10 @@ ts -c "const entries = await readDir('/tmp'); console.log(entries)" **Architecture:** ``` -TS code → ZapCode VM → ExternalFn("readFile", [path]) → BashKit VFS → resume +TS code → ZapCode VM → ExternalFn("readFile", [path]) → Bashkit VFS → resume ``` -ZapCode suspends execution at external function calls, BashKit bridges the +ZapCode suspends execution at external function calls, Bashkit bridges the call to the VFS, and resumes execution with the result. **Limitation: stdout after VFS calls.** `ZapcodeSnapshot::resume()` returns @@ -273,12 +273,12 @@ by-design consistent with all other builtins. Use single quotes to prevent expansion: `ts -c 'console.log("hello")'`. #### Threat: Resource exhaustion -ZapCode enforces independent resource limits. Even if BashKit's shell limits +ZapCode enforces independent resource limits. Even if Bashkit's shell limits are generous, TypeScript code cannot exceed ZapCode's time/memory/stack caps. #### Threat: Sandbox escape via filesystem TypeScript code has no direct filesystem access. VFS-bridged functions go -through BashKit's virtual filesystem. `/etc/passwd` reads from VFS, not host. +through Bashkit's virtual filesystem. `/etc/passwd` reads from VFS, not host. #### Threat: Sandbox escape via eval/import ZapCode blocks `eval()`, `Function()`, `import`, and `require` at the language @@ -305,7 +305,7 @@ contributes a hint to `help()` and `system_prompt()`: > File I/O via readFile()/writeFile() async functions. No npm/import/require. > No HTTP/network. No eval(). -### Integration with BashKit +### Integration with Bashkit - `ts`/`typescript`/`node`/`deno`/`bun` all map to the same builtin - Works in pipelines: `echo "data" | ts -c "..."`