@love-moon/conductor-cli 0.2.18 → 0.2.20

package/src/daemon.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -9,11 +10,13 @@ import yaml from "js-yaml";
 
 import { ConductorWebSocketClient, ConductorConfig, loadConfig, ConfigFileNotFound } from "@love-moon/conductor-sdk";
 import { DaemonLogCollector } from "./log-collector.js";
+import { filterRuntimeSupportedAllowCliList, normalizeRuntimeBackendName } from "./runtime-backends.js";
 
 dotenv.config();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const moduleRequire = createRequire(import.meta.url);
 const CLI_PATH = path.resolve(__dirname, "..", "bin", "conductor-fire.js");
 const DAEMON_LOG_DIR = path.join(os.homedir(), ".conductor", "logs");
 const DAEMON_LOG_PATH = path.join(DAEMON_LOG_DIR, "conductor-daemon.log");
@@ -22,6 +25,11 @@ const PLAN_LIMIT_MESSAGES = {
   app_active_task: "Free plan limit reached: only 1 active app task is allowed.",
   daemon_active_connection: "Free plan limit reached: only 1 active daemon connection is allowed.",
 };
+const DEFAULT_TERMINAL_COLS = 120;
+const DEFAULT_TERMINAL_ROWS = 40;
+const DEFAULT_TERMINAL_RING_BUFFER_MAX_BYTES = 2 * 1024 * 1024;
+const DEFAULT_RTC_MODULE_CANDIDATES = ["@roamhq/wrtc", "wrtc"];
+let nodePtySpawnPromise = null;
 
 function appendDaemonLog(line) {
   try {
@@ -112,16 +120,137 @@ function getPlanLimitMessage(payload) {
 const DEFAULT_CLI_LIST = {
   codex: "codex --dangerously-bypass-approvals-and-sandbox",
   claude: "claude --dangerously-skip-permissions",
+  opencode: "opencode",
 };
 
 function getAllowCliList(userConfig) {
   // If user has configured allow_cli_list, use it; otherwise use defaults
   if (userConfig.allow_cli_list && typeof userConfig.allow_cli_list === "object") {
-    return userConfig.allow_cli_list;
+    return filterRuntimeSupportedAllowCliList(userConfig.allow_cli_list);
   }
   return DEFAULT_CLI_LIST;
 }
 
+async function defaultCreatePty(command, args, options) {
+  if (!nodePtySpawnPromise) {
+    const spawnHelperInfo = ensureNodePtySpawnHelperExecutable();
+    if (spawnHelperInfo?.updated) {
+      log(`Enabled execute permission on node-pty spawn-helper: ${spawnHelperInfo.helperPath}`);
+    }
+    nodePtySpawnPromise = import("node-pty").then((mod) => {
+      if (typeof mod.spawn === "function") {
+        return mod.spawn;
+      }
+      if (mod.default && typeof mod.default.spawn === "function") {
+        return mod.default.spawn.bind(mod.default);
+      }
+      throw new Error("node-pty spawn export not found");
+    });
+  }
+  const spawnPty = await nodePtySpawnPromise;
+  return spawnPty(command, args, options);
+}
+
+export function ensureNodePtySpawnHelperExecutable(deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === "win32") {
+    return null;
+  }
+
+  const arch = deps.arch || process.arch;
+  const existsSyncFn = deps.existsSync || fs.existsSync;
+  const statSyncFn = deps.statSync || fs.statSync;
+  const chmodSyncFn = deps.chmodSync || fs.chmodSync;
+  let packageJsonPath = deps.packageJsonPath || null;
+
+  if (!packageJsonPath) {
+    try {
+      packageJsonPath = moduleRequire.resolve("node-pty/package.json");
+    } catch {
+      return null;
+    }
+  }
+
+  const packageDir = path.dirname(packageJsonPath);
+  const helperCandidates = [
+    path.join(packageDir, "build", "Release", "spawn-helper"),
+    path.join(packageDir, "build", "Debug", "spawn-helper"),
+    path.join(packageDir, "prebuilds", `${platform}-${arch}`, "spawn-helper"),
+  ];
+  const helperPath = helperCandidates.find((candidate) => existsSyncFn(candidate));
+  if (!helperPath) {
+    return null;
+  }
+
+  const currentMode = statSyncFn(helperPath).mode & 0o777;
+  if ((currentMode & 0o111) !== 0) {
+    return { helperPath, updated: false };
+  }
+
+  const nextMode = currentMode | 0o111;
+  chmodSyncFn(helperPath, nextMode);
+  return { helperPath, updated: true };
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized || null;
+}
+
+function normalizePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function normalizeNonNegativeInt(value, fallback = null) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (Number.isFinite(parsed) && parsed >= 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function normalizeIsoTimestamp(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    return null;
+  }
+  return Number.isNaN(Date.parse(normalized)) ? null : normalized;
+}
+
+function normalizeLaunchConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+
+function normalizeTerminalEnv(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const env = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      env[key] = raw;
+      continue;
+    }
+    if (typeof raw === "number" || typeof raw === "boolean") {
+      env[key] = String(raw);
+    }
+  }
+  return env;
+}
+
 export function startDaemon(config = {}, deps = {}) {
   const exitFn = deps.exit || process.exit;
   const killFn = deps.kill || process.kill;
@@ -210,10 +339,14 @@ export function startDaemon(config = {}, deps = {}) {
   const renameSyncFn = deps.renameSync || fs.renameSync;
   const createWriteStreamFn = deps.createWriteStream || fs.createWriteStream;
   const fetchFn = deps.fetch || fetch;
+  const createRtcPeerConnection = deps.createRtcPeerConnection || null;
+  const importOptionalModule = deps.importOptionalModule || ((moduleName) => import(moduleName));
   const createWebSocketClient =
     deps.createWebSocketClient ||
     ((clientConfig, options) => new ConductorWebSocketClient(clientConfig, options));
   const createLogCollector = deps.createLogCollector || ((backendUrl) => new DaemonLogCollector(backendUrl));
+  const RTC_MODULE_CANDIDATES = resolveRtcModuleCandidates(process.env.CONDUCTOR_PTY_RTC_MODULES);
+  const RTC_DIRECT_DISABLED = parseBooleanEnv(process.env.CONDUCTOR_DISABLE_PTY_DIRECT_RTC);
   const PROJECT_PATH_LOOKUP_TIMEOUT_MS = parsePositiveInt(
     process.env.CONDUCTOR_PROJECT_PATH_LOOKUP_TIMEOUT_MS,
     1500,
@@ -254,6 +387,10 @@ export function startDaemon(config = {}, deps = {}) {
     process.env.CONDUCTOR_DAEMON_WATCHDOG_MAX_SELF_HEALS,
     3,
   );
+  const TERMINAL_RING_BUFFER_MAX_BYTES = parsePositiveInt(
+    config.TERMINAL_RING_BUFFER_MAX_BYTES || process.env.CONDUCTOR_TERMINAL_RING_BUFFER_MAX_BYTES,
+    DEFAULT_TERMINAL_RING_BUFFER_MAX_BYTES,
+  );
 
   try {
     mkdirSyncFn(WORKSPACE_ROOT, { recursive: true });
@@ -389,6 +526,8 @@ export function startDaemon(config = {}, deps = {}) {
   let didRecoverStaleTasks = false;
   let daemonShuttingDown = false;
   const activeTaskProcesses = new Map();
+  const activePtySessions = new Map();
+  const activePtyRtcTransports = new Map();
   const suppressedExitStatusReports = new Set();
   const seenCommandRequestIds = new Set();
   let lastConnectedAt = null;
@@ -405,11 +544,15 @@ export function startDaemon(config = {}, deps = {}) {
   let watchdogLastPresenceMismatchAt = 0;
   let watchdogAwaitingHealthySignalAt = null;
   let watchdogTimer = null;
+  let rtcImplementationPromise = null;
+  let rtcAvailabilityLogKey = null;
   const logCollector = createLogCollector(BACKEND_HTTP);
+  const createPtyFn = deps.createPty || defaultCreatePty;
   const client = createWebSocketClient(sdkConfig, {
     extraHeaders: {
       "x-conductor-host": AGENT_NAME,
       "x-conductor-backends": SUPPORTED_BACKENDS.join(","),
+      "x-conductor-capabilities": "pty_task",
     },
     onConnected: ({ isReconnect, connectedAt } = { isReconnect: false, connectedAt: Date.now() }) => {
       wsConnected = true;
@@ -626,6 +769,10 @@ export function startDaemon(config = {}, deps = {}) {
     }
   }
 
+  const getActiveTaskIds = () => [
+    ...new Set([...activeTaskProcesses.keys(), ...activePtySessions.keys()]),
+  ];
+
   async function recoverStaleTasks() {
     try {
       const response = await fetchFn(`${BACKEND_HTTP}/api/tasks`, {
@@ -701,7 +848,7 @@ export function startDaemon(config = {}, deps = {}) {
       if (!Array.isArray(tasks)) {
         return;
       }
-      const localTaskIds = new Set(activeTaskProcesses.keys());
+      const localTaskIds = new Set(getActiveTaskIds());
       const assigned = tasks.filter((task) => {
         const agentHost = String(task?.agent_host || "").trim();
         const status = String(task?.status || "").trim().toLowerCase();
@@ -746,7 +893,7 @@ export function startDaemon(config = {}, deps = {}) {
     await client.sendJson({
       type: "agent_resume",
       payload: {
-        active_tasks: [...activeTaskProcesses.keys()],
+        active_tasks: getActiveTaskIds(),
         source: "conductor-daemon",
         metadata: { is_reconnect: Boolean(isReconnect) },
       },
@@ -781,6 +928,858 @@ export function startDaemon(config = {}, deps = {}) {
     });
   }
 
+  function sendTerminalEvent(type, payload) {
+    return client.sendJson({
+      type,
+      payload,
+    });
+  }
+
+  function sendPtyTransportStatus(payload) {
+    return client.sendJson({
+      type: "pty_transport_status",
+      payload,
+    });
+  }
+
+  function sendPtyTransportSignal(payload) {
+    return client.sendJson({
+      type: "pty_transport_signal",
+      payload,
+    });
+  }
+
+  function logRtcAvailabilityOnce(key, message) {
+    if (rtcAvailabilityLogKey === key) {
+      return;
+    }
+    rtcAvailabilityLogKey = key;
+    log(message);
+  }
+
+  async function resolveRtcImplementation() {
+    if (RTC_DIRECT_DISABLED) {
+      logRtcAvailabilityOnce(
+        "disabled",
+        "PTY direct RTC runtime disabled by CONDUCTOR_DISABLE_PTY_DIRECT_RTC=1; relay fallback only",
+      );
+      return null;
+    }
+
+    if (createRtcPeerConnection) {
+      logRtcAvailabilityOnce("ready:deps", "PTY direct RTC runtime ready via injected peer connection");
+      return {
+        source: "deps.createRtcPeerConnection",
+        createPeerConnection: (...args) => createRtcPeerConnection(...args),
+      };
+    }
+
+    if (typeof globalThis.RTCPeerConnection === "function") {
+      logRtcAvailabilityOnce("ready:global", "PTY direct RTC runtime ready via globalThis.RTCPeerConnection");
+      return {
+        source: "globalThis.RTCPeerConnection",
+        createPeerConnection: (...args) => new globalThis.RTCPeerConnection(...args),
+      };
+    }
+
+    if (!rtcImplementationPromise) {
+      rtcImplementationPromise = (async () => {
+        for (const moduleName of RTC_MODULE_CANDIDATES) {
+          try {
+            const mod = await importOptionalModule(moduleName);
+            const PeerConnectionCtor =
+              mod?.RTCPeerConnection ||
+              mod?.default?.RTCPeerConnection ||
+              mod?.default;
+            if (typeof PeerConnectionCtor === "function") {
+              return {
+                source: moduleName,
+                createPeerConnection: (...args) => new PeerConnectionCtor(...args),
+              };
+            }
+          } catch {
+            // Try next implementation.
+          }
+        }
+        return null;
+      })();
+    }
+
+    const rtc = await rtcImplementationPromise;
+    if (rtc) {
+      logRtcAvailabilityOnce(`ready:${rtc.source}`, `PTY direct RTC runtime ready via ${rtc.source}`);
+      return rtc;
+    }
+
+    logRtcAvailabilityOnce(
+      "unavailable",
+      `PTY direct RTC runtime unavailable; install optional dependency ${DEFAULT_RTC_MODULE_CANDIDATES[0]} or keep relay fallback`,
+    );
+    return null;
+  }
+
+  function cleanupPtyRtcTransport(taskId, expectedSessionId = null) {
+    const current = activePtyRtcTransports.get(taskId);
+    if (!current) {
+      return;
+    }
+    if (expectedSessionId && current.sessionId !== expectedSessionId) {
+      return;
+    }
+    try {
+      current.channel?.close?.();
+    } catch {}
+    try {
+      current.peer?.close?.();
+    } catch {}
+    activePtyRtcTransports.delete(taskId);
+  }
+
+  async function startPtyRtcNegotiation(taskId, sessionId, connectionId, offerDescription) {
+    const record = activePtySessions.get(taskId);
+    if (!record) {
+      return { ok: false, reason: "terminal_session_not_found" };
+    }
+
+    const rtc = await resolveRtcImplementation();
+    if (!rtc) {
+      return { ok: false, reason: "direct_transport_not_supported" };
+    }
+
+    cleanupPtyRtcTransport(taskId);
+
+    try {
+      const peer = rtc.createPeerConnection();
+      const transport = {
+        taskId,
+        sessionId,
+        connectionId,
+        peer,
+        channel: null,
+      };
+      activePtyRtcTransports.set(taskId, transport);
+
+      peer.ondatachannel = (event) => {
+        transport.channel = event?.channel || null;
+        if (transport.channel) {
+          transport.channel.onmessage = (messageEvent) => {
+            try {
+              const raw =
+                typeof messageEvent?.data === "string"
+                  ? messageEvent.data
+                  : Buffer.isBuffer(messageEvent?.data)
+                    ? messageEvent.data.toString("utf8")
+                    : String(messageEvent?.data ?? "");
+              const parsed = JSON.parse(raw);
+              handleDirectTransportPayload(taskId, sessionId, connectionId, parsed);
+            } catch (error) {
+              logError(`Failed to handle PTY direct channel message for ${taskId}: ${error?.message || error}`);
+            }
+          };
+          transport.channel.onopen = () => {
+            sendPtyTransportStatus({
+              task_id: taskId,
+              session_id: sessionId,
+              connection_id: connectionId,
+              transport_state: "direct",
+              transport_policy: "direct_preferred",
+              writer_connection_id: connectionId,
+              direct_candidate: true,
+            }).catch((err) => {
+              logError(`Failed to report direct PTY transport status for ${taskId}: ${err?.message || err}`);
+            });
+          };
+          transport.channel.onclose = () => {
+            sendPtyTransportStatus({
+              task_id: taskId,
+              session_id: sessionId,
+              connection_id: connectionId,
+              transport_state: "fallback_relay",
+              transport_policy: "direct_preferred",
+              writer_connection_id: connectionId,
+              direct_candidate: false,
+              reason: "direct_channel_closed",
+            }).catch((err) => {
+              logError(`Failed to report PTY transport fallback for ${taskId}: ${err?.message || err}`);
+            });
+            cleanupPtyRtcTransport(taskId, sessionId);
+          };
+        }
+      };
+
+      peer.onicecandidate = (event) => {
+        if (!event?.candidate) {
+          return;
+        }
+        sendPtyTransportSignal({
+          task_id: taskId,
+          session_id: sessionId,
+          connection_id: connectionId,
+          signal_type: "ice_candidate",
+          candidate: typeof event.candidate.toJSON === "function" ? event.candidate.toJSON() : event.candidate,
+        }).catch((err) => {
+          logError(`Failed to report PTY ICE candidate for ${taskId}: ${err?.message || err}`);
+        });
+      };
+
+      await peer.setRemoteDescription({
+        type: "offer",
+        sdp: offerDescription.sdp,
+      });
+      const answer = await peer.createAnswer();
+      await peer.setLocalDescription(answer);
+
+      await sendPtyTransportSignal({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        signal_type: "answer",
+        description: {
+          type: answer.type,
+          sdp: answer.sdp,
+        },
+      });
+      await sendPtyTransportStatus({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        transport_state: "negotiating",
+        transport_policy: "direct_preferred",
+        writer_connection_id: connectionId,
+        direct_candidate: true,
+      });
+
+      return { ok: true };
+    } catch (error) {
+      cleanupPtyRtcTransport(taskId, sessionId);
+      return {
+        ok: false,
+        reason: error?.message || "rtc_negotiation_failed",
+      };
+    }
+  }
+
+  function resolvePtyLaunchSpec(launchConfig, fallbackCwd) {
+    const normalizedLaunchConfig = normalizeLaunchConfig(launchConfig);
+    const entrypointType =
+      normalizeOptionalString(normalizedLaunchConfig.entrypoint_type) ||
+      normalizeOptionalString(normalizedLaunchConfig.entrypointType) ||
+      (normalizeOptionalString(normalizedLaunchConfig.tool_preset) ||
+      normalizeOptionalString(normalizedLaunchConfig.toolPreset)
+        ? "tool_preset"
+        : "shell");
+    const preferredShell =
+      normalizeOptionalString(normalizedLaunchConfig.shell) ||
+      process.env.SHELL ||
+      "/bin/zsh";
+    const cwd =
+      normalizeOptionalString(normalizedLaunchConfig.cwd) ||
+      fallbackCwd;
+    const env = normalizeTerminalEnv(normalizedLaunchConfig.env);
+    const cols = normalizePositiveInt(
+      normalizedLaunchConfig.cols ?? normalizedLaunchConfig.columns,
+      DEFAULT_TERMINAL_COLS,
+    );
+    const rows = normalizePositiveInt(
+      normalizedLaunchConfig.rows,
+      DEFAULT_TERMINAL_ROWS,
+    );
+
+    if (entrypointType === "tool_preset") {
+      const toolPreset =
+        normalizeOptionalString(normalizedLaunchConfig.tool_preset) ||
+        normalizeOptionalString(normalizedLaunchConfig.toolPreset) ||
+        SUPPORTED_BACKENDS[0] ||
+        "codex";
+      const cliCommand = ALLOW_CLI_LIST[toolPreset];
+      if (!cliCommand) {
+        throw new Error(`Unsupported tool preset: ${toolPreset}`);
+      }
+      return {
+        entrypointType,
+        toolPreset,
+        command: preferredShell,
+        args: ["-lc", cliCommand],
+        shell: preferredShell,
+        cwd,
+        env,
+        cols,
+        rows,
+      };
+    }
+
+    if (entrypointType === "custom") {
+      const command = normalizeOptionalString(normalizedLaunchConfig.command);
+      if (!command) {
+        throw new Error("launch_config.command is required for custom entrypoint");
+      }
+      const args = Array.isArray(normalizedLaunchConfig.args)
+        ? normalizedLaunchConfig.args.filter((value) => typeof value === "string")
+        : [];
+      return {
+        entrypointType,
+        toolPreset: null,
+        command,
+        args,
+        shell: preferredShell,
+        cwd,
+        env,
+        cols,
+        rows,
+      };
+    }
+
+    return {
+      entrypointType: "shell",
+      toolPreset: null,
+      command: preferredShell,
+      args: ["-l"],
+      shell: preferredShell,
+      cwd,
+      env,
+      cols,
+      rows,
+    };
+  }
+
+  function getTerminalChunkByteLength(data) {
+    return Buffer.byteLength(data, "utf8");
+  }
+
+  function trimTerminalChunkToTailBytes(data, maxBytes) {
+    const encoded = Buffer.from(data, "utf8");
+    if (encoded.length <= maxBytes) {
+      return data;
+    }
+    const tail = encoded.subarray(encoded.length - maxBytes);
+    let start = 0;
+    while (start < tail.length && (tail[start] & 0b1100_0000) === 0b1000_0000) {
+      start += 1;
+    }
+    return tail.subarray(start).toString("utf8");
+  }
+
+  function bufferTerminalOutput(record, data) {
+    record.outputSeq += 1;
+    let bufferedData = typeof data === "string" ? data : String(data ?? "");
+    let byteLength = getTerminalChunkByteLength(bufferedData);
+    if (byteLength > TERMINAL_RING_BUFFER_MAX_BYTES) {
+      bufferedData = trimTerminalChunkToTailBytes(bufferedData, TERMINAL_RING_BUFFER_MAX_BYTES);
+      byteLength = getTerminalChunkByteLength(bufferedData);
+    }
+    record.ringBuffer.push({ seq: record.outputSeq, data: bufferedData, byteLength });
+    record.ringBufferByteLength += byteLength;
+    while (record.ringBufferByteLength > TERMINAL_RING_BUFFER_MAX_BYTES && record.ringBuffer.length > 0) {
+      const removed = record.ringBuffer.shift();
+      record.ringBufferByteLength -= removed?.byteLength ?? 0;
+    }
+    return record.outputSeq;
+  }
+
+  function sendDirectPtyPayload(taskId, payload) {
+    const transport = activePtyRtcTransports.get(taskId);
+    const channel = transport?.channel;
+    if (!channel || channel.readyState !== "open" || typeof channel.send !== "function") {
+      return false;
+    }
+    try {
+      channel.send(JSON.stringify(payload));
+      return true;
+    } catch (error) {
+      logError(`Failed to send PTY direct payload for ${taskId}: ${error?.message || error}`);
+      if (transport) {
+        sendPtyTransportStatus({
+          task_id: taskId,
+          session_id: transport.sessionId,
+          connection_id: transport.connectionId,
+          transport_state: "fallback_relay",
+          transport_policy: "direct_preferred",
+          writer_connection_id: transport.connectionId,
+          direct_candidate: false,
+          reason: "direct_channel_send_failed",
+        }).catch((err) => {
+          logError(`Failed to report PTY direct send fallback for ${taskId}: ${err?.message || err}`);
+        });
+      }
+      cleanupPtyRtcTransport(taskId);
+      return false;
+    }
+  }
+
+  function handleDirectTransportPayload(taskId, sessionId, connectionId, payload) {
+    const transport = activePtyRtcTransports.get(taskId);
+    if (
+      !transport ||
+      transport.sessionId !== sessionId ||
+      transport.connectionId !== connectionId
+    ) {
+      return;
+    }
+    if (payload?.type === "terminal_input" && payload.payload) {
+      handleTerminalInput(payload.payload);
+      return;
+    }
+    if (payload?.type === "terminal_resize" && payload.payload) {
+      handleTerminalResize(payload.payload);
+    }
+  }
+
+  function attachPtyStreamHandlers(taskId, record) {
+    const writeLogChunk = (chunk) => {
+      if (record.logStream) {
+        record.logStream.write(chunk);
+      }
+    };
+
+    record.pty.onData((data) => {
+      writeLogChunk(data);
+      const seq = bufferTerminalOutput(record, data);
+      const latencySample = record.pendingLatencySample
+        ? {
+            client_input_seq: record.pendingLatencySample.clientInputSeq ?? undefined,
+            client_sent_at: record.pendingLatencySample.clientSentAt ?? undefined,
+            server_received_at: record.pendingLatencySample.serverReceivedAt ?? undefined,
+            daemon_received_at: record.pendingLatencySample.daemonReceivedAt,
+            first_output_at: new Date().toISOString(),
+            daemon_input_to_first_output_ms: Math.max(0, Date.now() - record.pendingLatencySample.daemonReceivedAtMs),
+          }
+        : undefined;
+      record.pendingLatencySample = null;
+      const outputPayload = {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        seq,
+        data,
+        ...(latencySample ? { latency_sample: latencySample } : {}),
+      };
+      sendDirectPtyPayload(taskId, {
+        type: "terminal_output",
+        payload: outputPayload,
+      });
+      sendTerminalEvent("terminal_output", outputPayload).catch((err) => {
+        logError(`Failed to report terminal_output for ${taskId}: ${err?.message || err}`);
+      });
+    });
+
+    record.pty.onExit(({ exitCode, signal }) => {
+      if (record.stopForceKillTimer) {
+        clearTimeout(record.stopForceKillTimer);
+      }
+      cleanupPtyRtcTransport(taskId);
+      activePtySessions.delete(taskId);
+      if (record.logStream) {
+        const ts = new Date().toLocaleString("sv-SE", { timeZone: "Asia/Shanghai" }).replace(" ", "T");
+        record.logStream.write(
+          `[daemon ${ts}] pty exited exitCode=${exitCode ?? "null"} signal=${signal ?? "null"}\n`,
+        );
+        record.logStream.end();
+      }
+      const closedAt = new Date().toISOString();
+      log(`PTY task ${taskId} exited with code=${exitCode ?? "null"} signal=${signal ?? "null"}`);
+      sendTerminalEvent("terminal_exit", {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        exit_code: exitCode ?? null,
+        signal: signal ?? null,
+        seq: record.outputSeq,
+        closed_at: closedAt,
+      }).catch((err) => {
+        logError(`Failed to report terminal_exit for ${taskId}: ${err?.message || err}`);
+      });
+    });
+  }
+
+  function resizePty(record, cols, rows) {
+    const nextCols = normalizePositiveInt(cols, record.cols || DEFAULT_TERMINAL_COLS);
+    const nextRows = normalizePositiveInt(rows, record.rows || DEFAULT_TERMINAL_ROWS);
+    record.cols = nextCols;
+    record.rows = nextRows;
+    if (typeof record.pty.resize === "function") {
+      record.pty.resize(nextCols, nextRows);
+    }
+  }
+
+  async function handleCreatePtyTask(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const projectId = payload?.project_id ? String(payload.project_id) : "";
+    const ptySessionId = payload?.pty_session_id ? String(payload.pty_session_id) : "";
+    const requestId = payload?.request_id ? String(payload.request_id) : "";
+    const launchConfig = normalizeLaunchConfig(payload?.launch_config);
+
+    if (!taskId || !projectId || !ptySessionId) {
+      logError(`Invalid create_pty_task payload: ${JSON.stringify(payload)}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      return;
+    }
+
+    if (requestId && !markRequestSeen(requestId)) {
+      log(`Duplicate create_pty_task ignored for ${taskId} (request_id=${requestId})`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: true,
+      }).catch(() => {});
+      return;
+    }
+
+    if (activeTaskProcesses.has(taskId) || activePtySessions.has(taskId)) {
+      log(`Duplicate create_pty_task ignored for ${taskId}: task already active`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: true,
+      }).catch(() => {});
+      return;
+    }
+
+    let boundPath = await getProjectLocalPath(projectId);
+    let taskDir = normalizeOptionalString(launchConfig.cwd) || boundPath;
+    if (!taskDir) {
+      const now = new Date();
+      const dayDir = path.join(WORKSPACE_ROOT, formatWorkspaceDate(now));
+      const runTimestampPart = formatWorkspaceRunTimestamp(now);
+      const taskSuffix = taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 8) || String(process.pid);
+      // PTY login shells can exit immediately if their cwd is renamed right after spawn.
+      const pendingRunDir = `${runTimestampPart}_pty_${taskSuffix}`;
+      taskDir = path.join(dayDir, pendingRunDir);
+    }
+
+    try {
+      mkdirSyncFn(taskDir, { recursive: true });
+    } catch (err) {
+      logError(`Failed to create PTY workspace ${taskDir}: ${err?.message || err}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      return;
+    }
+
+    let launchSpec;
+    try {
+      launchSpec = resolvePtyLaunchSpec(launchConfig, taskDir);
+    } catch (error) {
+      logError(`Failed to resolve PTY launch config for ${taskId}: ${error?.message || error}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        message: error?.message || String(error),
+      }).catch(() => {});
+      return;
+    }
+
+    sendAgentCommandAck({
+      requestId,
+      taskId,
+      eventType: "create_pty_task",
+      accepted: true,
+    }).catch((err) => {
+      logError(`Failed to report agent_command_ack(create_pty_task) for ${taskId}: ${err?.message || err}`);
+    });
+
+    const env = {
+      ...process.env,
+      ...launchSpec.env,
+      CONDUCTOR_PROJECT_ID: projectId,
+      CONDUCTOR_TASK_ID: taskId,
+      CONDUCTOR_PTY_SESSION_ID: ptySessionId,
+    };
+    if (config.CONFIG_FILE) {
+      env.CONDUCTOR_CONFIG = config.CONFIG_FILE;
+    }
+    if (AGENT_TOKEN) {
+      env.CONDUCTOR_AGENT_TOKEN = AGENT_TOKEN;
+    }
+    if (BACKEND_HTTP) {
+      env.CONDUCTOR_BACKEND_URL = BACKEND_HTTP;
+    }
+
+    const logPath = path.join(launchSpec.cwd, "conductor-terminal.log");
+    let logStream;
+    try {
+      logStream = createWriteStreamFn(logPath, { flags: "a" });
+      if (logStream && typeof logStream.on === "function") {
+        const logPathSnapshot = logPath;
+        logStream.on("error", (err) => {
+          logError(`Terminal log stream error (${logPathSnapshot}): ${err?.message || err}`);
+        });
+      }
+    } catch (err) {
+      logError(`Failed to open PTY log file ${logPath}: ${err?.message || err}`);
+    }
+
+    try {
+      const pty = await createPtyFn(launchSpec.command, launchSpec.args, {
+        name: "xterm-256color",
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        cwd: launchSpec.cwd,
+        env,
+      });
+      const resolvedLogPath = path.join(taskDir, "conductor-terminal.log");
+
+      const startedAt = new Date().toISOString();
+      const record = {
+        kind: "pty",
+        pty,
+        ptySessionId,
+        projectId,
+        taskDir,
+        logPath: resolvedLogPath,
+        logStream,
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        shell: launchSpec.shell,
+        startedAt,
+        outputSeq: 0,
+        ringBuffer: [],
+        ringBufferByteLength: 0,
+        pendingLatencySample: null,
+        stopForceKillTimer: null,
+      };
+      activePtySessions.set(taskId, record);
+      attachPtyStreamHandlers(taskId, record);
+
+      log(`Created PTY task ${taskId} (${launchSpec.entrypointType}) cwd=${launchSpec.cwd}`);
+      sendTerminalEvent("terminal_opened", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        pid: Number.isInteger(pty?.pid) ? pty.pid : null,
+        cwd: taskDir,
+        shell: launchSpec.shell,
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        started_at: startedAt,
+      }).catch((err) => {
+        logError(`Failed to report terminal_opened for ${taskId}: ${err?.message || err}`);
+      });
+    } catch (error) {
+      if (logStream) {
+        logStream.end();
+      }
+      logError(`Failed to create PTY task ${taskId}: ${error?.message || error}`);
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        message: error?.message || String(error),
+      }).catch(() => {});
+    }
+  }
+
+  async function handleTerminalAttach(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    if (!taskId) return;
+    const record = activePtySessions.get(taskId);
+    if (!record) {
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        pty_session_id: payload?.pty_session_id ? String(payload.pty_session_id) : null,
+        message: "terminal session not found",
+      }).catch(() => {});
+      return;
+    }
+
+    if (payload?.cols || payload?.rows) {
+      resizePty(record, payload?.cols, payload?.rows);
+    }
+
+    await sendTerminalEvent("terminal_opened", {
+      task_id: taskId,
+      project_id: record.projectId,
+      pty_session_id: record.ptySessionId,
+      pid: Number.isInteger(record.pty?.pid) ? record.pty.pid : null,
+      cwd: record.taskDir,
+      shell: record.shell,
+      cols: record.cols,
+      rows: record.rows,
+      started_at: record.startedAt,
+    }).catch((err) => {
+      logError(`Failed to report terminal_opened on attach for ${taskId}: ${err?.message || err}`);
+    });
+
+    const lastSeq = normalizePositiveInt(payload?.last_seq ?? payload?.lastSeq, 0);
+    for (const chunk of record.ringBuffer) {
+      if (chunk.seq <= lastSeq) continue;
+      await sendTerminalEvent("terminal_output", {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        seq: chunk.seq,
+        data: chunk.data,
+      }).catch((err) => {
+        logError(`Failed to replay terminal_output for ${taskId}: ${err?.message || err}`);
+      });
+    }
+  }
+
+  function handleTerminalInput(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const data = typeof payload?.data === "string" ? payload.data : "";
+    if (!taskId || !data) return;
+    const record = activePtySessions.get(taskId);
+    if (!record || typeof record.pty.write !== "function") {
+      return;
+    }
+    record.pendingLatencySample = {
+      clientInputSeq: normalizeNonNegativeInt(payload?.client_input_seq ?? payload?.clientInputSeq, null),
+      clientSentAt: normalizeIsoTimestamp(payload?.client_sent_at ?? payload?.clientSentAt),
+      serverReceivedAt: normalizeIsoTimestamp(payload?.server_received_at ?? payload?.serverReceivedAt),
+      daemonReceivedAt: new Date().toISOString(),
+      daemonReceivedAtMs: Date.now(),
+    };
+    record.pty.write(data);
+  }
+
+  function handleTerminalResize(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    if (!taskId) return;
+    const record = activePtySessions.get(taskId);
+    if (!record) return;
+    resizePty(record, payload?.cols, payload?.rows);
+  }
+
+  function handleTerminalDetach(_payload) {
+    // PTY sessions stay alive without viewers. Detach is currently a no-op.
+  }
+
+  async function handlePtyTransportSignal(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const sessionId = payload?.session_id ? String(payload.session_id) : "";
+    const connectionId = payload?.connection_id ? String(payload.connection_id) : "";
+    const signalType = payload?.signal_type ? String(payload.signal_type) : "";
+    if (!taskId || !connectionId || !signalType) {
+      return;
+    }
+
+    const record = activePtySessions.get(taskId);
+    const description =
+      payload?.description && typeof payload.description === "object" && !Array.isArray(payload.description)
+        ? payload.description
+        : null;
+    const candidate =
+      payload?.candidate && typeof payload.candidate === "object" && !Array.isArray(payload.candidate)
+        ? payload.candidate
+        : null;
+
+    if (signalType === "ice_candidate") {
+      if (!sessionId) {
+        return;
+      }
+      const transport = activePtyRtcTransports.get(taskId);
+      if (
+        transport &&
+        transport.sessionId === sessionId &&
+        transport.connectionId === connectionId &&
+        typeof transport.peer?.addIceCandidate === "function" &&
+        candidate
+      ) {
+        try {
+          await transport.peer.addIceCandidate(candidate);
+        } catch (err) {
+          logError(`Failed to apply PTY ICE candidate for ${taskId}: ${err?.message || err}`);
+        }
+      }
+      return;
+    }
+
+    if (signalType === "revoke") {
+      const transport = activePtyRtcTransports.get(taskId);
+      if (transport && transport.connectionId === connectionId) {
+        cleanupPtyRtcTransport(taskId);
+      }
+      return;
+    }
+
+    if (signalType === "offer" && description?.type === "offer" && typeof description.sdp === "string") {
+      if (!sessionId) {
+        return;
+      }
+      const negotiation = await startPtyRtcNegotiation(taskId, sessionId, connectionId, description);
+      if (negotiation.ok) {
+        return;
+      }
+      const reason = negotiation.reason || (record ? "direct_transport_not_supported" : "terminal_session_not_found");
+      sendPtyTransportSignal({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        signal_type: "answer_placeholder",
+        description: {
+          type: "answer",
+          mode: "placeholder",
+          reason,
+        },
+      }).catch((err) => {
+        logError(`Failed to report pty_transport_signal for ${taskId}: ${err?.message || err}`);
+      });
+      sendPtyTransportStatus({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        transport_state: "fallback_relay",
+        transport_policy: "relay_only",
+        writer_connection_id: connectionId,
+        direct_candidate: false,
+        reason,
+      }).catch((err) => {
+        logError(`Failed to report pty_transport_status for ${taskId}: ${err?.message || err}`);
+      });
+      return;
+    }
+
+    const reason = record ? "direct_transport_not_supported" : "terminal_session_not_found";
+    if (signalType === "direct_request") {
+      if (!sessionId) {
+        return;
+      }
+      sendPtyTransportSignal({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        signal_type: "answer_placeholder",
+        description: {
+          type: "answer",
+          mode: "placeholder",
+          reason,
+        },
+      }).catch((err) => {
+        logError(`Failed to report pty_transport_signal for ${taskId}: ${err?.message || err}`);
+      });
+      sendPtyTransportStatus({
+        task_id: taskId,
+        session_id: sessionId,
+        connection_id: connectionId,
+        transport_state: "fallback_relay",
+        transport_policy: "relay_only",
+        writer_connection_id: connectionId,
+        direct_candidate: false,
+        reason,
+      }).catch((err) => {
+        logError(`Failed to report pty_transport_status for ${taskId}: ${err?.message || err}`);
+      });
+    }
+  }
+
   function handleEvent(event) {
     const receivedAt = Date.now();
     lastInboundAt = receivedAt;
@@ -805,10 +1804,34 @@ export function startDaemon(config = {}, deps = {}) {
       handleCreateTask(event.payload);
       return;
     }
+    if (event.type === "create_pty_task") {
+      void handleCreatePtyTask(event.payload);
+      return;
+    }
     if (event.type === "stop_task") {
       handleStopTask(event.payload);
       return;
     }
+    if (event.type === "terminal_attach") {
+      void handleTerminalAttach(event.payload);
+      return;
+    }
+    if (event.type === "terminal_input") {
+      handleTerminalInput(event.payload);
+      return;
+    }
+    if (event.type === "terminal_resize") {
+      handleTerminalResize(event.payload);
+      return;
+    }
+    if (event.type === "terminal_detach") {
+      handleTerminalDetach(event.payload);
+      return;
+    }
+    if (event.type === "pty_transport_signal") {
+      void handlePtyTransportSignal(event.payload);
+      return;
+    }
     if (event.type === "collect_logs") {
       void handleCollectLogs(event.payload);
     }
@@ -922,8 +1945,9 @@ export function startDaemon(config = {}, deps = {}) {
       });
     };
 
-    const record = activeTaskProcesses.get(taskId);
-    if (!record || !record.child) {
+    const processRecord = activeTaskProcesses.get(taskId);
+    const ptyRecord = activePtySessions.get(taskId);
+    if ((!processRecord || !processRecord.child) && !ptyRecord) {
       log(`Stop requested for task ${taskId}, but no active process found`);
       sendStopAck(false);
       return;
@@ -934,36 +1958,61 @@ export function startDaemon(config = {}, deps = {}) {
 
     sendStopAck(true);
 
-    if (record.stopForceKillTimer) {
-      clearTimeout(record.stopForceKillTimer);
-      record.stopForceKillTimer = null;
+    const activeRecord = processRecord || ptyRecord;
+    if (activeRecord?.stopForceKillTimer) {
+      clearTimeout(activeRecord.stopForceKillTimer);
+      activeRecord.stopForceKillTimer = null;
+    }
+    if (ptyRecord) {
+      cleanupPtyRtcTransport(taskId);
     }
 
-    try {
-      if (typeof record.child.kill === "function") {
-        record.child.kill("SIGTERM");
+    if (processRecord?.child) {
+      try {
+        if (typeof processRecord.child.kill === "function") {
+          processRecord.child.kill("SIGTERM");
+        }
+      } catch (error) {
+        logError(`Failed to stop task ${taskId}: ${error?.message || error}`);
+      }
+    } else if (ptyRecord?.pty) {
+      try {
+        if (typeof ptyRecord.pty.kill === "function") {
+          ptyRecord.pty.kill("SIGTERM");
+        }
+      } catch (error) {
+        logError(`Failed to stop PTY task ${taskId}: ${error?.message || error}`);
       }
-    } catch (error) {
-      logError(`Failed to stop task ${taskId}: ${error?.message || error}`);
     }
 
-    record.stopForceKillTimer = setTimeout(() => {
-      const latest = activeTaskProcesses.get(taskId);
-      if (!latest || latest.child !== record.child) {
+    activeRecord.stopForceKillTimer = setTimeout(() => {
+      const latestProcess = activeTaskProcesses.get(taskId);
+      const latestPty = activePtySessions.get(taskId);
+      if (latestProcess?.child && processRecord?.child && latestProcess.child === processRecord.child) {
+        try {
+          if (typeof latestProcess.child.kill === "function") {
+            log(`Task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
+            latestProcess.child.kill("SIGKILL");
+          }
+        } catch (error) {
+          logError(`Failed to SIGKILL task ${taskId}: ${error?.message || error}`);
+        }
         return;
       }
-      try {
-        if (typeof latest.child.kill === "function") {
-          log(`Task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
-          latest.child.kill("SIGKILL");
+      if (latestPty?.pty && ptyRecord?.pty && latestPty.pty === ptyRecord.pty) {
+        try {
+          if (typeof latestPty.pty.kill === "function") {
+            log(`PTY task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
+            latestPty.pty.kill("SIGKILL");
+          }
+        } catch (error) {
+          logError(`Failed to SIGKILL PTY task ${taskId}: ${error?.message || error}`);
         }
-      } catch (error) {
-        logError(`Failed to SIGKILL task ${taskId}: ${error?.message || error}`);
       }
     }, STOP_FORCE_KILL_TIMEOUT_MS);
 
-    if (typeof record.stopForceKillTimer?.unref === "function") {
-      record.stopForceKillTimer.unref();
+    if (typeof activeRecord.stopForceKillTimer?.unref === "function") {
+      activeRecord.stopForceKillTimer.unref();
     }
   }
 
@@ -1067,7 +2116,7 @@ export function startDaemon(config = {}, deps = {}) {
     }
 
     // Validate and get CLI command for the backend
-    const effectiveBackend = backendType || SUPPORTED_BACKENDS[0];
+    const effectiveBackend = normalizeRuntimeBackendName(backendType || SUPPORTED_BACKENDS[0]);
     if (!SUPPORTED_BACKENDS.includes(effectiveBackend)) {
       logError(`Unsupported backend: ${effectiveBackend}. Supported: ${SUPPORTED_BACKENDS.join(", ")}`);
       sendAgentCommandAck({
@@ -1315,7 +2364,9 @@ export function startDaemon(config = {}, deps = {}) {
         clearInterval(watchdogTimer);
         watchdogTimer = null;
       }
-      const activeEntries = [...activeTaskProcesses.entries()];
+      const activeProcessEntries = [...activeTaskProcesses.entries()];
+      const activePtyEntries = [...activePtySessions.entries()];
+      const activeEntries = [...activeProcessEntries, ...activePtyEntries];
       if (activeEntries.length > 0) {
         log(`Shutdown requested (${reason}); stopping ${activeEntries.length} active task(s)`);
       }
@@ -1343,7 +2394,7 @@ export function startDaemon(config = {}, deps = {}) {
         }),
       );
 
-      for (const [taskId, record] of activeEntries) {
+      for (const [taskId, record] of activeProcessEntries) {
         if (record?.stopForceKillTimer) {
           clearTimeout(record.stopForceKillTimer);
         }
@@ -1356,7 +2407,22 @@ export function startDaemon(config = {}, deps = {}) {
         }
       }
 
+      for (const [taskId, record] of activePtyEntries) {
+        if (record?.stopForceKillTimer) {
+          clearTimeout(record.stopForceKillTimer);
+        }
+        cleanupPtyRtcTransport(taskId);
+        try {
+          if (typeof record.pty?.kill === "function") {
+            record.pty.kill("SIGTERM");
+          }
+        } catch (error) {
+          logError(`Failed to stop PTY task ${taskId} on daemon close: ${error?.message || error}`);
+        }
+      }
+
       activeTaskProcesses.clear();
+      activePtySessions.clear();
 
       try {
         await withTimeout(
@@ -1429,6 +2495,25 @@ function parsePositiveInt(value, fallback) {
   return fallback;
 }
 
+function parseBooleanEnv(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function resolveRtcModuleCandidates(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return [...DEFAULT_RTC_MODULE_CANDIDATES];
+  }
+  const candidates = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  return candidates.length > 0 ? [...new Set(candidates)] : [...DEFAULT_RTC_MODULE_CANDIDATES];
+}
+
 function formatDisconnectDiagnostics(event) {
   const parts = [];
   const reason = typeof event?.reason === "string" && event.reason.trim()