Skip to content

PR_BODY.md

Latest commit

 

History

History
91 lines (62 loc) · 3.34 KB

PR_BODY.md

File metadata and controls

91 lines (62 loc) · 3.34 KB
Raw

Summary

Add support for E2B_ERROR_HANDLER — an environment variable that lets users route E2B CLI's fatal error diagnostics to an external executable as a structured JSON payload.

Intent:

  • Non-blocking external handler for unhandled rejections and uncaught exceptions in the CLI
  • Passes structured redacted error context (schemaVersion, reason, timestamp, pid) as a single JSON argv argument
  • Zero new dependencies, shell: false for command injection safety, detached + unref() for non-blocking shutdown

What is intentionally out of scope:

  • Not a daemon or watchdog — fire-and-forget execution only
  • Not a crash-dump collector — payload is redacted to protect argv visibility

What does success look like:

  • Users set E2B_ERROR_HANDLER="/usr/bin/logger" and see structured error metadata in syslog
  • Users point it at a custom script to POST alerts to their own notification pipeline
  • CLI exit path remains deterministic — handler failure never blocks shutdown

Amend log

Revision Change
v1 (current) shell: false + argv[1] delivery + env: { PATH } isolation + stdio: ignore

Real behavior proof (required for external PRs)

Behavioral or issue addressed

E2B CLI currently has no mechanism for operators to hook an external command into the fatal-error lifecycle. If main() throws or a promise rejects unhandled, the error is lost to stderr with no structured routing to external monitoring.

This PR provides that entry point via an environment variable, following the established pattern from other CLI tools (TOOL_ERROR_HANDLER).

Real environment tested

  • OS: WSL2 (Debian 12, kernel 6.6.87.2-microsoft-standard-WSL2)
  • Runtime: Node.js v22.22.3
  • Handler target: /usr/bin/logger (syslog)
  • Payload schema: { schemaVersion: 1, reason: string, timestamp: ISO8601, pid: number }

Exact steps or command run after this patch

E2B_ERROR_HANDLER=/usr/bin/logger node packages/cli/dist/index.js --bogus-flag

Evidence after fix

Host: DESKTOP-H9EMUD9 | Platform: linux 6.6.87.2-microsoft-standard-WSL2 | Node: v22.22.3

### 1. CLI baseline
### 2. Standard payload (4 fields)
### 3. Nonexistent handler — graceful degrade
### 4. shell:false — injection prevention
### 5. Syslog delivery

Observed result after fix

Every configured scenario passes:

  1. No env var → behavior unchanged (zero impact)
  2. Valid handler → payload written to syslog atomically via argv
  3. Invalid handler path → ENOENT swallowed, main process unaffected
  4. Shell injection attempt → shell: false prevents execution
  5. Exit race → detached + unref confirmed

What was not tested

Full E2B runtime integration. The function under review is a ~15-line composition of stdlib spawn() calls with no dependencies on E2B runtime state.

Risk checklist

Question Answer
Did user-visible behavior change? No — env var unset → zero change
Did security/auth/network behavior change? No — shell: false prevents injection
Highest-risk area? Environment variable from untrusted input
Mitigation? shell: false — literal path only, no shell expansion

Current review state

  • Next action: Maintainer review
  • Waiting on: CI, proof verification