Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

src/js-host-api/examples/mcp-server/README.md

@@ -298,7 +298,7 @@ cd src\js-host-api\examples\mcp-server
 | `--cpu-timeout <ms>`| `-CpuTimeout <ms>`  | CPU time limit per execution (default: 1000ms)           |
 | `--wall-timeout <ms>`| `-WallTimeout <ms>`| Wall-clock backstop per execution (default: 5000ms)      |
 | `--heap-size <MB>`  | `-HeapSize <MB>`    | Guest heap size (default: 16MB)                          |
-| `--stack-size <MB>` | `-StackSize <MB>`   | Guest stack size (default: 1MB)                          |
+| `--scratch-size <MB>` | `-ScratchSize <MB>`   | Guest scratch size (default: 1MB)                          |
 
 **What the script does:**
 
@@ -496,7 +496,7 @@ and return the result.
 
 ### 🔢 Mathematics
 
-> **"Calculate π to 50 decimal places using the Bailey–Borwein–Plouffe formula"**
+> **"Calculate π to 50 decimal places using Machin's formula"**
 >
 > Tests: BigInt arithmetic, series computation, precision handling
 
@@ -540,7 +540,7 @@ and return the result.
 >
 > Tests: Complex number arithmetic, nested loops, character mapping
 
-> **"Generate a maze using recursive backtracking on an 21×21 grid and render it as ASCII"**
+> **"Generate a maze using recursive backtracking on a 21×21 grid and render it as ASCII"**
 >
 > Tests: Graph traversal, random selection, 2D grid manipulation
 
@@ -634,7 +634,7 @@ The Hyperlight sandbox provides **hardware-level isolation**:
 - 🌐 **No network access** — can't make HTTP requests
 - 🖥️ **No host access** — can't access environment variables, processes, or system calls
 - ⏱️ **CPU bounded** — configurable limit (default 1000ms), enforced by the hypervisor
-- 💾 **Memory bounded** — configurable (default 16MB heap, 1MB stack)
+- 💾 **Memory bounded** — configurable (default 16MB heap, 1MB scratch)
 - 🔄 **Automatic recovery** — sandbox rebuilds after failures
 
 This makes it safe to execute untrusted, AI-generated code.
@@ -646,7 +646,7 @@ This makes it safe to execute untrusted, AI-generated code.
 | `HYPERLIGHT_CPU_TIMEOUT_MS`    | `1000`   | Maximum CPU time per execution (milliseconds). The hypervisor hard-kills the guest when exceeded. |
 | `HYPERLIGHT_WALL_TIMEOUT_MS`   | `5000`   | Maximum wall-clock time per execution (milliseconds). Backstop for edge cases where CPU time alone doesn't catch the issue. |
 | `HYPERLIGHT_HEAP_SIZE_MB`      | `16`     | Guest heap size in megabytes. Increase for memory-heavy computations (large arrays, BigInt work). |
-| `HYPERLIGHT_STACK_SIZE_MB`     | `1`      | Guest stack size in megabytes. Increase for deeply recursive algorithms. |
+| `HYPERLIGHT_SCRATCH_SIZE_MB`     | `1`      | Guest scratch size in megabytes. Increase for deeply recursive algorithms. |
 | `HYPERLIGHT_TIMING_LOG`        | —        | Path to a file. When set, the server appends one JSON line per tool call with a timing breakdown (init, setup, compile, snapshot, execute, total). Used by the demo script to show model vs. tool time. |
 | `HYPERLIGHT_CODE_LOG`          | —        | Path to a file. When set, the server writes the received JavaScript source code on each tool call. Used by the demo script's `--show-code` flag. |
 
@@ -700,7 +700,7 @@ The code exceeded the CPU time limit (default: 1000ms). Options:
 
 Check that:
 
-1. Node.js >= 18 is installed
+1. Node.js >= 20 is installed
 2. The native module is built (`ls src/js-host-api/js-host-api.*.node`)
 3. Dependencies are installed (`cd examples/mcp-server && npm install`)
 

