Skip to content

Self-improving AI Employees for everyone

fix(nodejs): strip TypeScript with Bun.Transpiler so typescriptExecutor runs TS

trohitga5fad321ca4b
diff --git a/desktop/tests/invariants/staged-tree.test.ts b/desktop/tests/invariants/staged-tree.test.ts
index 749a1b00..d4345692 100644
--- a/desktop/tests/invariants/staged-tree.test.ts
+++ b/desktop/tests/invariants/staged-tree.test.ts
@@ -138,6 +138,14 @@ describe.skipIf(!staged || !runtimesStaged)("staged runtimes", () => {
}
}
expect(ok, output).toBe(true);
+ // TypeScript is type-stripped by Bun.Transpiler inside the sidecar; a
+ // Node-hosted sidecar would fail this with a SyntaxError.
+ const res = await fetch(`http://127.0.0.1:${port}/execute`, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ code: "const n: number = 21; output = n * 2;", language: "typescript" }),
+ });
+ expect(((await res.json()) as { output: unknown }).output).toBe(42);
} finally {
child.kill();
}
diff --git a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
index dc3f1369..c87be16d 100644
--- a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
+++ b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
@@ -4,18 +4,21 @@
|------|-------|
| **Category** | code_fs_process / code |
| **Backend handler** | [`server/nodes/code/javascript_executor/__init__.py::JavaScriptExecutorNode.execute_op`](../../../server/nodes/code/javascript_executor/__init__.py) (dispatched via `BaseNode.execute()` + `@Operation("execute")`; base in [`_base.py`](../../../server/nodes/code/_base.py)) |
-| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
+| **Sidecar client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
| **Tests** | [`server/tests/nodes/test_code_fs_process.py`](../../../server/tests/nodes/test_code_fs_process.py) |
| **Skill (if any)** | [`server/skills/coding_agent/javascript-skill/SKILL.md`](../../../server/skills/coding_agent/javascript-skill/SKILL.md) |
| **Dual-purpose tool** | yes - tool name `javascript_code` |
## Purpose
-Runs user JavaScript through the persistent Node.js executor server (Express +
-tsx) that the Python backend spawns on startup. The plugin does **not** spawn
-`node` per call - it POSTs the code to `http://localhost:5682/execute` via the
-shared `get_nodejs_client()` singleton (an async `aiohttp` client). The Node.js
-server evaluates the script and returns `{success, output, console_output, ...}`.
+Runs user JavaScript through the persistent JS executor sidecar (Express on the
+bun runtime, `server/nodejs/dist/index.js`) that the backend spawns on demand
+from `nodes/code/_runtime.py` on the first JS/TS execution. The plugin does
+**not** spawn a runtime per call - it POSTs the code to
+`http://localhost:${NODEJS_EXECUTOR_PORT}/execute` via the shared
+`get_nodejs_client()` singleton (an async `aiohttp` client). The sidecar
+evaluates the script in a `node:vm` context and returns
+`{success, output, console_output, ...}`.
The plugin merges the caller's upstream outputs (`ctx.raw["connected_outputs"]`)
into an `input_data` object, injects the workflow's `workspace_dir`
@@ -26,23 +29,26 @@ into an `input_data` object, injects the workflow's `workspace_dir`
| Handle | Connection type | Required | Purpose |
|--------|-----------------|----------|---------|
-| `input-main` | main | no | Upstream outputs merged into the Node-side `input_data` object |
+| `input-main` | main | no | Upstream outputs merged into the sidecar-side `input_data` object |
## Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|------|------|---------|----------|---------------------|-------------|
| `code` | string (code editor) | (required, `min_length=1`) | yes | - | JavaScript source. User must assign to `output` |
-| `timeout` | number | `30` (ge=1, le=600) | no | - | Seconds - multiplied by 1000 and forwarded as millisecond timeout to the Node server |
+| `timeout` | number | `30` (ge=1, le=600) | no | - | Seconds - multiplied by 1000 and forwarded as millisecond timeout to the sidecar |
`CodeExecutorParams` uses `extra="allow"` (extra params persist but are unread).
-## Node.js client singleton
+## Sidecar client singleton
`get_nodejs_client()` in [`_nodejs.py`](../../../server/nodes/code/_nodejs.py) lazily
-constructs one `NodeJSClient(base_url="http://localhost:5682", timeout=30)` shared
-across the JS + TS plugins. The defaults are hard-coded in the helper signature
-(no per-call kwargs from the plugin).
+constructs one `NodeJSClient` shared across the JS + TS plugins (base URL from
+`NODEJS_EXECUTOR_URL`, else `http://localhost:${NODEJS_EXECUTOR_PORT}`; request
+timeout from `NODEJS_EXECUTOR_TIMEOUT`; no per-call kwargs from the plugin) and,
+unless `NODEJS_EXECUTOR_URL` points at an external executor, asks the
+plugin-owned supervisor to `ensure_started()` the sidecar on the bun runtime
+(`OPENCOMPANY_BUN_BIN`, else `bun` on PATH).
## Outputs (handles)
@@ -54,7 +60,7 @@ across the JS + TS plugins. The defaults are hard-coded in the helper signature
```ts
{
- output: any; // Value the Node.js server parsed from `output` in the script
+ output: any; // Value the sidecar read from `output` in the script
console_output: string; // Captured console.log/.error etc.
}
```
@@ -72,7 +78,7 @@ flowchart TD
C --> D[input_data = ctx.raw connected_outputs or {}<br/>inject workspace_dir]
D --> F[get_nodejs_client<br/>lazy singleton]
F --> G[client.execute<br/>POST /execute<br/>language=javascript]
- G -- ClientConnectorError --> H1[raise NodeUserError<br/>JS executor not running on :5682]
+ G -- ClientConnectorError --> H1[raise NodeUserError<br/>JS executor unreachable on NODEJS_EXECUTOR_PORT]
G -- success=false --> H2[raise NodeUserError<br/>error=result.error]
G -- success=true --> I[Return dict<br/>output, console_output]
```
@@ -86,56 +92,58 @@ flowchart TD
`input_data["workspace_dir"]`, shadowing any upstream node that happened to
produce a key with that name.
- **Client reuse**: `get_nodejs_client()`'s `_client` is a **module-global**
- singleton in `_nodejs.py`, fixed at the hard-coded `base_url`/`timeout`.
-- **Node server error propagation**: if `result["success"]` is falsey, the
+ singleton in `_nodejs.py`, fixed at the env-derived `base_url`/`timeout`.
+- **Sidecar error propagation**: if `result["success"]` is falsey, the
plugin raises `NodeUserError(result["error"] or "JavaScript executor failed")`.
- **Sidecar down**: `aiohttp.ClientConnectorError` is caught and re-raised as a
- `NodeUserError` telling the LLM the Node executor is unreachable on
- localhost:5682 and to fall back to `python_executor`.
+ `NodeUserError` telling the LLM the JS executor is unreachable on
+ `NODEJS_EXECUTOR_PORT` and to fall back to `python_executor`.
## Side Effects
- **Database writes**: none.
- **Broadcasts**: none from this handler.
-- **External API calls**: `POST http://localhost:5682/execute`
+- **External API calls**: `POST http://localhost:${NODEJS_EXECUTOR_PORT}/execute`
(configurable via `NODEJS_EXECUTOR_URL`). Body:
`{code, input_data, language: "javascript", timeout}`.
-- **File I/O**: none from Python; the Node.js server may read/write user
- packages at `server/nodejs/user-packages/`.
-- **Subprocess**: none directly. The Node.js server itself is a long-lived
- subprocess started by `main.py` lifespan.
+- **File I/O**: none from Python; the sidecar may read/write user packages at
+ `server/nodejs/user-packages/` (`bun add` via `/packages/install`).
+- **Subprocess**: none directly. The sidecar itself is a long-lived bun
+ subprocess supervised by `nodes/code/_runtime.py` (spawned on demand, reaped
+ by the lifespan's `shutdown_all_supervisors()`).
- **Module-level state**: the `_client` module global in `_nodejs.py` is created
on first use and never reset.
## External Dependencies
- **Credentials**: none.
-- **Services**: Persistent Node.js executor at `http://localhost:5682`.
- Must be running - the backend start script boots it alongside uvicorn.
+- **Services**: the persistent JS executor sidecar on bun (`OPENCOMPANY_BUN_BIN`
+ or `bun` on PATH; bundled by the desktop app), spawned on demand by the
+ plugin's supervisor - nothing has to be started by hand.
- **Python packages**: `aiohttp`.
- **Environment variables**: `NODEJS_EXECUTOR_URL`,
`NODEJS_EXECUTOR_TIMEOUT`, `NODEJS_EXECUTOR_PORT`, `NODEJS_EXECUTOR_HOST`,
- `NODEJS_EXECUTOR_BODY_LIMIT` (all read by the Node server itself).
+ `NODEJS_EXECUTOR_BODY_LIMIT` (all read by the sidecar itself).
## Edge cases & known limits
- **Module-level client singleton**: `_client` in `_nodejs.py` is cached on
first call at the hard-coded `base_url`/`timeout`. Reset by setting
`services.code._nodejs._client = None` (or `nodes.code._nodejs._client`).
-- **Node server down**: connection refused surfaces as
- `error="Cannot connect to host localhost:5682 ssl:default [Connect call
- failed]"` or similar aiohttp message. No automatic retry.
+- **Sidecar down**: connection refused surfaces as
+ `error="Cannot connect to host localhost:<NODEJS_EXECUTOR_PORT> ssl:default
+ [Connect call failed]"` or similar aiohttp message. No automatic retry.
- **`workspace_dir` key collision**: user code cannot read an upstream
`workspace_dir` from `input_data` - the handler always overwrites it.
- **Timeout semantics**: the Python-side `timeout` is a ceiling on the
aiohttp request itself (set once at client creation); the
- `timeout_ms` forwarded in the body is the Node server's script timeout.
+ `timeout_ms` forwarded in the body is the sidecar's script timeout.
These two can disagree - if the script timeout is longer than the aiohttp
timeout, the HTTP call fails before the script finishes.
-- **`console_output` may contain partial output**: Node server streams stdio
- into a buffer and flushes at end-of-run, but on script timeout the server
- returns whatever it captured up to the kill signal.
-- **JSON-only transport**: `output` must be JSON-serialisable on the Node
+- **`console_output` may contain partial output**: the sidecar captures
+ `console.*` calls into a buffer and returns it at end-of-run, so on a script
+ timeout the response carries whatever was captured up to the abort.
+- **JSON-only transport**: `output` must be JSON-serialisable on the sidecar
side. Functions, `undefined`, `BigInt`, circular refs are stripped or
rejected by `JSON.stringify` before return.
diff --git a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
index 283bf43c..4e2ae2cc 100644
--- a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
+++ b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
@@ -4,7 +4,7 @@
|------|-------|
| **Category** | code_fs_process / code |
| **Backend handler** | [`server/nodes/code/typescript_executor/__init__.py::TypeScriptExecutorNode.execute_op`](../../../server/nodes/code/typescript_executor/__init__.py) (dispatched via `BaseNode.execute()` + `@Operation("execute")`; base in [`_base.py`](../../../server/nodes/code/_base.py)) |
-| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
+| **Sidecar client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
| **Tests** | [`server/tests/nodes/test_code_fs_process.py`](../../../server/tests/nodes/test_code_fs_process.py) |
| **Skill (if any)** | - (shared with `javascript-skill`) |
| **Dual-purpose tool** | yes - tool name `typescript_code` |
@@ -12,11 +12,14 @@
## Purpose
Identical to [`javascriptExecutor`](./javascriptExecutor.md) except the
-`language` field in the POST payload is `"typescript"`, so the Node.js server
-runs the script through `tsx` (TypeScript runner) instead of plain `node`.
-All inputs, outputs, and error paths match the JS variant - the only
-user-facing difference is that TypeScript type annotations parse without
-error.
+`language` field in the POST payload is `"typescript"`, so the sidecar strips
+the types with bun's own transpiler (`Bun.Transpiler`, loader `ts`) before
+evaluating the result in the same `node:vm` context. All inputs, outputs, and
+error paths match the JS variant - the only user-facing difference is that
+TypeScript syntax (annotations, interfaces, enums, generics) is accepted; a
+TypeScript syntax error comes back as `{success: false, error}` exactly like a
+runtime error. (Before the bun cutover the flag was ignored and any annotation
+was a `SyntaxError`.)
The plugin reads upstream outputs from `ctx.raw["connected_outputs"]` (injected
by the executor for code-executor node types) and the workflow's
@@ -26,22 +29,23 @@ by the executor for code-executor node types) and the workflow's
| Handle | Connection type | Required | Purpose |
|--------|-----------------|----------|---------|
-| `input-main` | main | no | Upstream outputs merged into the Node-side `input_data` object |
+| `input-main` | main | no | Upstream outputs merged into the sidecar-side `input_data` object |
## Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|------|------|---------|----------|---------------------|-------------|
| `code` | string (code editor) | (required, `min_length=1`) | yes | - | TypeScript source. User must assign to `output` |
-| `timeout` | number | `30` (ge=1, le=600) | no | - | Seconds - multiplied by 1000 before forwarding to the Node server |
+| `timeout` | number | `30` (ge=1, le=600) | no | - | Seconds - multiplied by 1000 before forwarding to the sidecar |
`CodeExecutorParams` uses `extra="allow"` (extra params persist but are unread).
-## Node.js client singleton
+## Sidecar client singleton
Shares `get_nodejs_client()` in [`_nodejs.py`](../../../server/nodes/code/_nodejs.py)
-with the JS plugin — one `NodeJSClient(base_url="http://localhost:5682",
-timeout=30)` instance, hard-coded defaults.
+with the JS plugin — one `NodeJSClient` instance whose base URL and timeout
+come from `NODEJS_EXECUTOR_URL` / `NODEJS_EXECUTOR_PORT` /
+`NODEJS_EXECUTOR_TIMEOUT`, with the sidecar spawned on demand on bun.
## Outputs (handles)
@@ -71,7 +75,7 @@ flowchart TD
C --> D[input_data = ctx.raw connected_outputs or {}<br/>inject workspace_dir]
D --> F[get_nodejs_client<br/>lazy singleton]
F --> G[client.execute<br/>POST /execute<br/>language=typescript]
- G -- ClientConnectorError --> H1[raise NodeUserError<br/>TS executor not running on :5682]
+ G -- ClientConnectorError --> H1[raise NodeUserError<br/>TS executor unreachable on NODEJS_EXECUTOR_PORT]
G -- success=false --> H2[raise NodeUserError<br/>error=result.error]
G -- success=true --> I[Return dict<br/>output, console_output]
```
@@ -85,16 +89,17 @@ wire-level difference is the POST body's `language` field.
- **Database writes**: none.
- **Broadcasts**: none.
-- **External API calls**: `POST http://localhost:5682/execute` with body
- `{code, input_data, language: "typescript", timeout}`.
+- **External API calls**: `POST http://localhost:${NODEJS_EXECUTOR_PORT}/execute`
+ with body `{code, input_data, language: "typescript", timeout}`.
- **Subprocess**: none directly.
- **Module-level state**: shares the `_nodejs_client` singleton with the JS
executor.
## External Dependencies
-- **Services**: Persistent Node.js executor at `http://localhost:5682`.
- The server must have `tsx` available (pinned in `server/nodejs/package.json`).
+- **Services**: the JS executor sidecar on bun; type stripping is built into
+ the bun runtime (`Bun.Transpiler`), so no `tsx` and no TypeScript compiler
+ are involved - and no type checking either.
- **Python packages**: `aiohttp`.
- **Environment variables**: `NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_TIMEOUT`.
@@ -103,9 +108,10 @@ wire-level difference is the POST body's `language` field.
- **Shared singleton with `javascriptExecutor`**: a TS call after a JS call
(or vice versa) reuses the same `NodeJSClient` instance. Changing
`nodejs_url` / `nodejs_timeout` mid-process has no effect.
-- **No TypeScript compile errors at HTTP layer**: if `tsx` emits compile
- errors the Node server returns `{success: false, error: "<tsc message>"}`;
- the Python handler surfaces this verbatim.
+- **No type checking**: `Bun.Transpiler` erases types without checking them,
+ so a type error still runs; only a syntax error fails, returned as
+ `{success: false, error: "<parser message>"}` and surfaced verbatim by the
+ Python handler.
- **Type erasure**: runtime output is still JSON; interfaces and type aliases
are compile-time only.
- **Inherits every JS caveat**: module-level client, aiohttp-vs-script timeout
diff --git a/server/nodejs/src/index.ts b/server/nodejs/src/index.ts
index af063fe7..3291f5e1 100644
--- a/server/nodejs/src/index.ts
+++ b/server/nodejs/src/index.ts
@@ -52,9 +52,21 @@ app.get('/health', (_req: Request, res: Response) => {
});
});
+// TypeScript is type-stripped by bun's own transpiler before it reaches the
+// vm context (which evaluates JavaScript only). Type annotations, interfaces
+// and enums therefore work in typescriptExecutor; a syntax error surfaces as
+// the same {success: false, error} envelope as a runtime error.
+const tsTranspiler = typeof Bun !== 'undefined' ? new Bun.Transpiler({ loader: 'ts', target: 'node' }) : null;
+
+function prepareSource(code: string, language: ExecuteRequest['language']): string {
+ if (language !== 'typescript') return code;
+ if (!tsTranspiler) throw new Error('TypeScript execution needs the bun runtime');
+ return tsTranspiler.transformSync(code);
+}
+
// Execute code - all parameters from request body
app.post('/execute', (req: Request, res: Response) => {
- const { code, input_data = {}, timeout = 30000 } = req.body as ExecuteRequest;
+ const { code, language = 'javascript', input_data = {}, timeout = 30000 } = req.body as ExecuteRequest;
if (!code || typeof code !== 'string') {
res.status(400).json({ success: false, error: 'Missing or invalid "code" field' });
@@ -89,7 +101,7 @@ app.post('/execute', (req: Request, res: Response) => {
// Python backend via NodeJSClient. Public network exposure is the
// operator's responsibility.
// codeql[js/code-injection]
- vm.runInContext(code, context, { timeout, filename: 'user-code.js' });
+ vm.runInContext(prepareSource(code, language), context, { timeout, filename: language === 'typescript' ? 'user-code.ts' : 'user-code.js' });
res.json({
success: true,