meshy-node 0.3.8 → 0.4.0

package/main.cjs

@@ -33297,6 +33297,7 @@ function createNodeMessage(kind, payload, options = {}) {
 }
 
 // ../../packages/core/src/messaging/node-message-client.ts
+var RETRYABLE_NODE_MESSAGE_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
 var NodeMessageClient = class {
   constructor(options = {}) {
     this.options = options;
@@ -33335,6 +33336,16 @@ var NodeMessageClient = class {
       throw error;
     }
     if (!response.ok) {
+      if (RETRYABLE_NODE_MESSAGE_STATUSES.has(response.status) && this.options.heartbeat?.enqueueNodeMessage) {
+        this.log?.warn("direct node message delivery returned retryable status; queued for keepalive", {
+          nodeId: node.id,
+          messageId: message.id,
+          kind: message.kind,
+          statusCode: response.status
+        });
+        this.options.heartbeat.enqueueNodeMessage(node.id, message);
+        return { queued: true };
+      }
       throw new Error(await formatHttpError(response));
     }
     return { queued: false };
@@ -34558,6 +34569,10 @@ var NODE_KIND_BY_LEGACY = {
   "node-workdir-tree": "node.workdir.tree",
   "node-workdir-branch-info": "node.workdir.branch-info",
   "node-workdir-branch-create": "node.workdir.branch-create",
+  "node-terminal-session-start": "node.terminal.session.start",
+  "node-terminal-session-list": "node.terminal.session.list",
+  "node-terminal-session-get": "node.terminal.session.get",
+  "node-terminal-session-stop": "node.terminal.session.stop",
   "node-sessions-list": "node.sessions.list",
   devtunnel: "node.transport.set",
   "node-agent-upgrade": "node.agent.upgrade",
@@ -43063,6 +43078,7 @@ var NativeSessionSummarySchema = external_exports.object({
   summary: external_exports.string(),
   updatedAt: external_exports.string().nullable()
 });
+var NodeTerminalSessionStatusSchema = external_exports.enum(["running", "exited", "failed", "stopped"]);
 var NodeListQuery = external_exports.object({
   status: external_exports.enum(["online", "busy", "offline"]).optional(),
   capability: external_exports.string().optional()
@@ -43096,7 +43112,7 @@ var NodeNativeSessionsQuery = external_exports.object({
   agent: external_exports.enum(["codex", "claudecode"]),
   limit: external_exports.coerce.number().int().min(1).max(100).default(50)
 });
-var NodeTerminalExecuteBody = external_exports.object({
+var NodeTerminalSessionStartBody = external_exports.object({
   command: external_exports.string().trim().min(1),
   cwd: external_exports.string().trim().min(1).optional()
 });
@@ -43141,18 +43157,28 @@ var NodeNativeSessionsResponse = external_exports.object({
   agent: external_exports.enum(["codex", "claudecode"]),
   sessions: external_exports.array(NativeSessionSummarySchema)
 });
-var NodeTerminalExecuteResponse = external_exports.object({
+var NodeTerminalSessionResponse = external_exports.object({
+  id: external_exports.string(),
   nodeId: external_exports.string(),
   cwd: external_exports.string(),
   command: external_exports.string(),
+  pid: external_exports.number().int().nullable(),
+  status: NodeTerminalSessionStatusSchema,
   exitCode: external_exports.number().int().nullable(),
+  signal: external_exports.string().nullable(),
   stdout: external_exports.string(),
   stderr: external_exports.string(),
+  startedAt: external_exports.number(),
+  updatedAt: external_exports.number(),
+  completedAt: external_exports.number().optional(),
   durationMs: external_exports.number().int().min(0),
-  timedOut: external_exports.boolean(),
   stdoutTruncated: external_exports.boolean(),
   stderrTruncated: external_exports.boolean()
 });
+var NodeTerminalSessionListResponse = external_exports.object({
+  nodeId: external_exports.string(),
+  sessions: external_exports.array(NodeTerminalSessionResponse)
+});
 var UpdateNodeBody = external_exports.object({
   name: external_exports.string().min(1).optional(),
   capabilities: external_exports.array(external_exports.string()).optional()
@@ -45163,7 +45189,10 @@ var LEGACY_KIND_BY_NODE_MESSAGE = {
   "node.workdir.tree": "node-workdir-tree",
   "node.workdir.branch-info": "node-workdir-branch-info",
   "node.workdir.branch-create": "node-workdir-branch-create",
-  "node.terminal.execute": "node-terminal-execute",
+  "node.terminal.session.start": "node-terminal-session-start",
+  "node.terminal.session.list": "node-terminal-session-list",
+  "node.terminal.session.get": "node-terminal-session-get",
+  "node.terminal.session.stop": "node-terminal-session-stop",
   "node.sessions.list": "node-sessions-list",
   "node.transport.set": "devtunnel",
   "node.agent.upgrade": "node-agent-upgrade",
@@ -45179,9 +45208,13 @@ var LEGACY_KIND_BY_NODE_MESSAGE = {
 function canRequestNodeMessage(heartbeat) {
   return !!(heartbeat?.requestNodeMessage || heartbeat?.requestWorkerControl);
 }
-function requestFallbackNodeMessage(heartbeat, nodeId, message) {
-  if (heartbeat.requestNodeMessage) return heartbeat.requestNodeMessage(nodeId, message);
-  if (heartbeat.requestWorkerControl) return heartbeat.requestWorkerControl(nodeId, toLegacyWorkerControl2(message));
+function requestFallbackNodeMessage(heartbeat, nodeId, message, timeoutMs) {
+  if (heartbeat.requestNodeMessage) {
+    return timeoutMs === void 0 ? heartbeat.requestNodeMessage(nodeId, message) : heartbeat.requestNodeMessage(nodeId, message, timeoutMs);
+  }
+  if (heartbeat.requestWorkerControl) {
+    return timeoutMs === void 0 ? heartbeat.requestWorkerControl(nodeId, toLegacyWorkerControl2(message)) : heartbeat.requestWorkerControl(nodeId, toLegacyWorkerControl2(message), timeoutMs);
+  }
   throw new Error("Node message fallback is not available");
 }
 function toLegacyWorkerControl2(message) {
@@ -45442,16 +45475,18 @@ async function maybeProxyReadToLeader(req, res, options = {}) {
   }
 }
 
-// ../../packages/api/src/node/node-terminal-service.ts
+// ../../packages/api/src/node/node-terminal-session-service.ts
 var import_node_child_process10 = require("child_process");
+var import_node_crypto8 = require("crypto");
+
+// ../../packages/api/src/node/node-terminal-service.ts
 var fs17 = __toESM(require("fs"), 1);
 var path18 = __toESM(require("path"), 1);
-var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_OUTPUT_LIMIT_BYTES = 64 * 1024;
 function isAbsolutePath2(value) {
   return path18.isAbsolute(value) || /^[A-Za-z]:[\/]/.test(value);
 }
-function resolveCommandCwd(nodeId, rootPath, cwd) {
+function resolveNodeTerminalCwd(nodeId, rootPath, cwd) {
   if (!rootPath) {
     throw new MeshyError("VALIDATION_ERROR", `Node ${nodeId} does not expose a working directory`, 400);
   }
@@ -45462,74 +45497,170 @@ function resolveCommandCwd(nodeId, rootPath, cwd) {
   }
   return resolved;
 }
-function captureLimited(chunks, chunk, currentBytes, limitBytes) {
-  if (currentBytes >= limitBytes) {
-    return currentBytes + chunk.length;
+
+// ../../packages/api/src/node/node-terminal-session-service.ts
+var MAX_COMPLETED_SESSIONS = 10;
+function createOutputBuffer() {
+  return { chunks: [], bytes: 0, observedBytes: 0 };
+}
+function appendTail(buffer, chunk, limitBytes) {
+  buffer.observedBytes += chunk.length;
+  const nextChunk = chunk.length > limitBytes ? chunk.subarray(chunk.length - limitBytes) : chunk;
+  buffer.chunks.push(nextChunk);
+  buffer.bytes += nextChunk.length;
+  while (buffer.bytes > limitBytes && buffer.chunks.length > 0) {
+    const first = buffer.chunks[0];
+    if (!first) break;
+    const overflow = buffer.bytes - limitBytes;
+    if (first.length <= overflow) {
+      buffer.chunks.shift();
+      buffer.bytes -= first.length;
+      continue;
+    }
+    buffer.chunks[0] = first.subarray(overflow);
+    buffer.bytes -= overflow;
   }
-  const remaining = limitBytes - currentBytes;
-  chunks.push(chunk.length <= remaining ? chunk : chunk.subarray(0, remaining));
-  return currentBytes + chunk.length;
 }
-function toCapturedOutput(chunks, observedBytes, limitBytes) {
+function readBuffer(buffer, limitBytes) {
   return {
-    text: Buffer.concat(chunks).toString("utf8"),
-    truncated: observedBytes > limitBytes
+    text: Buffer.concat(buffer.chunks, buffer.bytes).toString("utf8"),
+    truncated: buffer.observedBytes > limitBytes
   };
 }
-function executeLocalNodeTerminalCommand(nodeId, rootPath, command, options = {}) {
-  const normalizedCommand = command.trim();
-  if (!normalizedCommand) {
-    throw new MeshyError("VALIDATION_ERROR", "Command must not be empty", 400);
+function cloneSession(session) {
+  return { ...session };
+}
+function killSessionProcess(state3, signal) {
+  const child = state3.process;
+  if (!child) return;
+  const pid = child.pid;
+  if (process.platform !== "win32" && typeof pid === "number") {
+    try {
+      process.kill(-pid, signal);
+      return;
+    } catch {
+    }
   }
-  const cwd = resolveCommandCwd(nodeId, rootPath, options.cwd);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const outputLimitBytes = options.outputLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
-  const startedAt = Date.now();
-  const stdoutChunks = [];
-  const stderrChunks = [];
-  let stdoutBytes = 0;
-  let stderrBytes = 0;
-  let timedOut = false;
-  return new Promise((resolve15, reject) => {
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
+var NodeTerminalSessionService = class {
+  sessions = /* @__PURE__ */ new Map();
+  nextSequence = 0;
+  start(nodeId, rootPath, command, options = {}) {
+    const normalizedCommand = command.trim();
+    if (!normalizedCommand) {
+      throw new MeshyError("VALIDATION_ERROR", "Command must not be empty", 400);
+    }
+    const cwd = resolveNodeTerminalCwd(nodeId, rootPath, options.cwd);
+    const startedAt = Date.now();
     const child = (0, import_node_child_process10.spawn)(normalizedCommand, {
       cwd,
       shell: true,
       windowsHide: true,
-      stdio: ["ignore", "pipe", "pipe"]
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32"
     });
-    const timeout = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGTERM");
-    }, timeoutMs);
+    const session = {
+      id: (0, import_node_crypto8.randomUUID)(),
+      nodeId,
+      cwd,
+      command: normalizedCommand,
+      pid: child.pid ?? null,
+      status: "running",
+      exitCode: null,
+      signal: null,
+      stdout: "",
+      stderr: "",
+      startedAt,
+      updatedAt: startedAt,
+      durationMs: 0,
+      stdoutTruncated: false,
+      stderrTruncated: false
+    };
+    const state3 = {
+      session,
+      process: child,
+      stdout: createOutputBuffer(),
+      stderr: createOutputBuffer(),
+      sequence: this.nextSequence++
+    };
+    const outputLimitBytes = options.outputLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
+    this.sessions.set(session.id, state3);
     child.stdout?.on("data", (chunk) => {
-      stdoutBytes = captureLimited(stdoutChunks, chunk, stdoutBytes, outputLimitBytes);
+      appendTail(state3.stdout, chunk, outputLimitBytes);
+      this.refreshOutput(state3, outputLimitBytes);
     });
     child.stderr?.on("data", (chunk) => {
-      stderrBytes = captureLimited(stderrChunks, chunk, stderrBytes, outputLimitBytes);
+      if (state3.session.status === "stopped") return;
+      appendTail(state3.stderr, chunk, outputLimitBytes);
+      this.refreshOutput(state3, outputLimitBytes);
     });
     child.on("error", (err) => {
-      clearTimeout(timeout);
-      reject(new MeshyError("VALIDATION_ERROR", err.message, 400));
-    });
-    child.on("close", (code) => {
-      clearTimeout(timeout);
-      const stdout = toCapturedOutput(stdoutChunks, stdoutBytes, outputLimitBytes);
-      const stderr = toCapturedOutput(stderrChunks, stderrBytes, outputLimitBytes);
-      resolve15({
-        nodeId,
-        cwd,
-        command: normalizedCommand,
-        exitCode: code,
-        stdout: stdout.text,
-        stderr: stderr.text,
-        durationMs: Date.now() - startedAt,
-        timedOut,
-        stdoutTruncated: stdout.truncated,
-        stderrTruncated: stderr.truncated
-      });
+      state3.session.status = "failed";
+      state3.session.stderr = state3.session.stderr ? `${state3.session.stderr}
+${err.message}` : err.message;
+      this.complete(state3, null, null, outputLimitBytes);
     });
-  });
-}
+    child.on("close", (code, signal) => {
+      if (state3.session.status !== "stopped") {
+        state3.session.status = code === 0 ? "exited" : "failed";
+      }
+      this.complete(state3, code, signal, outputLimitBytes);
+    });
+    return cloneSession(session);
+  }
+  list() {
+    return Array.from(this.sessions.values()).sort((a, b) => b.sequence - a.sequence).map((state3) => cloneSession(state3.session));
+  }
+  get(id) {
+    const state3 = this.sessions.get(id);
+    return state3 ? cloneSession(state3.session) : null;
+  }
+  stop(id) {
+    const state3 = this.sessions.get(id);
+    if (!state3) return null;
+    if (state3.session.status === "running") {
+      state3.session.status = "stopped";
+      state3.session.updatedAt = Date.now();
+      killSessionProcess(state3, "SIGTERM");
+      setTimeout(() => {
+        if (state3.session.status === "stopped" && !state3.session.completedAt) {
+          killSessionProcess(state3, "SIGKILL");
+        }
+      }, 2e3).unref?.();
+    }
+    return cloneSession(state3.session);
+  }
+  refreshOutput(state3, outputLimitBytes) {
+    const stdout = readBuffer(state3.stdout, outputLimitBytes);
+    const stderr = readBuffer(state3.stderr, outputLimitBytes);
+    state3.session.stdout = stdout.text;
+    state3.session.stderr = stderr.text;
+    state3.session.stdoutTruncated = stdout.truncated;
+    state3.session.stderrTruncated = stderr.truncated;
+    state3.session.updatedAt = Date.now();
+    state3.session.durationMs = state3.session.updatedAt - state3.session.startedAt;
+  }
+  complete(state3, exitCode, signal, outputLimitBytes) {
+    this.refreshOutput(state3, outputLimitBytes);
+    state3.session.exitCode = exitCode;
+    state3.session.signal = signal;
+    state3.session.completedAt = Date.now();
+    state3.session.updatedAt = state3.session.completedAt;
+    state3.session.durationMs = state3.session.completedAt - state3.session.startedAt;
+    state3.process = null;
+    this.pruneCompletedSessions();
+  }
+  pruneCompletedSessions() {
+    const completed = Array.from(this.sessions.values()).filter((state3) => state3.session.status !== "running").sort((a, b) => b.sequence - a.sequence);
+    for (const state3 of completed.slice(MAX_COMPLETED_SESSIONS)) {
+      this.sessions.delete(state3.session.id);
+    }
+  }
+};
 
 // ../../packages/api/src/node/node-native-session-service.ts
 function getLocalNodeNativeSessions(nodeId, agent, limit) {
@@ -46615,6 +46746,10 @@ function payloadValue(request, key, fallback) {
   const value = request.payload[key];
   return value === void 0 ? fallback : value;
 }
+function getTerminalSessionService(deps) {
+  deps.terminalSessionService ??= new NodeTerminalSessionService();
+  return deps.terminalSessionService;
+}
 function maybeImportTaskSnapshot(deps, request) {
   if (!request.kind.startsWith("task.output.") && request.kind !== "task.preview.create" && request.kind !== "task.logs") return;
   const task = payloadValue(request, "task", null);
@@ -46692,12 +46827,12 @@ async function executeWorkerControlRequest(deps, request) {
         );
         break;
       }
-      case "node.terminal.execute": {
+      case "node.terminal.session.start": {
         const self2 = deps.nodeRegistry.getSelf();
         response = jsonResponse(
           request.id,
-          200,
-          await executeLocalNodeTerminalCommand(
+          202,
+          getTerminalSessionService(deps).start(
             self2.id,
             self2.workDir ?? deps.workDir,
             payloadValue(request, "command", ""),
@@ -46706,6 +46841,28 @@ async function executeWorkerControlRequest(deps, request) {
         );
         break;
       }
+      case "node.terminal.session.list": {
+        const self2 = deps.nodeRegistry.getSelf();
+        response = jsonResponse(request.id, 200, {
+          nodeId: self2.id,
+          sessions: getTerminalSessionService(deps).list()
+        });
+        break;
+      }
+      case "node.terminal.session.get": {
+        const sessionId = payloadValue(request, "sessionId", "");
+        const session = getTerminalSessionService(deps).get(sessionId);
+        if (!session) throw new MeshyError("NODE_NOT_FOUND", `Terminal session ${sessionId} not found`, 404);
+        response = jsonResponse(request.id, 200, session);
+        break;
+      }
+      case "node.terminal.session.stop": {
+        const sessionId = payloadValue(request, "sessionId", "");
+        const session = getTerminalSessionService(deps).stop(sessionId);
+        if (!session) throw new MeshyError("NODE_NOT_FOUND", `Terminal session ${sessionId} not found`, 404);
+        response = jsonResponse(request.id, 200, session);
+        break;
+      }
       case "node.sessions.list": {
         const self2 = deps.nodeRegistry.getSelf();
         response = jsonResponse(
@@ -46954,142 +47111,89 @@ async function sendNodeAgentUpgrade(req, res, nodeId, agentParam) {
 }
 
 // ../../packages/api/src/routes/node-terminal.ts
-var NODE_TERMINAL_PROXY_TIMEOUT_MS = 35e3;
-function describeProxyError2(error) {
-  if (error instanceof Error) {
-    const errorCategory = error.name === "AbortError" || /aborted/i.test(error.message) ? "abort" : /timeout/i.test(error.message) ? "timeout" : "network";
-    return {
-      errorName: error.name,
-      errorMessage: error.message,
-      errorCategory
-    };
-  }
-  return {
-    errorName: "UnknownError",
-    errorMessage: String(error),
-    errorCategory: "unknown"
-  };
+var TERMINAL_SESSION_PROXY_TIMEOUT_MS = 1e4;
+function getTerminalSessionService2(deps) {
+  deps.terminalSessionService ??= new NodeTerminalSessionService();
+  return deps.terminalSessionService;
 }
-function createNodeTerminalProxyTrace(log2, nodeId, proxyPath) {
-  return {
-    onAttempt: ({ attempt, endpoint, timeoutMs, totalEndpoints }) => {
-      log2.debug("node terminal proxy attempt", {
-        nodeId,
-        proxyPath,
-        endpoint,
-        attempt,
-        totalEndpoints,
-        timeoutMs
-      });
-    },
-    onResponse: ({ attempt, endpoint, response, timeoutMs, totalEndpoints }) => {
-      log2.info("node terminal proxy response", {
-        nodeId,
-        proxyPath,
-        endpoint,
-        attempt,
-        totalEndpoints,
-        timeoutMs,
-        ok: response.ok,
-        statusCode: response.status
-      });
-    },
-    onError: ({ attempt, endpoint, error, timeoutMs, totalEndpoints }) => {
-      log2.warn("node terminal proxy attempt failed", {
-        nodeId,
-        proxyPath,
-        endpoint,
-        attempt,
-        totalEndpoints,
-        timeoutMs,
-        ...describeProxyError2(error)
-      });
+async function sendRemoteTerminalSessionRequest(req, res, nodeId, message) {
+  const deps = req.app.locals.deps;
+  const node = deps.nodeRegistry.getNode(nodeId);
+  if (!node) throw new MeshyError("NODE_NOT_FOUND", `Node ${nodeId} not found`, 404);
+  const heartbeat = deps.heartbeat;
+  const canPushToNode = heartbeat.canPushToNode?.(nodeId) ?? true;
+  let response;
+  if (!canPushToNode && canRequestNodeMessage(heartbeat)) {
+    response = await requestFallbackNodeMessage(heartbeat, nodeId, message, TERMINAL_SESSION_PROXY_TIMEOUT_MS);
+  } else {
+    try {
+      response = await new NodeMessageClient({
+        logger: deps.logger,
+        timeoutMs: TERMINAL_SESSION_PROXY_TIMEOUT_MS
+      }).request(node, message);
+    } catch (err) {
+      if (canRequestNodeMessage(heartbeat)) {
+        response = await requestFallbackNodeMessage(heartbeat, nodeId, message, TERMINAL_SESSION_PROXY_TIMEOUT_MS);
+      } else {
+        throw new MeshyError("NODE_OFFLINE", `Cannot reach node ${nodeId} for terminal session control`, 502, {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
     }
-  };
-}
-async function maybeHandleRemoteNodeTerminalExecuteRequest(req, res, nodeId) {
-  const body = NodeTerminalExecuteBody.parse(req.body);
-  const { nodeRegistry, heartbeat, logger: rootLogger } = req.app.locals.deps;
-  const selfId = nodeRegistry.getSelf().id;
-  if (nodeId === selfId) {
-    return false;
   }
-  const node = nodeRegistry.getNode(nodeId);
-  if (!node) {
-    throw new MeshyError("NODE_NOT_FOUND", `Node ${nodeId} not found`, 404);
+  sendWorkerControlResponse(res, response);
+}
+async function sendNodeTerminalSessionStart(req, res, nodeId) {
+  const body = NodeTerminalSessionStartBody.parse(req.body);
+  const deps = req.app.locals.deps;
+  const self2 = deps.nodeRegistry.getSelf();
+  if (nodeId !== self2.id) {
+    await sendRemoteTerminalSessionRequest(req, res, nodeId, createNodeMessage("node.terminal.session.start", {
+      command: body.command,
+      cwd: body.cwd
+    }, { expectsResponse: true }));
+    return;
   }
-  const log2 = rootLogger.child("nodes/terminal");
-  const proxyPath = req.originalUrl ?? `/api/nodes/${nodeId}/terminal/execute`;
-  const fallbackRequest = createNodeMessage("node.terminal.execute", {
-    command: body.command,
-    cwd: body.cwd
-  }, { expectsResponse: true });
-  const canPushToNode = heartbeat?.canPushToNode?.(nodeId) ?? true;
-  if (!canPushToNode && canRequestNodeMessage(heartbeat)) {
-    log2.warn("node terminal request falling back to keepalive control", { nodeId, proxyPath });
-    const controlResponse = await requestFallbackNodeMessage(heartbeat, nodeId, fallbackRequest);
-    sendWorkerControlResponse(res, controlResponse);
-    return true;
+  const session = getTerminalSessionService2(deps).start(self2.id, self2.workDir ?? deps.workDir, body.command, { cwd: body.cwd });
+  res.status(202).json(session);
+}
+async function sendNodeTerminalSessionList(req, res, nodeId) {
+  const deps = req.app.locals.deps;
+  const self2 = deps.nodeRegistry.getSelf();
+  if (nodeId !== self2.id) {
+    await sendRemoteTerminalSessionRequest(req, res, nodeId, createNodeMessage("node.terminal.session.list", {}, { expectsResponse: true }));
+    return;
   }
-  try {
-    const { endpoint, response } = await fetchNodeWithFallback(
-      node,
-      proxyPath,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body)
-      },
-      NODE_TERMINAL_PROXY_TIMEOUT_MS,
-      createNodeTerminalProxyTrace(log2, nodeId, proxyPath),
-      { preferPublicEndpoint: true }
-    );
-    log2.debug("proxying node terminal request", { nodeId, endpoint, proxyPath });
-    await sendProxyResponse(res, response);
-    return true;
-  } catch (err) {
-    const errorDetails = describeProxyError2(err);
-    log2.warn("node terminal proxy error", {
-      nodeId,
-      proxyPath,
-      timeoutMs: NODE_TERMINAL_PROXY_TIMEOUT_MS,
-      ...errorDetails
-    });
-    if (canRequestNodeMessage(heartbeat)) {
-      log2.warn("node terminal proxy failed, falling back to keepalive control", {
-        nodeId,
-        proxyPath,
-        timeoutMs: NODE_TERMINAL_PROXY_TIMEOUT_MS,
-        ...errorDetails
-      });
-      const controlResponse = await requestFallbackNodeMessage(heartbeat, nodeId, fallbackRequest);
-      sendWorkerControlResponse(res, controlResponse);
-      return true;
-    }
-    throw new MeshyError("NODE_OFFLINE", `Cannot reach node ${nodeId} to execute a terminal command`, 502);
+  res.json({ nodeId: self2.id, sessions: getTerminalSessionService2(deps).list() });
+}
+async function sendNodeTerminalSessionGet(req, res, nodeId, sessionId) {
+  const deps = req.app.locals.deps;
+  const self2 = deps.nodeRegistry.getSelf();
+  if (nodeId !== self2.id) {
+    await sendRemoteTerminalSessionRequest(req, res, nodeId, createNodeMessage("node.terminal.session.get", { sessionId }, { expectsResponse: true }));
+    return;
   }
+  const session = getTerminalSessionService2(deps).get(sessionId);
+  if (!session) throw new MeshyError("NODE_NOT_FOUND", `Terminal session ${sessionId} not found`, 404);
+  res.json(session);
 }
-async function sendLocalNodeTerminalExecute(req, res, nodeId) {
-  const body = NodeTerminalExecuteBody.parse(req.body);
-  const { nodeRegistry, workDir } = req.app.locals.deps;
-  const self2 = nodeRegistry.getSelf();
+async function sendNodeTerminalSessionStop(req, res, nodeId, sessionId) {
+  const deps = req.app.locals.deps;
+  const self2 = deps.nodeRegistry.getSelf();
   if (nodeId !== self2.id) {
-    throw new MeshyError("NODE_NOT_FOUND", `Node ${nodeId} not found`, 404);
+    await sendRemoteTerminalSessionRequest(req, res, nodeId, createNodeMessage("node.terminal.session.stop", { sessionId }, { expectsResponse: true }));
+    return;
   }
-  const result = await executeLocalNodeTerminalCommand(
-    self2.id,
-    self2.workDir ?? workDir,
-    body.command,
-    { cwd: body.cwd }
-  );
-  res.json(result);
+  const session = getTerminalSessionService2(deps).stop(sessionId);
+  if (!session) throw new MeshyError("NODE_NOT_FOUND", `Terminal session ${sessionId} not found`, 404);
+  res.json(session);
 }
 
 // ../../packages/api/src/routes/nodes.ts
 var NODE_WORKDIR_PROXY_TIMEOUT_MS = 1e4;
 var NODE_WORKDIR_BRANCH_PROXY_TIMEOUT_MS = 25e3;
 var NODE_NATIVE_SESSIONS_PROXY_TIMEOUT_MS = 1e4;
-function describeProxyError3(error) {
+function describeProxyError2(error) {
   if (error instanceof Error) {
     const errorCategory = error.name === "AbortError" || /aborted/i.test(error.message) ? "abort" : /timeout/i.test(error.message) ? "timeout" : "network";
     return {
@@ -47136,7 +47240,7 @@ function createNodeWorkdirProxyTrace(log2, nodeId, proxyPath) {
         attempt,
         totalEndpoints,
         timeoutMs,
-        ...describeProxyError3(error)
+        ...describeProxyError2(error)
       });
     }
   };
@@ -47191,7 +47295,7 @@ async function maybeHandleRemoteNodeWorkDirRequest(req, res, nodeId) {
     await sendProxyResponse(res, response);
     return true;
   } catch (err) {
-    const errorDetails = describeProxyError3(err);
+    const errorDetails = describeProxyError2(err);
     log2.warn("node workdir proxy error", {
       nodeId,
       proxyPath,
@@ -47258,7 +47362,7 @@ async function maybeHandleRemoteNodeWorkDirBranchInfoRequest(req, res, nodeId) {
     await sendProxyResponse(res, response);
     return true;
   } catch (err) {
-    const errorDetails = describeProxyError3(err);
+    const errorDetails = describeProxyError2(err);
     log2.warn("node workdir branch proxy error", {
       nodeId,
       proxyPath,
@@ -47323,7 +47427,7 @@ async function maybeHandleRemoteNodeNativeSessionsRequest(req, res, nodeId) {
     await sendProxyResponse(res, response);
     return true;
   } catch (err) {
-    const errorDetails = describeProxyError3(err);
+    const errorDetails = describeProxyError2(err);
     log2.warn("node native sessions proxy error", {
       nodeId,
       proxyPath,
@@ -47410,13 +47514,17 @@ function createNodeRoutes() {
     }
     sendLocalNodeWorkDirBranchInfo(req, res, nodeId);
   }));
-  router.post("/:id/terminal/execute", asyncHandler3(async (req, res) => {
-    const nodeId = req.params.id;
-    const handled = await maybeHandleRemoteNodeTerminalExecuteRequest(req, res, nodeId);
-    if (handled) {
-      return;
-    }
-    await sendLocalNodeTerminalExecute(req, res, nodeId);
+  router.get("/:id/terminal/sessions", asyncHandler3(async (req, res) => {
+    await sendNodeTerminalSessionList(req, res, req.params.id);
+  }));
+  router.post("/:id/terminal/sessions", asyncHandler3(async (req, res) => {
+    await sendNodeTerminalSessionStart(req, res, req.params.id);
+  }));
+  router.get("/:id/terminal/sessions/:sessionId", asyncHandler3(async (req, res) => {
+    await sendNodeTerminalSessionGet(req, res, req.params.id, req.params.sessionId);
+  }));
+  router.post("/:id/terminal/sessions/:sessionId/stop", asyncHandler3(async (req, res) => {
+    await sendNodeTerminalSessionStop(req, res, req.params.id, req.params.sessionId);
   }));
   router.post("/:id/workdir/branch", asyncHandler3(async (req, res) => {
     const nodeId = req.params.id;
@@ -47837,7 +47945,7 @@ function getTaskLogsProxyRequestMetadata(req) {
   const sourceNodeId = req.get(TASK_LOG_PROXY_SOURCE_HEADER) ?? void 0;
   return { isProxy: purpose === TASK_LOG_PROXY_PURPOSE, sourceNodeId, task: decodeTaskSnapshot(req.get(TASK_LOG_PROXY_TASK_HEADER)) };
 }
-function describeProxyError4(error) {
+function describeProxyError3(error) {
   if (error instanceof Error) {
     const errorCategory = error.name === "AbortError" || /aborted/i.test(error.message) ? "abort" : /timeout/i.test(error.message) ? "timeout" : "network";
     return {
@@ -47879,7 +47987,7 @@ function createTaskLogsProxyTrace(log2, taskId, nodeId, proxyPath) {
         attempt,
         totalEndpoints,
         timeoutMs,
-        ...describeProxyError4(error)
+        ...describeProxyError3(error)
       });
     }
   };
@@ -47957,7 +48065,7 @@ async function sendTaskLogsResponse(req, res, taskId) {
         log2.warn("failed to seed task snapshot before task logs proxy", {
           taskId,
           assignedTo,
-          ...describeProxyError4(err)
+          ...describeProxyError3(err)
         });
         return [];
       });
@@ -47990,7 +48098,7 @@ async function sendTaskLogsResponse(req, res, taskId) {
           taskId,
           assignedTo,
           timeoutMs: TASK_LOG_PROXY_TIMEOUT_MS,
-          ...describeProxyError4(err)
+          ...describeProxyError3(err)
         });
         const fallback = await requestTaskLogsOverKeepalive(heartbeat, assignedTo, task, after);
         if (fallback) {
@@ -48067,7 +48175,7 @@ function resolveRequestOrigin(req) {
 
 // ../../packages/api/src/routes/task-output.ts
 var TASK_OUTPUT_PROXY_TIMEOUT_MS = 1e4;
-function describeProxyError5(error) {
+function describeProxyError4(error) {
   if (error instanceof Error) {
     const errorCategory = error.name === "AbortError" || /aborted/i.test(error.message) ? "abort" : /timeout/i.test(error.message) ? "timeout" : "network";
     return {
@@ -48120,7 +48228,7 @@ function createTaskOutputProxyTrace(log2, taskId, assignedTo, kind, proxyPath) {
         attempt,
         totalEndpoints,
         timeoutMs,
-        ...describeProxyError5(error)
+        ...describeProxyError4(error)
       });
     }
   };
@@ -48238,7 +48346,7 @@ async function maybeHandleRemoteTaskOutputRequest(req, res, taskId, subPath, ini
         assignedTo: assignedNodeId,
         kind: hydratedFallbackRequest.kind,
         timeoutMs: TASK_OUTPUT_PROXY_TIMEOUT_MS,
-        ...describeProxyError5(err)
+        ...describeProxyError4(err)
       });
       const controlResponse = await requestFallbackNodeMessage(heartbeat, assignedNodeId, hydratedFallbackRequest);
       if (hydratedFallbackRequest.kind === "task.preview.create" && controlResponse.bodyEncoding === "json" && isPreviewSessionPayload(controlResponse.body)) {
@@ -48255,7 +48363,7 @@ async function maybeHandleRemoteTaskOutputRequest(req, res, taskId, subPath, ini
       assignedTo: assignedNodeId,
       kind: messageKind,
       timeoutMs: TASK_OUTPUT_PROXY_TIMEOUT_MS,
-      ...describeProxyError5(err)
+      ...describeProxyError4(err)
     });
     throw new MeshyError("NODE_OFFLINE", "Cannot reach worker for task output", 502);
   }