quadwork 1.5.1 → 1.5.2

package/server/routes.js

@@ -148,11 +148,41 @@ router.get("/api/chat", async (req, res) => {
 const { WebSocket: NodeWebSocket } = require("ws");
 const { syncChattrToken } = require("./config");
 
+// #236: wait for AgentChattr to echo our message back over the same ws
+// connection before resolving, instead of fire-and-forgetting. AC's
+// /ws handler does this on every connect:
+//   1. Replays history as N `{type:"message", data: msg}` frames.
+//   2. Sends one `{type:"status", data: …}` frame (broadcast_status).
+//   3. Enters the receive loop and accepts our outgoing frame.
+// After our `type:"message"` is processed, AC calls `store.add()`
+// which broadcasts the stored record back to all clients (including
+// us) as another `{type:"message", data: msg}`.
+//
+// To get a race-free ack we therefore:
+//   A. Wait for the first `type:"status"` frame to confirm the
+//      history replay is done — any `type:"message"` frame seen
+//      BEFORE that is historical and must be ignored.
+//   B. Only then send our message and record the highest message
+//      id observed so far as a correlation baseline.
+//   C. Accept the first post-send `type:"message"` whose payload
+//      matches (sender, text, channel, reply_to) AND whose id is
+//      strictly greater than the baseline (AC ids are monotonically
+//      increasing from store.add). This eliminates the risk a
+//      reviewer flagged on #382 round 1: a historical identical
+//      message from <1.5s ago could have satisfied the old
+//      heuristic matcher.
+// On timeout / early close / 4003, we surface a proper error so the
+// /api/chat handler can return a 5xx (or 401) instead of a silent
+// {ok:true}.
 function sendViaWebSocket(baseUrl, sessionToken, message) {
   return new Promise((resolve, reject) => {
     const wsUrl = `${baseUrl.replace(/^http/, "ws")}/ws?token=${encodeURIComponent(sessionToken || "")}`;
     const ws = new NodeWebSocket(wsUrl);
     let settled = false;
+    let historyFlushed = false;
+    let sent = false;
+    let maxIdAtSend = -Infinity;
+    let maxHistoryId = -Infinity;
     const finish = (err, value) => {
       if (settled) return;
       settled = true;
@@ -160,14 +190,56 @@ function sendViaWebSocket(baseUrl, sessionToken, message) {
       if (err) reject(err); else resolve(value);
     };
     const giveUp = setTimeout(() => finish(new Error("websocket send timeout")), 4000);
-    ws.on("open", () => {
+    const doSend = () => {
+      if (sent || settled) return;
       try {
+        maxIdAtSend = maxHistoryId;
         ws.send(JSON.stringify({ type: "message", ...message }));
-        // Server acks via broadcast, but the dashboard's POST /api/chat
-        // contract only needs to know the message was accepted. Wait
-        // ~250ms for the server to enqueue + close cleanly.
-        setTimeout(() => { clearTimeout(giveUp); finish(null, { ok: true }); }, 250);
+        sent = true;
       } catch (err) { clearTimeout(giveUp); finish(err); }
+    };
+    ws.on("open", () => {
+      // Do NOT send yet. Wait for the status frame that marks the
+      // end of history replay so we have a clean correlation
+      // baseline. A safety timer covers the (unlikely) case of an
+      // AC build that doesn't emit status on connect — after 750ms
+      // we fall back to sending anyway, using whatever max id we
+      // collected from history so far as the baseline.
+      setTimeout(() => {
+        if (!historyFlushed) {
+          historyFlushed = true;
+          doSend();
+        }
+      }, 750);
+    });
+    ws.on("message", (raw) => {
+      if (settled) return;
+      let frame;
+      try { frame = JSON.parse(raw.toString()); } catch { return; }
+      if (!frame || !frame.type) return;
+      if (frame.type === "status" && !historyFlushed) {
+        historyFlushed = true;
+        doSend();
+        return;
+      }
+      if (frame.type !== "message" || !frame.data) return;
+      const d = frame.data;
+      // Track the highest message id we have observed, whether from
+      // history replay or from other live broadcasts. Used as the
+      // baseline for the post-send correlation check.
+      if (typeof d.id === "number" && d.id > maxHistoryId) {
+        maxHistoryId = d.id;
+      }
+      if (!sent) return; // anything before our send is history
+      if (typeof d.id !== "number" || d.id <= maxIdAtSend) return;
+      if (d.sender !== message.sender) return;
+      if (d.text !== message.text) return;
+      if ((d.channel || "general") !== (message.channel || "general")) return;
+      const wantReply = message.reply_to ?? null;
+      const gotReply = d.reply_to ?? null;
+      if (wantReply !== gotReply) return;
+      clearTimeout(giveUp);
+      finish(null, { ok: true, message: d });
     });
     ws.on("error", (err) => { clearTimeout(giveUp); finish(err); });
     ws.on("close", (code, reason) => {
@@ -179,6 +251,15 @@ function sendViaWebSocket(baseUrl, sessionToken, message) {
         const e = new Error(msg);
         e.code = "EAGENTCHATTR_401";
         finish(e);
+        return;
+      }
+      // Any other premature close after we sent but before we saw
+      // the echo is an error — the old code path would have claimed
+      // success, silently swallowing a server-side reject.
+      if (!settled) {
+        clearTimeout(giveUp);
+        const r = (reason && reason.toString()) || "";
+        finish(new Error(`websocket closed before ack (code=${code}${r ? ", reason=" + r : ""})`));
       }
     });
   });
@@ -861,8 +942,12 @@ router.post("/api/chat", async (req, res) => {
   const attemptSend = () => sendViaWebSocket(base, sessionToken, message);
 
   try {
-    await attemptSend();
-    return res.json({ ok: true });
+    // #236: sendViaWebSocket now waits for AC's broadcast echo and
+    // returns `{ok, message}` where `message` is the stored record
+    // (with server-assigned id/timestamp). Pass it through so
+    // callers regain parity with the old /api/send response body.
+    const result = await attemptSend();
+    return res.json({ ok: true, message: result.message });
   } catch (err) {
     // If the cached session_token is stale (AgentChattr regenerates
     // one on every restart) the ws closes with code 4003 — re-sync
@@ -876,8 +961,8 @@ router.post("/api/chat", async (req, res) => {
       const { token: refreshed } = getChattrConfig(projectId);
       if (refreshed && refreshed !== sessionToken) {
         try {
-          await sendViaWebSocket(base, refreshed, message);
-          return res.json({ ok: true, resynced: true });
+          const retry = await sendViaWebSocket(base, refreshed, message);
+          return res.json({ ok: true, resynced: true, message: retry.message });
         } catch (retryErr) {
           console.warn(`[chat] retry after token resync failed: ${retryErr.message}`);
           return res.status(401).json({ error: "AgentChattr auth failed (token resync did not help)", detail: retryErr.message });
@@ -2339,7 +2424,12 @@ function readLastLines(filePath, n) {
 // otherwise. Keep the import list small and close to what the
 // bridge actually needs; add modules here if the bridge gains new
 // hard deps.
-function checkTelegramBridgePythonDeps() {
+// #380: `pythonPath` defaults to bare `python3` for backward-compat,
+// but the production call sites (install, start) MUST pass the
+// dedicated bridge venv's interpreter (`<BRIDGE_DIR>/.venv/bin/python3`)
+// so the import check runs against the same interpreter the spawn will
+// use. See #379 research ticket for root cause.
+function checkTelegramBridgePythonDeps(pythonPath = "python3") {
   try {
     // Only check the third-party module the bridge actually needs
     // at import time — `requests`. Toml parsing differs between
@@ -2347,7 +2437,7 @@ function checkTelegramBridgePythonDeps() {
     // genuine toml import failure will now be captured in the
     // bridge log file on spawn, so this pre-flight stays narrow
     // and avoids false negatives on older Python installs.
-    execFileSync("python3", ["-c", "import requests"], {
+    execFileSync(pythonPath, ["-c", "import requests"], {
       encoding: "utf-8",
       timeout: 10000,
       stdio: ["ignore", "pipe", "pipe"],
@@ -2503,34 +2593,47 @@ router.post("/api/telegram", async (req, res) => {
       }
     }
     case "install": {
-      // #353: pip3 can exit 0 on some systems (PEP 668 externally-
-      // managed environments, non-writable site-packages) even when
-      // the subsequent import still fails. After the pip step, run
-      // a post-install import check and surface both the pip output
-      // and the import error together if the check fails — that's
-      // the signal the operator needs to know whether to pick a
-      // virtualenv, use --user, or --break-system-packages.
+      // #380: create a dedicated bridge venv at
+      // `<BRIDGE_DIR>/.venv` and install requirements into it using
+      // that venv's pip. All bridge subprocesses then spawn with
+      // `<BRIDGE_DIR>/.venv/bin/python3` by absolute path. See #379
+      // research ticket for the root cause — bare `python3` / `pip3`
+      // resolve to Homebrew Python on modern macOS where `requests`
+      // is not available, producing a ModuleNotFoundError on Start.
+      // Idempotent: existing installs missing a `.venv` get the venv
+      // created on top of the existing clone without re-cloning.
+      const venvDir = path.join(BRIDGE_DIR, ".venv");
+      const venvPython = path.join(venvDir, "bin", "python3");
+      const venvPip = path.join(venvDir, "bin", "pip");
       let pipOutput = "";
       try {
         if (!fs.existsSync(BRIDGE_DIR)) {
           execFileSync("gh", ["repo", "clone", "realproject7/agentchattr-telegram", BRIDGE_DIR], { encoding: "utf-8", timeout: 30000 });
         }
+        // #380: create the dedicated venv if missing. `python3 -m venv`
+        // builds a fresh isolated environment that bypasses PEP 668
+        // externally-managed markers, so this works even on Homebrew
+        // Python where bare `pip3 install` would be blocked.
+        if (!fs.existsSync(venvPython)) {
+          execFileSync("python3", ["-m", "venv", venvDir], { encoding: "utf-8", timeout: 60000 });
+        }
         pipOutput = execFileSync(
-          "pip3",
+          venvPip,
           ["install", "-r", path.join(BRIDGE_DIR, "requirements.txt")],
-          { encoding: "utf-8", timeout: 60000 },
+          { encoding: "utf-8", timeout: 120000 },
         );
       } catch (err) {
-        return res.json({ ok: false, error: err.message || "Install failed" });
+        const stderr = (err && err.stderr && err.stderr.toString && err.stderr.toString()) || "";
+        return res.json({ ok: false, error: (stderr.trim() || err.message || "Install failed") });
       }
-      const depCheck = checkTelegramBridgePythonDeps();
+      const depCheck = checkTelegramBridgePythonDeps(venvPython);
       if (!depCheck.ok) {
         return res.json({
           ok: false,
           error:
-            "pip3 reported success but the bridge's Python deps still fail to import. " +
-            "This usually means pip installed into a location python3 cannot see " +
-            "(externally-managed environment / PEP 668 / mismatched interpreter).\n\n" +
+            "pip reported success but the bridge venv's Python deps still fail to import. " +
+            "This is unexpected for a freshly-created venv — check disk space and permissions " +
+            `on ${venvDir}.\n\n` +
             `Import error: ${depCheck.error}\n\n` +
             `pip output tail:\n${pipOutput.split("\n").slice(-10).join("\n")}`,
         });
@@ -2543,6 +2646,18 @@ router.post("/api/telegram", async (req, res) => {
       if (isTelegramRunning(projectId)) return res.json({ ok: true, running: true, message: "Already running" });
       const bridgeScript = path.join(BRIDGE_DIR, "telegram_bridge.py");
       if (!fs.existsSync(bridgeScript)) return res.json({ ok: false, error: "Bridge not installed. Click Install Bridge first." });
+      // #380: resolve the dedicated venv's python3 by absolute path.
+      // Do NOT activate the venv or set VIRTUAL_ENV in the parent —
+      // calling the venv's python3 directly is sufficient because
+      // Python's sys.executable bootstrap resolves the venv
+      // automatically. See #379 research ticket.
+      const venvPython = path.join(BRIDGE_DIR, ".venv", "bin", "python3");
+      if (!fs.existsSync(venvPython)) {
+        return res.json({
+          ok: false,
+          error: "Bridge venv missing. Click \"Install Bridge\" to create it.",
+        });
+      }
       const tg = getProjectTelegram(projectId);
       if (!tg || !tg.bot_token || !tg.chat_id) return res.json({ ok: false, error: "Save bot_token and chat_id in project settings first." });
       const tomlPath = telegramConfigToml(projectId);
@@ -2553,7 +2668,7 @@ router.post("/api/telegram", async (req, res) => {
       // `requests` module produces a readable error instead of the
       // Start → Running → Stopped flicker that the v1 code path
       // produced with `stdio: "ignore"`.
-      const depCheck = checkTelegramBridgePythonDeps();
+      const depCheck = checkTelegramBridgePythonDeps(venvPython);
       if (!depCheck.ok) {
         // #372: persist the pre-flight failure to the bridge log
         // file so the GET /api/telegram `last_error` tail picks it
@@ -2562,8 +2677,8 @@ router.post("/api/telegram", async (req, res) => {
         // local error state, producing the "silent fail" symptom
         // (pill flips back to Stopped with no trace of why).
         const msg =
-          "Bridge Python dependencies not installed. Click \"Install Bridge\" to install them, " +
-          "or run: pip3 install -r " + path.join(BRIDGE_DIR, "requirements.txt") + "\n\n" +
+          "Bridge Python dependencies not installed in the dedicated venv. " +
+          "Click \"Install Bridge\" to (re)create the venv and install them.\n\n" +
           `Import error: ${depCheck.error}`;
         try {
           fs.writeFileSync(
@@ -2595,7 +2710,7 @@ router.post("/api/telegram", async (req, res) => {
       }
       let child;
       try {
-        child = spawn("python3", [bridgeScript, "--config", tomlPath], {
+        child = spawn(venvPython, [bridgeScript, "--config", tomlPath], {
           detached: true,
           stdio: ["ignore", outFd, errFd],
         });
@@ -2780,3 +2895,9 @@ module.exports.buildNoPrRow = buildNoPrRow;
 module.exports.summarizeItems = summarizeItems;
 // #353: expose readLastLines for the telegram-bridge test.
 module.exports.readLastLines = readLastLines;
+// #380: expose checkTelegramBridgePythonDeps so the bridge test can
+// exercise the venv-path interpreter argument round trip.
+module.exports.checkTelegramBridgePythonDeps = checkTelegramBridgePythonDeps;
+// #236: expose sendViaWebSocket so the chat-ws-send regression test
+// can verify the ack/body/error paths against a fake AC ws server.
+module.exports.sendViaWebSocket = sendViaWebSocket;

package/server/routes.telegramBridge.test.js

@@ -10,7 +10,8 @@ const assert = require("node:assert/strict");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
-const { readLastLines } = require("./routes");
+const { execFileSync } = require("node:child_process");
+const { readLastLines, checkTelegramBridgePythonDeps } = require("./routes");
 
 const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qw-bridge-log-"));
 function write(name, content) {
@@ -89,7 +90,54 @@ try {
   assert.match(tail, /ModuleNotFoundError/);
   assert.match(tail, /Install Bridge/);
 
-  console.log("routes.telegramBridge.test.js: all assertions passed (8 cases)");
+  // 9) #380: checkTelegramBridgePythonDeps accepts an explicit
+  //    interpreter path. Passing a guaranteed-broken path must
+  //    return { ok: false, error } without throwing.
+  const broken = checkTelegramBridgePythonDeps(path.join(tmp, "nope", "python3"));
+  assert.equal(broken.ok, false);
+  assert.ok(broken.error && broken.error.length > 0);
+
+  // 10) #380: start handler's missing-venv branch — we don't boot
+  //     the server here, but the branch reduces to a plain
+  //     fs.existsSync check on `<BRIDGE_DIR>/.venv/bin/python3`,
+  //     so we verify the check returns false for a fixture dir
+  //     that has no `.venv` subdir at all.
+  const fixtureBridgeDir = fs.mkdtempSync(path.join(tmp, "bridge-no-venv-"));
+  const missingVenvPython = path.join(fixtureBridgeDir, ".venv", "bin", "python3");
+  assert.equal(fs.existsSync(missingVenvPython), false);
+
+  // 11) #380: round-trip — build a real venv in a tmp dir, install
+  //     a stdlib-only sentinel is trivially importable, and confirm
+  //     checkTelegramBridgePythonDeps reports ok when `requests`
+  //     is installed into that venv. Skipped gracefully on CI if
+  //     `python3 -m venv` or network-backed pip install fails.
+  const venvDir = path.join(tmp, "case11-venv");
+  let venvSkipped = false;
+  try {
+    execFileSync("python3", ["-m", "venv", venvDir], { timeout: 30000, stdio: "pipe" });
+    const venvPython = path.join(venvDir, "bin", "python3");
+    const venvPip = path.join(venvDir, "bin", "pip");
+    // Without `requests` installed yet, the check must fail.
+    const before = checkTelegramBridgePythonDeps(venvPython);
+    assert.equal(before.ok, false);
+    try {
+      execFileSync(venvPip, ["install", "--quiet", "requests"], { timeout: 120000, stdio: "pipe" });
+    } catch {
+      venvSkipped = true;
+    }
+    if (!venvSkipped) {
+      const after = checkTelegramBridgePythonDeps(venvPython);
+      assert.equal(after.ok, true);
+    }
+  } catch {
+    venvSkipped = true;
+  }
+
+  console.log(
+    "routes.telegramBridge.test.js: all assertions passed (11 cases" +
+      (venvSkipped ? ", case 11 pip step skipped" : "") +
+      ")",
+  );
 } finally {
   try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {}
 }