@sema-agent/server 1.322.0 → 2.0.0

package/dist/lsp/e2b-bridge.js

@@ -1,4 +1,20 @@
+/**
+ * The WS↔stdio bridge that runs INSIDE the E2B sandbox + the setup it needs. A language server speaks LSP-JSON-RPC
+ * over stdio with **Content-Length** framing; our `WsLspTransport` speaks one raw JSON-RPC message per WS frame.
+ * This bridge (started per language server, exposed via `sandbox.getHost(port)`) translates between the two — it's
+ * the piece that lets core's stdio-only LSP design work over E2B's HTTP/WS proxy (no stdin on `execStream`).
+ *
+ * **Proven end-to-end** (scripts/lsp-live-test.ts): `goToDefinition` resolved to the real definition through
+ * `wss://…e2b.app`. For production the servers + bridge should be BAKED into an E2B template (the heavy-install
+ * pitfall); `lspInstallAndStart` is the on-the-fly path for P1 / un-baked templates.
+ */
 import { FRAME_DECODER_JS } from "./lsp-frames.js";
+/**
+ * Bridges WS ⇄ a language server's stdio. Server command from `LSP_CMD`, port `LSP_PORT`, and a per-session
+ * **auth token** `LSP_TOKEN` (the endpoint is a public `wss://<port>-<id>.e2b.app` URL — the runner connects with
+ * `?token=<secret>`; without it, anyone with the URL could read the workspace via LSP, council #4). Frame parsing
+ * uses the unit-tested {@link FRAME_DECODER_JS} (council #1/#2/#5).
+ */
 export const BRIDGE_SOURCE = FRAME_DECODER_JS +
     String.raw `
 const { WebSocketServer } = require('ws');
@@ -36,26 +52,35 @@ setInterval(() => {
 }, HEARTBEAT_MS);
 console.log('lsp-bridge listening', PORT);
 `;
+/** Language server command per languageId. P1 = typescript/javascript; dart/kotlin land with their template servers.
+ *  `--stdio` only where the server needs it to pick stdio over its other transports (the node-based servers);
+ *  gopls/jdtls/kotlin-language-server/sourcekit-lsp/`dart language-server` speak LSP over stdio by default. */
 export const SERVER_CMD = {
     typescript: "typescript-language-server --stdio",
     javascript: "typescript-language-server --stdio",
-    python: "pyright-langserver --stdio",
-    go: "gopls",
-    dart: "dart language-server",
-    kotlin: "kotlin-language-server",
+    python: "pyright-langserver --stdio", // dev-base bakes pyright
+    go: "gopls", // gopls serves LSP over stdio by default; baked in dev-base (no on-the-fly path — needs the go toolchain)
+    // dev-mobile baked servers (all stdio; no on-the-fly path — they need their SDKs):
+    dart: "dart language-server", // built into the Dart SDK (comes with Flutter)
+    kotlin: "kotlin-language-server", // fwcd candidate; a future bake-off may switch this to JetBrains kotlin-lsp
     java: "jdtls",
     swift: "sourcekit-lsp",
 };
+/** npm packages a non-baked sandbox needs (on-the-fly install). Languages absent here (go) REQUIRE a baked template. */
 export const SERVER_NPM = {
     typescript: "typescript-language-server typescript",
     javascript: "typescript-language-server typescript",
     python: "pyright",
 };
+/** Bridge dir + port inside the sandbox. One bridge process per language → distinct ports. */
 export const BRIDGE_DIR = "/home/user/.lsp-bridge";
 export function portForLanguage(language) {
+    // stable per-language port; extend the table as templates add servers (dev-mobile: dart/kotlin/java/swift)
     const ports = { typescript: 8123, javascript: 8123, dart: 8124, kotlin: 8125, python: 8126, go: 8127, java: 8128, swift: 8129 };
     return ports[language] ?? 8123;
 }
+/** FOREGROUND install (run via `env.exec` — must finish before the start). A baked template makes both checks
+ *  skip instantly; a non-baked sandbox npm-installs the server + ws here (slow once per sandbox). */
 export function lspInstallCommand(language) {
     const cmd = SERVER_CMD[language];
     const npm = SERVER_NPM[language];
@@ -65,6 +90,9 @@ export function lspInstallCommand(language) {
         npm ? `command -v ${cmd.split(" ")[0]} >/dev/null || npm i -g ${npm} >>/tmp/lsp-setup.log 2>&1` : "true",
     ].join(" && ");
 }