src/js-host-api/examples/mcp-server/demo-copilot-cli.ps1

@@ -39,8 +39,8 @@
 .PARAMETER HeapSize
     Guest heap size in megabytes (default: 16).
 
-.PARAMETER StackSize
-    Guest stack size in megabytes (default: 1).
+.PARAMETER ScratchSize
+    Guest scratch size in megabytes (default: 1).
 
 .EXAMPLE
     .\demo-copilot-cli.ps1
@@ -94,7 +94,7 @@ param(
     [int]$HeapSize = $(if ($env:HYPERLIGHT_HEAP_SIZE_MB) { [int]$env:HYPERLIGHT_HEAP_SIZE_MB } else { 16 }),
 
     [ValidateRange(1, [int]::MaxValue)]
-    [int]$StackSize = $(if ($env:HYPERLIGHT_STACK_SIZE_MB) { [int]$env:HYPERLIGHT_STACK_SIZE_MB } else { 1 })
+    [int]$ScratchSize = $(if ($env:HYPERLIGHT_SCRATCH_SIZE_MB) { [int]$env:HYPERLIGHT_SCRATCH_SIZE_MB } else { 1 })
 )
 
 # ── Strict Mode ──────────────────────────────────────────────────────
@@ -251,7 +251,7 @@ function Build-McpJson {
     $env:HYPERLIGHT_CPU_TIMEOUT_MS  = $CpuTimeout
     $env:HYPERLIGHT_WALL_TIMEOUT_MS = $WallTimeout
     $env:HYPERLIGHT_HEAP_SIZE_MB    = $HeapSize
-    $env:HYPERLIGHT_STACK_SIZE_MB   = $StackSize
+    $env:HYPERLIGHT_SCRATCH_SIZE_MB   = $ScratchSize
 
     $config = [ordered]@{
         mcpServers = [ordered]@{
@@ -277,16 +277,17 @@ function Build-McpServerEntry {
         HYPERLIGHT_CPU_TIMEOUT_MS  = [string]$CpuTimeout
         HYPERLIGHT_WALL_TIMEOUT_MS = [string]$WallTimeout
         HYPERLIGHT_HEAP_SIZE_MB    = [string]$HeapSize
-        HYPERLIGHT_STACK_SIZE_MB   = [string]$StackSize
+        HYPERLIGHT_SCRATCH_SIZE_MB   = [string]$ScratchSize
     }
 
     if ($ForInstall) {
-        # Permanent install: use fixed well-known paths so Copilot can
-        # spawn the server with predictable log locations.
+        # Permanent install: include timing log at a fixed well-known path.
+        # Code logging is intentionally omitted from permanent installs —
+        # it would persist all executed JS to disk by default, which is a
+        # privacy concern and can grow unbounded.
         # "Roads? Where we're going, we don't need roads." — Back to the Future (1985)
         $tempDir = [System.IO.Path]::GetTempPath()
         $envHash['HYPERLIGHT_TIMING_LOG'] = (Join-Path $tempDir 'hyperlight-timing.jsonl') -replace '\\', '/'
-        $envHash['HYPERLIGHT_CODE_LOG']   = (Join-Path $tempDir 'hyperlight-code.js') -replace '\\', '/'
     } else {
         # Per-session: use the current env vars (random per-session paths
         # set by the script to avoid clobbering between concurrent runs).
@@ -457,29 +458,6 @@ INSTRUCTIONS: You have an MCP tool called 'execute_javascript' from the 'hyperli
 
     # Write the prompt to a temp file and pass via @file to avoid PS7's
     # native-command argument mangling with multi-line here-strings.
-    # The copilot CLI reads -p @file the same as -p "string".
-    # "Nobody puts Baby in a corner." — Dirty Dancing (1987)
-    $promptFile = Join-Path ([System.IO.Path]::GetTempPath()) "hyperlight-prompt-$PID-$(Get-Random).txt"
-    $fullPrompt | Set-Content -Path $promptFile -Encoding utf8NoBOM
-
-    # Build the command args list for copilot CLI.
-    # We assemble it as an array so we can display it with -ShowCommand
-    # before actually executing it.
-    $copilotArgs = @(
-        '-p', $fullPrompt,
-        '-s',
-        '--additional-mcp-config', "@$mcpTmp",
-        '--allow-all-tools',
-        '--deny-tool', 'shell',
-        '--deny-tool', 'write',
-        '--deny-tool', 'read',
-        '--deny-tool', 'fetch',
-        '--no-custom-instructions',
-        '--no-ask-user',
-        '--disable-builtin-mcps',
-        '--model', $Model
-    )
-
     # Emit the command if -ShowCommand was requested.
     # "Show me the money!" — Jerry Maguire (1996... close enough to the 80s)
     if ($ShowCommand) {
@@ -497,7 +475,7 @@ INSTRUCTIONS: You have an MCP tool called 'execute_javascript' from the 'hyperli
         if ($CpuTimeout  -ne 1000) { $installFlags += " -CpuTimeout $CpuTimeout" }
         if ($WallTimeout -ne 5000) { $installFlags += " -WallTimeout $WallTimeout" }
         if ($HeapSize    -ne 16)   { $installFlags += " -HeapSize $HeapSize" }
-        if ($StackSize   -ne 1)    { $installFlags += " -StackSize $StackSize" }
+        if ($ScratchSize   -ne 1)    { $installFlags += " -ScratchSize $ScratchSize" }
 
         Write-Host ''
         Write-Host '🔧 Copy-pasteable command:' -ForegroundColor Cyan
@@ -687,7 +665,6 @@ INSTRUCTIONS: You have an MCP tool called 'execute_javascript' from the 'hyperli
     # Clean up temp files
     Remove-Item $mcpTmp      -ErrorAction SilentlyContinue
     Remove-Item $timingLog   -ErrorAction SilentlyContinue
-    Remove-Item $promptFile  -ErrorAction SilentlyContinue
     if ($codeLog) { Remove-Item $codeLog -ErrorAction SilentlyContinue }
 
     return $success
@@ -697,7 +674,7 @@ INSTRUCTIONS: You have an MCP tool called 'execute_javascript' from the 'hyperli
 
 Write-Banner
 Write-Info "Using model: $Model"
-Write-Info "Sandbox limits: CPU ${CpuTimeout}ms, wall ${WallTimeout}ms, heap ${HeapSize}MB, stack ${StackSize}MB"
+Write-Info "Sandbox limits: CPU ${CpuTimeout}ms, wall ${WallTimeout}ms, heap ${HeapSize}MB, scratch ${ScratchSize}MB"
 
 switch ($Mode) {
     'Install' {

src/js-host-api/examples/mcp-server/demo-copilot-cli.sh

@@ -27,7 +27,7 @@
 #   --cpu-timeout <ms>      CPU time limit per execution (default: 1000)
 #   --wall-timeout <ms>     Wall-clock backstop per execution (default: 5000)
 #   --heap-size <MB>        Guest heap size in megabytes (default: 16)
-#   --stack-size <MB>       Guest stack size in megabytes (default: 1)
+#   --scratch-size <MB>       Guest scratch size in megabytes (default: 1)
 #
 # ─────────────────────────────────────────────────────────────────────
 set -euo pipefail
@@ -55,7 +55,7 @@ CUSTOM_PROMPT=""
 CPU_TIMEOUT="${HYPERLIGHT_CPU_TIMEOUT_MS:-1000}"
 WALL_TIMEOUT="${HYPERLIGHT_WALL_TIMEOUT_MS:-5000}"
 HEAP_SIZE="${HYPERLIGHT_HEAP_SIZE_MB:-16}"
-STACK_SIZE="${HYPERLIGHT_STACK_SIZE_MB:-1}"
+SCRATCH_SIZE="${HYPERLIGHT_SCRATCH_SIZE_MB:-1}"
 
 # ── Paths ────────────────────────────────────────────────────────────
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -82,9 +82,24 @@ separator() {
 }
 
 # Timing helpers — because "Time... is not on my side" — The Rolling Stones (1964, close enough)
-# Uses millisecond precision via date +%s%3N (GNU coreutils)
+# Uses millisecond precision when available; falls back to portable options on macOS/BSD.
 now_ms() {
-    date +%s%3N
+    # Prefer GNU date if available (system date or gdate), and verify output is numeric.
+    if date +%s%3N 2>/dev/null | grep -Eq '^[0-9]+$'; then
+        date +%s%3N
+    elif command -v gdate >/dev/null 2>&1; then
+        gdate +%s%3N
+    elif command -v python3 >/dev/null 2>&1; then
+        python3 - <<'EOF'
+import time, sys
+sys.stdout.write(str(int(time.time() * 1000)))
+EOF
+    elif command -v node >/dev/null 2>&1; then
+        node -e 'console.log(Date.now())'
+    else
+        # Portable fallback: seconds since epoch with millisecond field set to 000.
+        date +%s000
+    fi
 }
 
 # Log elapsed time since a given start timestamp (ms)
@@ -144,8 +159,7 @@ check_prerequisites() {
     info "Verifying native addon loads correctly..."
     local lib_js="${SCRIPT_DIR}/../../lib.js"
     local smoke_err
-    smoke_err="$(node --input-type=module -e "import('${lib_js}').then(() => console.log('OK')).catch(e => { console.error(e.message); process.exit(1); })" 2>&1)"
-    if [[ $? -ne 0 ]]; then
+    if ! smoke_err="$(node --input-type=module -e "import('${lib_js}').then(() => console.log('OK')).catch(e => { console.error(e.message); process.exit(1); })" 2>&1)"; then
         fail "Native addon failed to load — rebuild with 'just build'.\n${smoke_err}"
     fi
     ok "Native addon loads successfully"
@@ -170,22 +184,21 @@ build_mcp_json() {
     export HYPERLIGHT_CPU_TIMEOUT_MS="${CPU_TIMEOUT}"
     export HYPERLIGHT_WALL_TIMEOUT_MS="${WALL_TIMEOUT}"
     export HYPERLIGHT_HEAP_SIZE_MB="${HEAP_SIZE}"
-    export HYPERLIGHT_STACK_SIZE_MB="${STACK_SIZE}"
+    export HYPERLIGHT_SCRATCH_SIZE_MB="${SCRATCH_SIZE}"
 
     node -e "
         const installMode = '${install_mode}' === 'install';
         const env = {
             HYPERLIGHT_CPU_TIMEOUT_MS:  process.env.HYPERLIGHT_CPU_TIMEOUT_MS,
             HYPERLIGHT_WALL_TIMEOUT_MS: process.env.HYPERLIGHT_WALL_TIMEOUT_MS,
             HYPERLIGHT_HEAP_SIZE_MB:    process.env.HYPERLIGHT_HEAP_SIZE_MB,
-            HYPERLIGHT_STACK_SIZE_MB:   process.env.HYPERLIGHT_STACK_SIZE_MB,
+            HYPERLIGHT_SCRATCH_SIZE_MB:   process.env.HYPERLIGHT_SCRATCH_SIZE_MB,
         };
         if (installMode) {
-            // Permanent install: fixed well-known paths so Copilot can
-            // spawn the server with predictable log locations.
-            // \"Roads? Where we're going, we don't need roads.\" — Back to the Future (1985)
+            // Permanent install: include timing log at a fixed well-known path.
+            // Code logging is intentionally omitted — it would persist all
+            // executed JS to disk by default (privacy concern, unbounded growth).
             env.HYPERLIGHT_TIMING_LOG = '/tmp/hyperlight-timing.jsonl';
-            env.HYPERLIGHT_CODE_LOG   = '/tmp/hyperlight-code.js';
         } else {
             if (process.env.HYPERLIGHT_TIMING_LOG) env.HYPERLIGHT_TIMING_LOG = process.env.HYPERLIGHT_TIMING_LOG;
             if (process.env.HYPERLIGHT_CODE_LOG)   env.HYPERLIGHT_CODE_LOG   = process.env.HYPERLIGHT_CODE_LOG;
@@ -233,9 +246,8 @@ install_mcp_config() {
                     HYPERLIGHT_CPU_TIMEOUT_MS:  '${CPU_TIMEOUT}',
                     HYPERLIGHT_WALL_TIMEOUT_MS: '${WALL_TIMEOUT}',
                     HYPERLIGHT_HEAP_SIZE_MB:    '${HEAP_SIZE}',
-                    HYPERLIGHT_STACK_SIZE_MB:   '${STACK_SIZE}',
+                    HYPERLIGHT_SCRATCH_SIZE_MB:   '${SCRATCH_SIZE}',
                     HYPERLIGHT_TIMING_LOG:      '/tmp/hyperlight-timing.jsonl',
-                    HYPERLIGHT_CODE_LOG:        '/tmp/hyperlight-code.js',
                 },
             };
             fs.writeFileSync('${MCP_CONFIG_FILE}', JSON.stringify(existing, null, 4) + '\n');
@@ -440,7 +452,7 @@ Your task is complete the moment you present the result."
         [[ "${CPU_TIMEOUT}"  != "1000" ]] && install_flags+=" --cpu-timeout ${CPU_TIMEOUT}"
         [[ "${WALL_TIMEOUT}" != "5000" ]] && install_flags+=" --wall-timeout ${WALL_TIMEOUT}"
         [[ "${HEAP_SIZE}"    != "16" ]]   && install_flags+=" --heap-size ${HEAP_SIZE}"
-        [[ "${STACK_SIZE}"   != "1" ]]    && install_flags+=" --stack-size ${STACK_SIZE}"
+        [[ "${SCRATCH_SIZE}"   != "1" ]]    && install_flags+=" --scratch-size ${SCRATCH_SIZE}"
 
         echo ""
         echo -e "${CYAN}${BOLD}🔧 Copy-pasteable command:${RESET}"
@@ -603,24 +615,24 @@ main() {
                 HEAP_SIZE="$2"
                 shift 2
                 ;;
-            --stack-size)
-                if [[ -z "${2:-}" ]]; then fail "--stack-size requires a value in MB"; fi
-                STACK_SIZE="$2"
+            --scratch-size)
+                if [[ -z "${2:-}" ]]; then fail "--scratch-size requires a value in MB"; fi
+                SCRATCH_SIZE="$2"
                 shift 2
                 ;;
             --install|--uninstall|--headless)
                 mode="$1"
                 shift
                 ;;
             *)
-                fail "Unknown argument: $1\nUsage: $0 [--headless] [--install] [--uninstall] [--model <name>] [--prompt <text>] [--show-code] [--show-command] [--cpu-timeout <ms>] [--wall-timeout <ms>] [--heap-size <MB>] [--stack-size <MB>]"
+                fail "Unknown argument: $1\nUsage: $0 [--headless] [--install] [--uninstall] [--model <name>] [--prompt <text>] [--show-code] [--show-command] [--cpu-timeout <ms>] [--wall-timeout <ms>] [--heap-size <MB>] [--scratch-size <MB>]"
                 ;;
         esac
     done
 
     banner
     info "Using model: ${BOLD}${MODEL}${RESET}"
-    info "Sandbox limits: CPU ${BOLD}${CPU_TIMEOUT}ms${RESET}, wall ${BOLD}${WALL_TIMEOUT}ms${RESET}, heap ${BOLD}${HEAP_SIZE}MB${RESET}, stack ${BOLD}${STACK_SIZE}MB${RESET}"
+    info "Sandbox limits: CPU ${BOLD}${CPU_TIMEOUT}ms${RESET}, wall ${BOLD}${WALL_TIMEOUT}ms${RESET}, heap ${BOLD}${HEAP_SIZE}MB${RESET}, scratch ${BOLD}${SCRATCH_SIZE}MB${RESET}"
 
     case "${mode}" in
         --install)

src/js-host-api/examples/mcp-server/package.json

@@ -15,5 +15,8 @@
     },
     "devDependencies": {
         "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">= 20"
     }
 }