@love-moon/conductor-cli 0.2.19 → 0.2.20

package/bin/conductor-channel.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+import { loadConfig } from "@love-moon/conductor-sdk";
+
+const isMainModule = (() => {
+  const currentFile = fileURLToPath(import.meta.url);
+  const entryFile = process.argv[1] ? path.resolve(process.argv[1]) : "";
+  return entryFile === currentFile;
+})();
+
+function resolveDefaultConfigPath(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  return path.join(home, ".conductor", "config.yaml");
+}
+
+function readTextFile(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function ensureFeishuChannelConfig(config) {
+  const feishu = config?.channels?.feishu;
+  if (!feishu?.appId || !feishu?.appSecret || !feishu?.verificationToken) {
+    throw new Error("config.yaml is missing channels.feishu.app_id/app_secret/verification_token");
+  }
+  return feishu;
+}
+
+function formatErrorBody(text) {
+  const normalized = typeof text === "string" ? text.trim() : "";
+  if (!normalized) return "";
+  try {
+    const parsed = JSON.parse(normalized);
+    if (parsed && typeof parsed === "object" && typeof parsed.error === "string") {
+      return parsed.error;
+    }
+  } catch {
+    // ignore
+  }
+  return normalized;
+}
+
+export async function connectFeishuChannel(options = {}) {
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? global.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch is not available");
+  }
+
+  const resolvedConfigPath = path.resolve(options.configFile || resolveDefaultConfigPath(env));
+  const rawYaml = readTextFile(resolvedConfigPath);
+  const config = loadConfig(resolvedConfigPath, { env });
+  const feishu = ensureFeishuChannelConfig(config);
+
+  const url = new URL("/api/channel/feishu/config", config.backendUrl);
+  const response = await fetchImpl(String(url), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.agentToken}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({ yaml: rawYaml }),
+  });
+
+  const rawText = await response.text();
+  if (!response.ok) {
+    const detail = formatErrorBody(rawText);
+    throw new Error(`Failed to connect Feishu channel (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+
+  const parsed = rawText ? JSON.parse(rawText) : {};
+  return {
+    configPath: resolvedConfigPath,
+    feishu,
+    config: parsed.config ?? null,
+  };
+}
+
+export async function main(argvInput = hideBin(process.argv), dependencies = {}) {
+  const log = dependencies.log ?? console.log;
+  const logError = dependencies.logError ?? console.error;
+
+  await yargs(argvInput)
+    .scriptName("conductor channel")
+    .command(
+      "connect feishu",
+      "Upload channels.feishu from config.yaml to Conductor backend",
+      (command) => command.option("config-file", {
+        type: "string",
+        describe: "Path to Conductor config file",
+      }),
+      async (argv) => {
+        try {
+          const result = await connectFeishuChannel({
+            configFile: argv.configFile,
+          });
+          const effective = result.config ?? {
+            provider: "FEISHU",
+            appId: result.feishu.appId,
+            verificationToken: result.feishu.verificationToken,
+          };
+          log(`Connected Feishu channel from ${result.configPath}`);
+          log(`app_id: ${effective.appId}`);
+          log(`verification_token: ${effective.verificationToken}`);
+          log("Configure the same verification_token in Feishu Open Platform webhook settings.");
+        } catch (error) {
+          logError(error instanceof Error ? error.message : String(error));
+          process.exitCode = 1;
+        }
+      },
+    )
+    .demandCommand(1)
+    .help()
+    .parseAsync();
+}
+
+if (isMainModule) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/bin/conductor-config.js

@@ -23,7 +23,7 @@ const DEFAULT_CLIs = {
   },
   codex: {
     command: "codex",
-    execArgs: "exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check",
+    execArgs: "--dangerously-bypass-approvals-and-sandbox --ask-for-approval never",
     description: "OpenAI Codex CLI"
   },
   // gemini: {

package/bin/conductor-diagnose.js

@@ -244,6 +244,7 @@ function printReport(taskId, report) {
   const diagnosis = payload?.diagnosis || {};
   const task = payload?.task || {};
   const realtime = payload?.realtime || {};
+  const ptyTransport = payload?.pty_transport || payload?.ptyTransport || {};
   const messages = payload?.messages || {};
 
   process.stdout.write(`Task: ${task?.id || taskId}\n`);
@@ -273,6 +274,25 @@ function printReport(taskId, report) {
       );
     }
   }
+  const latestLatency = ptyTransport?.latest_latency_sample || ptyTransport?.latestLatencySample;
+  if (latestLatency) {
+    process.stdout.write(
+      `- pty.latest_latency: client->server=${formatLatencyMs(
+        latestLatency.client_input_to_server_received_ms ?? latestLatency.clientInputToServerReceivedMs,
+      )}, server->daemon=${formatLatencyMs(
+        latestLatency.server_received_to_daemon_received_ms ?? latestLatency.serverReceivedToDaemonReceivedMs,
+      )}, daemon->first_output=${formatLatencyMs(
+        latestLatency.daemon_input_to_first_output_ms ?? latestLatency.daemonInputToFirstOutputMs,
+      )}, client->first_output=${formatLatencyMs(
+        latestLatency.client_input_to_first_output_ms ?? latestLatency.clientInputToFirstOutputMs,
+      )}\n`,
+    );
+    process.stdout.write(
+      `- pty.primary_bottleneck: ${String(
+        ptyTransport?.primary_bottleneck || ptyTransport?.primaryBottleneck || "unknown",
+      )}\n`,
+    );
+  }
 
   const reasons = Array.isArray(diagnosis.reasons) ? diagnosis.reasons : [];
   if (reasons.length > 0) {
@@ -364,6 +384,11 @@ function detectExecutionFailureLoopKey(value) {
   return null;
 }
 
+function formatLatencyMs(value) {
+  const num = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(num) && num >= 0 ? `${Math.round(num)}ms` : "n/a";
+}
+
 function normalizePositiveInt(value, fallback) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;

package/bin/conductor-fire.js

@@ -98,6 +98,30 @@ const DEFAULT_ERROR_LOOP_BACKOFF_MS = 3 * 60 * 1000;
 const DEFAULT_ERROR_LOOP_THRESHOLD = 3;
 const SESSION_BOOTSTRAP_LOCK_TIMEOUT_MS = 15_000;
 const SESSION_BOOTSTRAP_LOCK_RETRY_MS = 50;
+const FIRE_WATCHDOG_INTERVAL_MS = getBoundedEnvInt(
+  "CONDUCTOR_FIRE_WATCHDOG_INTERVAL_MS",
+  10_000,
+  1_000,
+  60_000,
+);
+const FIRE_WATCHDOG_STALE_WS_MS = getBoundedEnvInt(
+  "CONDUCTOR_FIRE_WATCHDOG_STALE_WS_MS",
+  45_000,
+  5_000,
+  5 * 60_000,
+);
+const FIRE_WATCHDOG_CONNECT_GRACE_MS = getBoundedEnvInt(
+  "CONDUCTOR_FIRE_WATCHDOG_CONNECT_GRACE_MS",
+  15_000,
+  1_000,
+  60_000,
+);
+const FIRE_WATCHDOG_RECONNECT_COOLDOWN_MS = getBoundedEnvInt(
+  "CONDUCTOR_FIRE_WATCHDOG_RECONNECT_COOLDOWN_MS",
+  15_000,
+  1_000,
+  2 * 60_000,
+);
 
 function sleepSync(ms) {
   if (!Number.isFinite(ms) || ms <= 0) {
@@ -191,6 +215,176 @@ function appendFireLocalLog(line) {
   }
 }
 
+function formatFireDisconnectDiagnostics(event = {}) {
+  const parts = [];
+  if (event.reason) {
+    parts.push(`reason=${event.reason}`);
+  }
+  if (typeof event.closeCode === "number") {
+    parts.push(`close_code=${event.closeCode}`);
+  }
+  if (event.closeReason) {
+    parts.push(`close_reason=${sanitizeForLog(event.closeReason, 120)}`);
+  }
+  if (event.socketError) {
+    parts.push(`socket_error=${sanitizeForLog(event.socketError, 120)}`);
+  }
+  if (typeof event.missedPongs === "number" && event.missedPongs > 0) {
+    parts.push(`missed_pongs=${event.missedPongs}`);
+  }
+  return parts.join(" ") || "reason=connection_lost";
+}
+
+function formatIsoTimestamp(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return "n/a";
+  }
+  return new Date(value).toISOString();
+}
+
+function formatFireWatchdogState({ connectedAt, lastPongAt, lastInboundAt }) {
+  return [
+    `connected_at=${formatIsoTimestamp(connectedAt)}`,
+    `last_pong_at=${formatIsoTimestamp(lastPongAt)}`,
+    `last_inbound_at=${formatIsoTimestamp(lastInboundAt)}`,
+  ].join(" ");
+}
+
+export class FireWatchdog {
+  constructor({
+    intervalMs = FIRE_WATCHDOG_INTERVAL_MS,
+    staleWsMs = FIRE_WATCHDOG_STALE_WS_MS,
+    connectGraceMs = FIRE_WATCHDOG_CONNECT_GRACE_MS,
+    reconnectCooldownMs = FIRE_WATCHDOG_RECONNECT_COOLDOWN_MS,
+    onForceReconnect,
+    logger = () => {},
+    now = () => Date.now(),
+  } = {}) {
+    this.intervalMs = intervalMs;
+    this.staleWsMs = staleWsMs;
+    this.connectGraceMs = connectGraceMs;
+    this.reconnectCooldownMs = reconnectCooldownMs;
+    this.onForceReconnect = onForceReconnect;
+    this.logger = logger;
+    this.now = now;
+    this.wsConnected = false;
+    this.lastConnectedAt = null;
+    this.lastPongAt = null;
+    this.lastInboundAt = null;
+    this.lastHealAt = 0;
+    this.healAttempts = 0;
+    this.awaitingHealthySignalAt = null;
+    this.timer = null;
+  }
+
+  start() {
+    if (this.timer) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      void this.runOnce();
+    }, this.intervalMs);
+    if (typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+  }
+
+  stop() {
+    if (!this.timer) {
+      return;
+    }
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  onConnected({ isReconnect = false, connectedAt = this.now() } = {}) {
+    this.wsConnected = true;
+    this.lastConnectedAt = connectedAt;
+    this.lastPongAt =
+      Number.isFinite(this.lastPongAt) && this.lastPongAt > connectedAt ? this.lastPongAt : connectedAt;
+    if (isReconnect && this.healAttempts > 0) {
+      this.awaitingHealthySignalAt = connectedAt;
+    } else if (!isReconnect) {
+      this.awaitingHealthySignalAt = null;
+    }
+  }
+
+  onDisconnected() {
+    this.wsConnected = false;
+  }
+
+  onPong({ at = this.now() } = {}) {
+    this.lastPongAt = at;
+    this.markHealthy("pong", at);
+  }
+
+  onInbound(at = this.now()) {
+    this.lastInboundAt = at;
+    this.markHealthy("inbound", at);
+  }
+
+  markHealthy(signal, at = this.now()) {
+    if (!this.awaitingHealthySignalAt || this.healAttempts === 0) {
+      return;
+    }
+    if (at < this.awaitingHealthySignalAt) {
+      return;
+    }
+    this.logger(
+      `[watchdog] Backend websocket healthy again after self-heal via ${signal} (${formatFireWatchdogState({
+        connectedAt: this.lastConnectedAt,
+        lastPongAt: this.lastPongAt,
+        lastInboundAt: this.lastInboundAt,
+      })})`,
+    );
+    this.awaitingHealthySignalAt = null;
+    this.healAttempts = 0;
+  }
+
+  async runOnce() {
+    if (!this.wsConnected || typeof this.onForceReconnect !== "function") {
+      return false;
+    }
+    const now = this.now();
+    if (!Number.isFinite(this.lastConnectedAt) || now - this.lastConnectedAt < this.connectGraceMs) {
+      return false;
+    }
+    const lastWsHealthAt = Math.max(this.lastPongAt || 0, this.lastInboundAt || 0, this.lastConnectedAt || 0);
+    if (lastWsHealthAt && now - lastWsHealthAt <= this.staleWsMs) {
+      return false;
+    }
+    if (this.lastHealAt && now - this.lastHealAt < this.reconnectCooldownMs) {
+      return false;
+    }
+
+    this.lastHealAt = now;
+    this.healAttempts += 1;
+    this.awaitingHealthySignalAt = null;
+    this.wsConnected = false;
+    this.logger(
+      `[watchdog] stale_ws_health; restarting fire websocket (${this.healAttempts}) (${formatFireWatchdogState({
+        connectedAt: this.lastConnectedAt,
+        lastPongAt: this.lastPongAt,
+        lastInboundAt: this.lastInboundAt,
+      })})`,
+    );
+    await this.onForceReconnect("watchdog:stale_ws_health");
+    return true;
+  }
+
+  getDebugState() {
+    return {
+      wsConnected: this.wsConnected,
+      lastConnectedAt: this.lastConnectedAt,
+      lastPongAt: this.lastPongAt,
+      lastInboundAt: this.lastInboundAt,
+      lastHealAt: this.lastHealAt,
+      healAttempts: this.healAttempts,
+      awaitingHealthySignalAt: this.awaitingHealthySignalAt,
+    };
+  }
+}
+
 async function main() {
   const cliArgs = parseCliArgs();
   let runtimeProjectPath = process.cwd();
@@ -239,6 +433,17 @@ async function main() {
   let pendingRemoteStopEvent = null;
   let conductor = null;
   let reconnectResumeInFlight = false;
+  let fireShuttingDown = false;
+  const fireWatchdog = new FireWatchdog({
+    onForceReconnect: async (reason) => {
+      if (!conductor || typeof conductor.forceReconnect !== "function") {
+        return;
+      }
+      await conductor.forceReconnect(reason);
+    },
+    logger: log,
+  });
+  fireWatchdog.start();
 
   const scheduleReconnectRecovery = ({ isReconnect }) => {
     if (!isReconnect) {
@@ -274,6 +479,7 @@ async function main() {
   };
 
   const handleStopTaskCommand = async (event) => {
+    fireWatchdog.onInbound();
     if (!event || typeof event !== "object") {
       return;
     }
@@ -322,7 +528,19 @@ async function main() {
       projectPath: runtimeProjectPath,
       extraEnv: env,
       configFile: cliArgs.configFile,
-      onConnected: scheduleReconnectRecovery,
+      onConnected: (event) => {
+        fireWatchdog.onConnected(event);
+        scheduleReconnectRecovery(event);
+      },
+      onDisconnected: (event) => {
+        fireWatchdog.onDisconnected();
+        if (!fireShuttingDown) {
+          log(`[fire-ws] Disconnected from backend: ${formatFireDisconnectDiagnostics(event)}`);
+        }
+      },
+      onPong: (event) => {
+        fireWatchdog.onPong(event);
+      },
       onStopTask: handleStopTaskCommand,
     });
 
@@ -425,11 +643,13 @@ async function main() {
     };
     const onSigint = () => {
       shutdownSignal = shutdownSignal || "SIGINT";
+      fireShuttingDown = true;
       signals.abort();
       requestBackendShutdown("SIGINT");
     };
     const onSigterm = () => {
       shutdownSignal = shutdownSignal || "SIGTERM";
+      fireShuttingDown = true;
       signals.abort();
       requestBackendShutdown("SIGTERM");
     };
@@ -494,6 +714,8 @@ async function main() {
       }
     }
   } finally {
+    fireShuttingDown = true;
+    fireWatchdog.stop();
     if (backendSession && typeof backendSession.close === "function") {
       try {
         await backendSession.close();

package/bin/conductor.js

@@ -10,6 +10,7 @@
  *   update   - Update the CLI to the latest version
  *   diagnose - Diagnose a task in production/backend
  *   send-file - Upload a local file into a task session
+ *   channel  - Connect user-owned chat channel providers
  */
 
 import { fileURLToPath } from "node:url";
@@ -46,7 +47,7 @@ if (argv[0] === "--version" || argv[0] === "-v") {
 const subcommand = argv[0];
 
 // Valid subcommands
-const validSubcommands = ["fire", "daemon", "config", "update", "diagnose", "send-file"];
+const validSubcommands = ["fire", "daemon", "config", "update", "diagnose", "send-file", "channel"];
 
 if (!validSubcommands.includes(subcommand)) {
   console.error(`Error: Unknown subcommand '${subcommand}'`);
@@ -90,6 +91,7 @@ Subcommands:
   update    Update the CLI to the latest version
   diagnose  Diagnose a task and print likely root cause
   send-file Upload a local file into a task session
+  channel   Connect user-owned chat channel providers
 
 Options:
   -h, --help     Show this help message
@@ -101,6 +103,7 @@ Examples:
   conductor daemon --config-file ~/.conductor/config.yaml
   conductor diagnose <task-id>
   conductor send-file ./screenshot.png
+  conductor channel connect feishu
   conductor config
   conductor update
 
@@ -111,6 +114,7 @@ For subcommand-specific help:
   conductor update --help
   conductor diagnose --help
   conductor send-file --help
+  conductor channel --help
 
 Version: ${pkgJson.version}
 `);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.2.19",
-  "gitCommitId": "346e048",
+  "version": "0.2.20",
+  "gitCommitId": "d622756",
   "type": "module",
   "bin": {
     "conductor": "bin/conductor.js"
@@ -17,8 +17,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-sdk": "0.2.19",
-    "@love-moon/conductor-sdk": "0.2.19",
+    "@love-moon/ai-sdk": "0.2.20",
+    "@love-moon/conductor-sdk": "0.2.20",
     "dotenv": "^16.4.5",
     "enquirer": "^2.4.1",
     "js-yaml": "^4.1.1",
@@ -28,7 +28,14 @@
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0"
   },
+  "optionalDependencies": {
+    "@roamhq/wrtc": "^0.10.0"
+  },
   "pnpm": {
+    "onlyBuiltDependencies": [
+      "node-pty",
+      "@roamhq/wrtc"
+    ],
     "overrides": {
       "@love-moon/ai-sdk": "file:../modules/ai-sdk",
       "@love-moon/conductor-sdk": "file:../modules/conductor-sdk"

package/src/daemon.js

@@ -28,6 +28,7 @@ const PLAN_LIMIT_MESSAGES = {
 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) {
@@ -207,6 +208,25 @@ function normalizePositiveInt(value, fallback) {
   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 {};
@@ -319,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,
@@ -503,6 +527,7 @@ export function startDaemon(config = {}, deps = {}) {
   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;
@@ -519,6 +544,8 @@ 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, {
@@ -908,6 +935,230 @@ export function startDaemon(config = {}, deps = {}) {
     });
   }
 
+  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 =
@@ -1025,6 +1276,54 @@ export function startDaemon(config = {}, deps = {}) {
     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) {
@@ -1035,13 +1334,30 @@ export function startDaemon(config = {}, deps = {}) {
     record.pty.onData((data) => {
       writeLogChunk(data);
       const seq = bufferTerminalOutput(record, data);
-      sendTerminalEvent("terminal_output", {
+      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,
-      }).catch((err) => {
+        ...(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}`);
       });
     });
@@ -1050,6 +1366,7 @@ export function startDaemon(config = {}, deps = {}) {
       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");
@@ -1235,6 +1552,7 @@ export function startDaemon(config = {}, deps = {}) {
         outputSeq: 0,
         ringBuffer: [],
         ringBufferByteLength: 0,
+        pendingLatencySample: null,
         stopForceKillTimer: null,
       };
       activePtySessions.set(taskId, record);
@@ -1322,6 +1640,13 @@ export function startDaemon(config = {}, deps = {}) {
     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);
   }
 
@@ -1337,6 +1662,124 @@ export function startDaemon(config = {}, deps = {}) {
     // 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;
@@ -1385,6 +1828,10 @@ export function startDaemon(config = {}, deps = {}) {
       handleTerminalDetach(event.payload);
       return;
     }
+    if (event.type === "pty_transport_signal") {
+      void handlePtyTransportSignal(event.payload);
+      return;
+    }
     if (event.type === "collect_logs") {
       void handleCollectLogs(event.payload);
     }
@@ -1516,6 +1963,9 @@ export function startDaemon(config = {}, deps = {}) {
       clearTimeout(activeRecord.stopForceKillTimer);
       activeRecord.stopForceKillTimer = null;
     }
+    if (ptyRecord) {
+      cleanupPtyRtcTransport(taskId);
+    }
 
     if (processRecord?.child) {
       try {
@@ -1961,6 +2411,7 @@ export function startDaemon(config = {}, deps = {}) {
         if (record?.stopForceKillTimer) {
           clearTimeout(record.stopForceKillTimer);
         }
+        cleanupPtyRtcTransport(taskId);
         try {
           if (typeof record.pty?.kill === "function") {
             record.pty.kill("SIGTERM");
@@ -2044,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()