+/** Start the bridge — run as a TRUE background command (`env.startBackground`), NOT `&`-backgrounded inside a
+ *  foreground run: E2B reaps the foreground process group on completion, killing an in-shell `&`/nohup child.
+ *  So node is the FOREGROUND here and E2B keeps the background command alive. */
 export function lspStartCommand(language, port, token) {
     return `cd ${BRIDGE_DIR} && LSP_PORT=${port} LSP_TOKEN='${token}' LSP_CMD='${SERVER_CMD[language]}' node bridge.cjs`;
 }

package/dist/lsp/e2b-manager.d.ts

@@ -2,15 +2,25 @@ import { connectWsLspTransport } from "./ws-transport.js";
 import { E2bLspManager, type LspCapableEnv } from "./manager.js";
 import type { LspTransport } from "./types.js";
 export interface E2bLspOptions {
+    /** Injectable for tests (no E2B/ws). */
     connect?: typeof connectWsLspTransport;
     retry?: {
         attempts: number;
         delayMs: number;
     };
+    /** Bridge auth token override. The manager pins ONE token per env+language: on a RE-open (transport heal
+     *  after the E2B proxy idle-killed the WS) the original bridge process is still listening with the FIRST
+     *  token — a fresh random token would be rejected and the reconnect would always fail. */
     token?: string;
+    /** WS scheme for the bridge URL. E2B's `getHost` returns a public TLS proxy host → `wss` (default);
+     *  the k8s adapter returns a cluster-internal `podIP:port` → plain `ws` (no TLS on the pod network;
+     *  the per-session bridge token still gates access). */
     scheme?: "ws" | "wss";
+    /** Observability hook (open/heal/degrade events) — prod wires the service logger. */
     log?: (event: string, fields: Record<string, unknown>) => void;
 }
+/** Start (+ install on a non-baked template) the language server + bridge inside THIS env's sandbox, then connect. */
 export declare function openE2bLspTransport(language: string, env: LspCapableEnv, opts?: E2bLspOptions): Promise<LspTransport | undefined>;
+/** The single shared `LspServerManager` for the deployment (`RunnerDeps.lspManager`). */
 export declare function createE2bLspManager(opts?: E2bLspOptions): E2bLspManager;
 //# sourceMappingURL=e2b-manager.d.ts.map

package/dist/lsp/e2b-manager.js

@@ -1,10 +1,21 @@
+/**
+ * E2B LSP wiring — `createE2bLspManager()` builds the ONE stateless manager (core 1.86.2 seam: core passes
+ * the task's env into `sessionFor` at the tool mount point, so there is NO sessionId→env registry and no per-task
+ * manager construction; the old registry/monkey-patch wiring is gone).
+ *
+ * `openE2bLspTransport` does the per-sandbox start: write bridge.cjs from BRIDGE_SOURCE (single source of truth —
+ * works on baked + un-baked templates) → foreground install (baked template skips instantly) → start the bridge
+ * as a TRUE background command (a shell `&` child gets reaped when E2B completes the foreground command) → WS
+ * connect via `wss://getHost(port)?token=…` (per-session auth — the URL is public).
+ */
 import { randomUUID } from "node:crypto";
 import { connectWsLspTransport } from "./ws-transport.js";
 import { E2bLspManager } from "./manager.js";
 import { BRIDGE_DIR, BRIDGE_SOURCE, lspInstallCommand, lspStartCommand, portForLanguage, SERVER_CMD } from "./e2b-bridge.js";
+/** Start (+ install on a non-baked template) the language server + bridge inside THIS env's sandbox, then connect. */
 export async function openE2bLspTransport(language, env, opts) {
     if (!SERVER_CMD[language])
-        return undefined;
+        return undefined; // no server for this language → graceful degrade
     const connect = opts?.connect ?? connectWsLspTransport;
     const retry = opts?.retry ?? { attempts: 6, delayMs: 1500 };
     const port = portForLanguage(language);
@@ -12,9 +23,10 @@ export async function openE2bLspTransport(language, env, opts) {
     const installed = await env.exec(lspInstallCommand(language)).catch(() => undefined);
     if (!installed || !installed.ok)
         return undefined;
-    const token = opts?.token ?? randomUUID();
+    const token = opts?.token ?? randomUUID(); // per-session bridge auth — the getHost URL is public (council #4)
     await env.startBackground(lspStartCommand(language, port, token)).catch(() => undefined);
     const root = env.workspaceHandle().mountPath;
+    // the bridge starts as a background command → retry the WS connect (with the auth token) while it comes up
     const scheme = opts?.scheme ?? "wss";
     for (let attempt = 0; attempt < retry.attempts; attempt++) {
         const host = await env.getHost(port);
@@ -27,7 +39,11 @@ export async function openE2bLspTransport(language, env, opts) {
     }
     return undefined;
 }
+/** The single shared `LspServerManager` for the deployment (`RunnerDeps.lspManager`). */
 export function createE2bLspManager(opts) {
+    // One bridge token per env+language, pinned across re-opens (heal after an idle-killed WS): the original
+    // bridge keeps listening with the first token, so the reconnect must present the SAME one. WeakMap → a
+    // destroyed task's tokens are collectible with its env.
     const tokens = new WeakMap();
     return new E2bLspManager({
         log: opts?.log,

package/dist/lsp/lsp-frames.d.ts

@@ -1,2 +1,14 @@
+/**
+ * The LSP stdio Content-Length frame decoder, as JS SOURCE — embedded verbatim into `BRIDGE_SOURCE` (which runs
+ * inside the E2B sandbox, can't import TS) AND unit-tested here (test/lsp-frames.test.ts evals this same string).
+ * So the in-sandbox parser is actually exercised (council #5: the untestable raw-string parser was the risk).
+ *
+ * Guards: a frame claiming a non-finite / negative / over-cap length is skipped instead of looping or waiting
+ * forever (council #1 defense); the accumulator is dropped if it exceeds the cap with no complete frame (council
+ * #2 — a server that never sends `\r\n\r\n`, or a huge Content-Length, can't grow the buffer without bound).
+ * The runaway cap carries a `HEADER_SLACK` (core 1.196 #6 twin): a VALID frame whose PAYLOAD passes the
+ * `len <= maxBytes` check but whose `Content-Length: <n>\r\n\r\n` header pushes header+payload just over `maxBytes`
+ * must NOT be wiped mid-arrival (that silently dropped an in-window legal reply) — so cap at `maxBytes + 128`.
+ */
 export declare const FRAME_DECODER_JS: string;
 //# sourceMappingURL=lsp-frames.d.ts.map

package/dist/lsp/lsp-frames.js

@@ -1,3 +1,15 @@
+/**
+ * The LSP stdio Content-Length frame decoder, as JS SOURCE — embedded verbatim into `BRIDGE_SOURCE` (which runs
+ * inside the E2B sandbox, can't import TS) AND unit-tested here (test/lsp-frames.test.ts evals this same string).
+ * So the in-sandbox parser is actually exercised (council #5: the untestable raw-string parser was the risk).
+ *
+ * Guards: a frame claiming a non-finite / negative / over-cap length is skipped instead of looping or waiting
+ * forever (council #1 defense); the accumulator is dropped if it exceeds the cap with no complete frame (council
+ * #2 — a server that never sends `\r\n\r\n`, or a huge Content-Length, can't grow the buffer without bound).
+ * The runaway cap carries a `HEADER_SLACK` (core 1.196 #6 twin): a VALID frame whose PAYLOAD passes the
+ * `len <= maxBytes` check but whose `Content-Length: <n>\r\n\r\n` header pushes header+payload just over `maxBytes`
+ * must NOT be wiped mid-arrival (that silently dropped an in-window legal reply) — so cap at `maxBytes + 128`.
+ */
 export const FRAME_DECODER_JS = String.raw `
 function makeFrameDecoder(maxBytes) {
   var HEADER_SLACK = 128; // room for "Content-Length: <n>\r\n\r\n" ON TOP of a max-size payload (core 1.196 #6 twin)

package/dist/lsp/manager.d.ts

@@ -1,6 +1,7 @@
 import { LspDiagnosticsRegistry } from "@sema-agent/core";
 import type { ExecutionEnv } from "@sema-agent/core";
 import type { LspServerManager, LspSession, LspTransport } from "./types.js";
+/** The E2B surface the LSP needs beyond base ExecutionEnv (present on RemoteContainerExecutionEnv). */
 export interface LspCapableEnv {
     exec(command: string): Promise<{
         ok: boolean;
@@ -22,17 +23,28 @@ export interface LspCapableEnv {
         mountPath: string;
     };
 }
+/** Duck-type check: is this ExecutionEnv an E2B adapter with the LSP surface? */
 export declare function isLspCapable(env: ExecutionEnv): env is ExecutionEnv & LspCapableEnv;
 export interface E2bLspManagerOptions {
+    /** Opens (+ `initialize`s) a WS transport to the language server inside THIS env's sandbox. */
     transportFactory: (language: string, env: LspCapableEnv) => Promise<LspTransport | undefined>;
+    /** Override the file-extension → languageId map. */
     extToLang?: Readonly<Record<string, string>>;
+    /** Observability hook (open/heal/degrade events) — prod wires the service logger; silent when unset. */
     log?: (event: string, fields: Record<string, unknown>) => void;
 }
 export declare class E2bLspManager implements LspServerManager {
+    /** Per-sandbox session cache: env (weak) → language → in-flight/ready session. */
     private readonly perEnv;
     private readonly factory;
     private readonly extToLang;
     private readonly log;
+    /** design/121 (core 1.220, board [S] ①): the workspace diagnostics registry — WORKSPACE-scoped (survives
+     *  heal/evict; diagnostics belong to files, not servers), drained by the Runner at turn boundaries. Every
+     *  session feeds it from `textDocument/publishDiagnostics` (the WS transport now dispatches notifications).
+     *  ⚠️ ONE registry across sandboxes on this manager instance (it is per-deployment) — same posture as
+     *  NodeLspManager's workspace scoping; a task only sees diagnostics for files IT touched (delivered-set +
+     *  fileEdited keying is per-uri, and sandbox workspace paths are per-task-unique). */
     readonly diagnostics: LspDiagnosticsRegistry;
     constructor(opts: E2bLspManagerOptions);
     sessionFor(filePath: string, _signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;

package/dist/lsp/manager.js

@@ -1,5 +1,16 @@
+/**
+ * `E2bLspManager` — our `LspServerManager` (core mounts the `lsp` tool over it). STATELESS since core 1.86.2:
+ * core passes the task's own ExecutionEnv into `sessionFor(filePath, signal, env)` (prepare-task
+ * has the per-task env in scope), so ONE manager serves all tasks; no sessionId→env registry, no per-task
+ * construction. Sessions are cached per env+language (a language server is heavy — keep it warm per sandbox)
+ * in a WeakMap, so a destroyed task's entries become collectible (its bridge dies with the sandbox).
+ *
+ * Any miss (no env / unknown language / env without the E2B surface / failed open) → `undefined`, which makes
+ * core's tool degrade gracefully to grep/read_file.
+ */
 import path from "node:path";
 import { TransportLspSession, LspDiagnosticsRegistry } from "@sema-agent/core";
+/** Duck-type check: is this ExecutionEnv an E2B adapter with the LSP surface? */
 export function isLspCapable(env) {
     const e = env;
     return typeof e.getHost === "function" && typeof e.startBackground === "function" && typeof e.workspaceHandle === "function";
@@ -23,10 +34,17 @@ const DEFAULT_EXT_TO_LANG = {
     ".rs": "rust",
 };
 export class E2bLspManager {
+    /** Per-sandbox session cache: env (weak) → language → in-flight/ready session. */
     perEnv = new WeakMap();
     factory;
     extToLang;
     log;
+    /** design/121 (core 1.220, board [S] ①): the workspace diagnostics registry — WORKSPACE-scoped (survives
+     *  heal/evict; diagnostics belong to files, not servers), drained by the Runner at turn boundaries. Every
+     *  session feeds it from `textDocument/publishDiagnostics` (the WS transport now dispatches notifications).
+     *  ⚠️ ONE registry across sandboxes on this manager instance (it is per-deployment) — same posture as
+     *  NodeLspManager's workspace scoping; a task only sees diagnostics for files IT touched (delivered-set +
+     *  fileEdited keying is per-uri, and sandbox workspace paths are per-task-unique). */
     diagnostics = new LspDiagnosticsRegistry();
     constructor(opts) {
         this.factory = opts.transportFactory;
@@ -35,7 +53,7 @@ export class E2bLspManager {
     }
     async sessionFor(filePath, _signal, env) {
         if (!env || !isLspCapable(env))
-            return undefined;
+            return undefined; // no env passed (core <1.86.2) or not the E2B adapter → degrade
         const language = this.extToLang[path.extname(filePath).toLowerCase()];
         if (!language)
             return undefined;
@@ -45,7 +63,7 @@ export class E2bLspManager {
             this.perEnv.set(env, sessions);
         }
         let pending = sessions.get(language);
-        const fresh = !pending;
+        const fresh = !pending; // capture BEFORE assigning, or the open/open_failed log is dead code (review 2026-06-10)
         if (!pending) {
             pending = this.open(language, env);
             sessions.set(language, pending);
@@ -54,6 +72,13 @@ export class E2bLspManager {
         if (fresh)
             this.log(session ? "lsp_session_open" : "lsp_session_open_failed", { language });
         if (session?.closed) {
+            // Transport died between tool calls (the E2B proxy idle-kills silent WS connections — live-drill
+            // finding 2026-06-10). Heal: evict + reopen ONCE — the bridge spawns a fresh server per connection.
+            // Carry the dead session's opened files over: a fresh server with no project config only "sees" its
+            // open files, so without the replay cross-file ops silently degrade to single-file (live-repro).
+            // Guard against clobbering a concurrent heal: a racer that lost sees sessions.get !== its pending and
+            // adopts the winner's reopen. ⚠️ Relies on JS run-to-completion — there is NO await between the
+            // delete and the set below (this.open() is CALLED but not awaited); do not insert one.
             const carry = session.openedFiles();
             if (sessions.get(language) === pending)
                 sessions.delete(language);
@@ -64,6 +89,8 @@ export class E2bLspManager {
                 await session.warmOpen(carry);
             this.log(session ? "lsp_session_heal" : "lsp_session_heal_failed", { language, carried: carry.length });
         }
+        // failed open → don't cache the miss (retry next request); guarded so a slow loser awaiting an old failed
+        // pending can't evict a NEWER in-flight session a concurrent call already cached.
         if (!session && sessions.get(language) === pending)
             sessions.delete(language);
         return session;
@@ -78,6 +105,12 @@ export class E2bLspManager {
                 throw new Error("lsp: read failed");
             return r.value;
         };
+        // core 1.190+ `TransportLspSession` (byte-equivalent to the former local RemoteLspSession — service originally
+        // ported it there; core deduplicated it back, single-source). `undefined` warmup ⇒ core's default {windowMs:10_000,
+        // retryMs:1_000}, identical to the old 4-arg call (equivalence-verified). 6th arg (design/121): the
+        // workspace diagnostics registry — the session subscribes publishDiagnostics via transport.onNotification
+        // (version-staleness guarded core-side); absent onNotification would be a silent no-op, but WsLspTransport
+        // now dispatches.
         return new TransportLspSession(transport, language, readText, this.log, undefined, this.diagnostics);
     }
 }

package/dist/lsp/types.d.ts

@@ -1,2 +1,12 @@
+/**
+ * LSP sidecar — service-side types (design/64 §13.1). core 1.82+ ships `createLspTool(manager)`
+ * + the `LspServerManager`/`LspSession`/`LspResult` SEAM (`@sema-agent/core`); the runner mounts the tool
+ * when OUR manager is wired via `RunnerDeps.lspManager`. We re-export core's seam types — SINGLE SOURCE OF TRUTH,
+ * incl. the injectable `LspTransport` (the WS-bridge connection to the language server inside E2B) + `LspReadText`.
+ * The protocol LOGIC + the `TransportLspSession` were originally ported FROM core; core later deduplicated them
+ * back (session.ts/op-map.ts deleted, byte-equivalence verified). The one thing that stays SERVICE-side is the WS
+ * `LspTransport` IMPLEMENTATION (`WsLspTransport` in ws-transport.ts) — core has no WebSocket transport (raw TCP
+ * doesn't traverse E2B's HTTP proxy; WS does). "1:1-copy-CC" is the protocol; the WS transport is ours.
+ */
 export type { LspOperation, LspRequestParams, LspResult, LspLocation, LspSymbolInfo, LspServerManager, LspSession, LspTransport, LspReadText, } from "@sema-agent/core";
 //# sourceMappingURL=types.d.ts.map

package/dist/lsp/ws-transport.d.ts

@@ -1,9 +1,12 @@
 import type { LspTransport } from "./types.js";
+/** The slice of `ws`'s WebSocket the transport uses (so tests can supply a fake). */
 export interface WsLike {
     send(data: string): void;
     close(): void;
     on(event: "message" | "close" | "error" | "pong", listener: (arg?: unknown) => void): void;
+    /** WS ping frame (keepalive + liveness probe). Optional — fakes without it get no ping-liveness. */
     ping?(): void;
+    /** Hard-kill the socket (skip the close handshake) — used when a ping goes unanswered (half-open). */
     terminate?(): void;
 }
 export declare class WsLspTransport implements LspTransport {
@@ -14,15 +17,24 @@ export declare class WsLspTransport implements LspTransport {
     private isClosed;
     private keepalive;
     private awaitingPong;
+    /** design/121: server→client NOTIFICATION subscribers (publishDiagnostics etc.). */
     private readonly notificationHandlers;
     constructor(ws: WsLike, requestTimeoutMs?: number, keepaliveMs?: number);
+    /** Manager-visible liveness (LspTransport.closed): evict + reopen instead of reusing a dead connection. */
     get closed(): boolean;
     private onMessage;
     private failAll;
     request(method: string, params: unknown, signal?: AbortSignal): Promise<unknown>;
     notify(method: string, params: unknown): void;
+    /** design/121 (core 1.220): subscribe to server→client notifications; returns unsubscribe. Additive —
+     *  core's diagnostics registry is the intended consumer; with no subscriber, behavior is byte-identical. */
     onNotification(handler: (method: string, params: unknown) => void): () => void;
     close(): Promise<void>;
 }
+/**
+ * Connect to a language server's WS bridge inside E2B and run the LSP `initialize`/`initialized` handshake.
+ * Returns `undefined` on any failure (→ the manager degrades that language gracefully). `wsUrl` is the
+ * `wss://…e2b.dev` URL from `sandbox.getHost(port)`; `rootPath` is the in-sandbox workspace root.
+ */
 export declare function connectWsLspTransport(wsUrl: string, rootPath: string, signal?: AbortSignal): Promise<LspTransport | undefined>;
 //# sourceMappingURL=ws-transport.d.ts.map

package/dist/lsp/ws-transport.js

@@ -1,5 +1,14 @@
+/**
+ * `WsLspTransport` — LSP JSON-RPC over a WebSocket to the language server inside the E2B sandbox (the bridge
+ * exposed via `sandbox.getHost(port)`). Each WS message is one JSON-RPC message (the LSP-over-WebSocket
+ * convention — no Content-Length framing needed; that's the part that differs from CC's stdio transport). The
+ * socket is behind a minimal `WsLike` interface so the request/response correlation is unit-testable without a
+ * network; `connectWsLspTransport` wires the real `ws` client + the `initialize` handshake.
+ */
 import WebSocket from "ws";
 import { pathToUri } from "@sema-agent/core";
+/** Error-or-event → Error. Bun's ws shim emits browser-style ErrorEvents (NOT instanceof Error) whose
+ *  String() is "[object ErrorEvent]" — extract .message so real failures (e.g. TLS) stay readable. */
 function toError(e) {
     if (e instanceof Error)
         return e;
@@ -14,6 +23,7 @@ export class WsLspTransport {
     isClosed = false;
     keepalive;
     awaitingPong = false;
+    /** design/121: server→client NOTIFICATION subscribers (publishDiagnostics etc.). */
     notificationHandlers = new Set();
     constructor(ws, requestTimeoutMs = 30_000, keepaliveMs = 20_000) {
         this.ws = ws;
@@ -21,17 +31,27 @@ export class WsLspTransport {
         ws.on("message", (data) => this.onMessage(typeof data === "string" ? data : String(data)));
         ws.on("close", () => this.failAll(new Error("LSP websocket closed")));
         ws.on("error", (e) => this.failAll(toError(e)));
+        // Keepalive + LIVENESS: the E2B ingress kills a WS after ~60-75s regardless of traffic (live-tested:
+        // neither ws pings nor app-level data frames prevent it), and the kill can be SILENT — no close frame
+        // reaches us, the socket goes half-open, requests black-hole into the 30s timeout and `closed` never
+        // flips, so the manager keeps reusing a dead session (live-drill: "first op after a thinking gap is
+        // none, the next op heals"). So the ping doubles as a liveness probe: a ping with no pong by the next
+        // interval ⇒ half-open ⇒ fail everything locally + terminate, flipping `closed` so the manager heals
+        // on the very next tool call. `$/keepalive` (LSP spec: `$/` notifications must be ignored) stays as a
+        // best-effort data-frame keepalive for other backends.
         if (keepaliveMs > 0) {
             ws.on("pong", () => {
                 this.awaitingPong = false;
             });
             this.keepalive = setInterval(() => {
                 if (this.awaitingPong) {
+                    // previous ping unanswered for a full interval → half-open connection
                     this.failAll(new Error("LSP websocket unresponsive (no pong)"));
                     try {
                         (ws.terminate ?? ws.close).call(ws);
                     }
                     catch {
+                        /* already gone */
                     }
                     return;
                 }
@@ -41,6 +61,7 @@ export class WsLspTransport {
                         ws.ping();
                     }
                     catch {
+                        /* socket gone — close/error handler does the bookkeeping */
                     }
                 }
                 this.notify("$/keepalive", {});
@@ -48,6 +69,7 @@ export class WsLspTransport {
             this.keepalive.unref?.();
         }
     }
+    /** Manager-visible liveness (LspTransport.closed): evict + reopen instead of reusing a dead connection. */
     get closed() {
         return this.isClosed;
     }
@@ -57,28 +79,40 @@ export class WsLspTransport {
             msg = JSON.parse(raw);
         }
         catch {
-            return;
+            return; // not JSON — ignore
         }
+        // 🔴 A server→client message (has `method`) is a REQUEST (also carries `id`) or a NOTIFICATION (no `id`) — NEVER a
+        // response to us (a JSON-RPC response has no `method`). Handle it FIRST + by `method`, not by `id`:
+        // otherwise a server REQUEST whose `id` (the SERVER's id space) COLLIDES with one of OUR pending request ids would
+        // be `this.pending.get(id)` → resolve OUR request with the server's request as if it were our response = a silent
+        // wrong answer. We implement NO server→client method → reply `-32601 MethodNotFound` to a REQUEST so the server does
+        // not hang waiting (some servers send `workspace/configuration` etc. and block until answered); ignore a NOTIFICATION.
         if (typeof msg.method === "string") {
             if (msg.id !== undefined && msg.id !== null) {
                 try {
                     this.ws.send(JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "method not found" } }));
                 }
                 catch {
+                    /* best-effort — a dead socket fails the pending requests elsewhere */
                 }
-                return;
+                return; // an answered server REQUEST — never our response, never a notification
             }
+            // design/121 (core 1.220 LspTransport.onNotification): a server NOTIFICATION (method, no id) —
+            // publishDiagnostics etc. — now dispatches to subscribers (previously dropped). Contract: swallow a
+            // throwing handler (a bad consumer must never kill the WS read loop). Zero subscribers = old behavior.
             const params = msg.params;
             for (const h of this.notificationHandlers) {
                 try {
                     h(msg.method, params);
                 }
                 catch {
+                    /* per-contract: never let a consumer kill the read loop */
                 }
             }
             return;
         }
         if (typeof msg.id === "number") {
+            // A RESPONSE to one of our requests (no `method` ⇒ a server-request id can no longer hijack a pending entry).
             const p = this.pending.get(msg.id);
             if (p) {
                 this.pending.delete(msg.id);
@@ -104,7 +138,7 @@ export class WsLspTransport {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 if (this.pending.delete(id)) {
-                    signal?.removeEventListener("abort", onAbort);
+                    signal?.removeEventListener("abort", onAbort); // or a long-lived task signal accumulates one listener per timeout
                     reject(new Error(`LSP ${method} timed out after ${this.requestTimeoutMs}ms`));
                 }
             }, this.requestTimeoutMs);
@@ -151,8 +185,11 @@ export class WsLspTransport {
             this.ws.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
         }
         catch {
+            /* fire-and-forget */
         }
     }
+    /** design/121 (core 1.220): subscribe to server→client notifications; returns unsubscribe. Additive —
+     *  core's diagnostics registry is the intended consumer; with no subscriber, behavior is byte-identical. */
     onNotification(handler) {
         this.notificationHandlers.add(handler);
         return () => this.notificationHandlers.delete(handler);
@@ -163,18 +200,28 @@ export class WsLspTransport {
             this.ws.close();
         }
         catch {
+            /* noop */
         }
     }
 }
+/**
+ * Connect to a language server's WS bridge inside E2B and run the LSP `initialize`/`initialized` handshake.
+ * Returns `undefined` on any failure (→ the manager degrades that language gracefully). `wsUrl` is the
+ * `wss://…e2b.dev` URL from `sandbox.getHost(port)`; `rootPath` is the in-sandbox workspace root.
+ */
 export async function connectWsLspTransport(wsUrl, rootPath, signal) {
     let socket;
     try {
         socket = new WebSocket(wsUrl);
+        // Permanent no-op 'error' listener FIRST: Bun's ws shim can emit 'error' again after the once-handler
+        // below consumed the first one (e.g. a late emission while closing a failed socket). An 'error' event
+        // with zero listeners throws and KILLS the process — a bridge-still-booting connect retry crashed the
+        // whole worker in the 2026-06-11 night drill. Control flow still goes through the once-handlers.
         socket.on("error", () => { });
         await new Promise((resolve, reject) => {
             const onAbort = () => reject(new Error("connect aborted"));
             const settle = (fn) => {
-                signal?.removeEventListener("abort", onAbort);
+                signal?.removeEventListener("abort", onAbort); // don't accumulate listeners on a long-lived task signal
                 fn();
             };
             socket.once("open", () => settle(resolve));
@@ -185,9 +232,10 @@ export async function connectWsLspTransport(wsUrl, rootPath, signal) {
     }
     catch {
         try {
-            socket?.close();
+            socket?.close(); // an aborted connect leaves the socket mid-handshake — don't leak it (it WOULD open)
         }
         catch {
+            /* never opened */
         }
         return undefined;
     }

package/dist/lsp-evict.d.ts

@@ -1,2 +1,16 @@
+/**
+ * core 1.191 LSP eviction — the host-lane task-end cleanup wrap, factored out of main.ts so it is unit-testable.
+ *
+ * Decorate an EPHEMERAL host `ExecutionEnv` so its `destroy()` (task-end, which `rm -rf`s the per-task
+ * `sema-host-<id>` workspace) ALSO evicts the cached LSP servers rooted at that workspace — so a busy host server
+ * doesn't retain one heavy language server (jdtls = a whole JVM) per (task × language) until process shutdown.
+ * `evict` is best-effort + idempotent + fire-and-forget so it NEVER blocks or breaks teardown; the server dies async
+ * while the dir is rm'd (rooted there, it just sees ENOENT). Only the ephemeral lane is wrapped by the caller — the
+ * cwdHonored persistent-project path keeps its warm server (stable root, reused across turns = CC-parity, no leak).
+ *
+ * Structural param types (no `ExecutionEnv`/`NodeLspManager` import): a non-evicting manager (e2b/k8s bridge) or an
+ * env without a string `cwd` / callable `destroy` is returned UNWRAPPED (probe-guarded), so this is a safe no-op
+ * everywhere the precondition doesn't hold.
+ */
 export declare function evictLspOnDestroy<E extends object>(env: E, lsp: unknown): E;
 //# sourceMappingURL=lsp-evict.d.ts.map

package/dist/lsp-evict.js

@@ -1,3 +1,17 @@
+/**
+ * core 1.191 LSP eviction — the host-lane task-end cleanup wrap, factored out of main.ts so it is unit-testable.
+ *
+ * Decorate an EPHEMERAL host `ExecutionEnv` so its `destroy()` (task-end, which `rm -rf`s the per-task
+ * `sema-host-<id>` workspace) ALSO evicts the cached LSP servers rooted at that workspace — so a busy host server
+ * doesn't retain one heavy language server (jdtls = a whole JVM) per (task × language) until process shutdown.
+ * `evict` is best-effort + idempotent + fire-and-forget so it NEVER blocks or breaks teardown; the server dies async
+ * while the dir is rm'd (rooted there, it just sees ENOENT). Only the ephemeral lane is wrapped by the caller — the
+ * cwdHonored persistent-project path keeps its warm server (stable root, reused across turns = CC-parity, no leak).
+ *
+ * Structural param types (no `ExecutionEnv`/`NodeLspManager` import): a non-evicting manager (e2b/k8s bridge) or an
+ * env without a string `cwd` / callable `destroy` is returned UNWRAPPED (probe-guarded), so this is a safe no-op
+ * everywhere the precondition doesn't hold.
+ */
 export function evictLspOnDestroy(env, lsp) {
     const evict = lsp?.evict;
     const e = env;
@@ -6,7 +20,7 @@ export function evictLspOnDestroy(env, lsp) {
     const origDestroy = e.destroy.bind(e);
     const root = e.cwd;
     e.destroy = () => {
-        void evict.call(lsp, root).catch(() => { });
+        void evict.call(lsp, root).catch(() => { }); // fire-and-forget: never block/break teardown on a slow server close
         return origDestroy();
     };
     return env;