runspec-console 0.44.2__tar.gz → 0.45.0__tar.gz

{runspec_console-0.44.2 → runspec_console-0.45.0}/CHANGELOG.md

@@ -8,6 +8,33 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 ---
 
 
+## [0.45.0] — 2026-06-12
+
+### Added
+- **Room connection tester (Rooms tab → "Test").** Diagnoses a room/queue's
+  connection on demand over the *real* paramiko path the supervisor uses (HTTP
+  proxy, key, ssh_config, then the tunnel or exec relay), in an isolated attempt
+  that ignores the pool's connect-backoff and doesn't disturb the live
+  connection. It reports the actual blocker with a localised stage —
+  **ssh** (reach/auth the host, incl. the proxy), **channel** (tunnel/exec
+  relay), or **room** (the relay reached the host but the room server isn't
+  answering on the port) — plus an actionable hint, in a dialog. No more reading
+  tracebacks or fumbling with a local `ssh` command (which exercises OpenSSH
+  ControlMaster/config the console never uses).
+
+### Changed
+- **Blocked SSH port-forwarding now logs one actionable line, not a repeating
+  traceback.** A host with `AllowTcpForwarding no` refuses the direct-tcpip room
+  tunnel (`Administratively prohibited`) — a permanent condition the reconnect
+  loop would otherwise re-report as a full traceback every backoff. The
+  supervisor now detects it and points at the fix (`room_via = "exec"`); the same
+  classification powers the connection tester.
+- **Agent-mode chat source logs its queue.** `listening on queue 'helpdesk/<q>'`
+  instead of the empty `listening in room ''` (an agent subscribes to a namespace,
+  not a room).
+
+---
+
 ## [0.44.2] — 2026-06-12
 
 ### Changed

{runspec_console-0.44.2 → runspec_console-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-console
-Version: 0.44.2
+Version: 0.45.0
 Requires-Python: >=3.11
 Requires-Dist: cryptography>=42.0
 Requires-Dist: paramiko>=3.0

{runspec_console-0.44.2 → runspec_console-0.45.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-console"
-version = "0.44.2"
+version = "0.45.0"
 requires-python = ">=3.11"
 dependencies = [
     "pywebview>=5.0",

{runspec_console-0.44.2 → runspec_console-0.45.0}/runspec_console/bridge.py

@@ -150,6 +150,71 @@ class _BridgeTriggerOps:
         )
 
 
+def _chat_connect_hint(exc: BaseException, *, via: str) -> str | None:
+    """A concise, actionable message for a known-*permanent* chat-connect failure,
+    or ``None`` to fall back to a full traceback.
+
+    ``Administratively prohibited`` on a ``direct-tcpip`` channel means the host
+    refuses SSH port-forwarding (``AllowTcpForwarding no``) — retrying the tunnel
+    will never succeed, so a 20-line traceback every backoff is just noise. The
+    fix is the exec relay, so point the operator straight at it."""
+    if via != "exec" and "Administratively prohibited" in str(exc):
+        return (
+            "SSH port-forwarding is blocked on this host (Administratively "
+            'prohibited). Set room_via = "exec" on the host entry to reach the '
+            "room over an exec channel (console-room connect) instead of a tunnel."
+        )
+    return None
+
+
+def _classify_room_connection(exc: BaseException | None, *, via: str) -> dict[str, Any]:
+    """Turn a room-connect attempt's outcome into a structured, human-readable
+    result for the UI's connection tester: ``{ok, stage, message, hint}``.
+
+    ``stage`` localises the failure — ``ssh`` (reaching/authing the host, incl.
+    the HTTP proxy), ``channel`` (opening the tunnel / exec relay), ``room`` (the
+    relay reached the host but not the room server), or ``ok``. ``hint`` is an
+    actionable next step when we recognise the failure."""
+    if exc is None:
+        return {"ok": True, "stage": "ok", "message": "", "hint": None}
+    text = str(exc) or type(exc).__name__
+    low = text.lower()
+    if "in connect-backoff" in low:
+        return {
+            "ok": False,
+            "stage": "ssh",
+            "message": f"Host is in connect-backoff after recent failures ({text}). The always-on reconnect loop is already retrying — try again in a moment.",
+            "hint": None,
+        }
+    if isinstance(exc, TimeoutError) or "timed out" in low or "timeout" in low:
+        return {
+            "ok": False,
+            "stage": "ssh",
+            "message": "Timed out reaching the host — the SSH connection (through the HTTP proxy, if configured) didn't complete in time.",
+            "hint": "If the proxy works for discovery/transfers, this is usually transient at startup (many connections open at once) — retry. If it persists, check the [ssh] proxy host:port is reachable.",
+        }
+    if "administratively prohibited" in low:
+        return {
+            "ok": False,
+            "stage": "channel",
+            "message": "The host refused the tunnel — SSH port-forwarding is disabled (AllowTcpForwarding no).",
+            "hint": _chat_connect_hint(exc, via=via),
+        }
+    if "authentication" in low or "not a valid" in low or "no authentication" in low:
+        return {
+            "ok": False,
+            "stage": "ssh",
+            "message": f"SSH authentication failed ({text}). Check this host's key / identityFile.",
+            "hint": None,
+        }
+    return {
+        "ok": False,
+        "stage": "ssh",
+        "message": text,
+        "hint": _chat_connect_hint(exc, via=via),
+    }
+
+
 class _RotaPresenceWatcher:
     """Pushes console presence to the chat room as the working-hours rota flips.
 
@@ -5054,8 +5119,15 @@ class Bridge:
             )
             try:
                 source.start(self._on_chat_event)
-            except Exception:
-                logger.exception("chat: connect to room %r failed", room)
+            except Exception as exc:
+                # A blocked-forwarding failure is permanent — log one actionable
+                # line, not a fresh traceback every backoff. Genuinely unexpected
+                # errors still get the full traceback.
+                hint = _chat_connect_hint(exc, via=str(spec.get("via") or "tunnel"))
+                if hint:
+                    logger.error("chat: room %r — %s", room, hint)
+                else:
+                    logger.exception("chat: connect to room %r failed", room)
                 if self._chat_stop.wait(backoff):
                     break
                 backoff = min(backoff * 2, self._CHAT_BACKOFF_MAX)
@@ -5291,6 +5363,123 @@ class Bridge:
             rooms.append(entry)
         return {"rooms": rooms}
 
+    def test_room_connection(self, host: str) -> dict[str, Any]:
+        """Diagnose a room/queue's connection the way the supervisor reaches it —
+        an isolated, fresh attempt (no pool backoff, no effect on the live
+        connection) over the *same* paramiko path (HTTP proxy, key, ssh_config),
+        so the UI can show the real outcome instead of a buried traceback.
+
+        Steps, matching the transport: connect+auth to the host (the ``ssh``
+        stage — where the proxy timeout surfaces), open the tunnel / exec relay
+        (``channel`` — where blocked forwarding surfaces), and for exec confirm
+        the relay didn't immediately exit (``room`` — the room server is actually
+        listening). Returns the ``_classify_room_connection`` shape plus the host
+        / room / queue it tested."""
+        from .executor import _make_ssh_client
+
+        specs = [
+            s
+            for s in self._room_specs()
+            if s.get("host") == host or s.get("ssh_target") == host
+        ]
+        if not specs:
+            return {
+                "ok": False,
+                "stage": "config",
+                "host": host,
+                "message": f"No room or queue is configured on host {host!r}.",
+                "hint": "Add room/room_port (group chat) or room_queue/room_port (help desk) to this host.",
+            }
+        spec = specs[0]
+        cfg = self.get_config().get("ssh")
+        cfg = cfg if isinstance(cfg, dict) else None
+        via = str(spec.get("via") or "tunnel")
+        meta = {
+            "host": host,
+            "room": spec["room"],
+            "queue": str(spec.get("queue") or ""),
+        }
+
+        client = None
+        chan = None
+        try:
+            try:
+                client = _make_ssh_client(
+                    str(spec["ssh_target"]), spec.get("identity_file") or None, cfg
+                )
+            except Exception as exc:  # noqa: BLE001 — report, don't raise
+                return {**_classify_room_connection(exc, via=via), **meta}
+
+            transport = client.get_transport()
+            if transport is None:
+                return {
+                    **_classify_room_connection(OSError("transport closed"), via=via),
+                    **meta,
+                }
+            try:
+                if via == "exec":
+                    chan = transport.open_session()
+                    chan.exec_command(str(spec["exec_command"]))
+                else:
+                    chan = transport.open_channel(
+                        "direct-tcpip",
+                        (str(spec.get("dest_host") or "127.0.0.1"), int(spec["port"])),
+                        ("127.0.0.1", 0),
+                    )
+            except Exception as exc:  # noqa: BLE001
+                return {**_classify_room_connection(exc, via=via), **meta}
+
+            # Exec: the relay (console-room connect) connects to localhost:port on
+            # the host. If the room server is down it exits straight away — catch
+            # that so "host reachable but room down" isn't reported as success.
+            if via == "exec":
+                time.sleep(1.5)
+                if chan.exit_status_ready():
+                    err = ""
+                    try:
+                        if chan.recv_stderr_ready():
+                            err = (
+                                chan.recv_stderr(2048)
+                                .decode("utf-8", "replace")
+                                .strip()
+                            )
+                    except Exception:
+                        pass
+                    return {
+                        **meta,
+                        "ok": False,
+                        "stage": "room",
+                        "message": (
+                            f"Reached the host, but the relay exited — the room "
+                            f"server isn't answering on port {spec['port']} "
+                            f"(is console-room running there?)."
+                            + (f" [{err}]" if err else "")
+                        ),
+                        "hint": "Start the room server on the host (console-room) and confirm its --ndjson-port matches this host's room_port.",
+                    }
+
+            return {
+                **meta,
+                "ok": True,
+                "stage": "ok",
+                "message": (
+                    f"Connected to the room on {host} (port {spec['port']}, via {via})."
+                    + (f" Queue {spec['queue']}." if spec.get("queue") else "")
+                ),
+                "hint": None,
+            }
+        finally:
+            try:
+                if chan is not None:
+                    chan.close()
+            except Exception:
+                pass
+            try:
+                if client is not None:
+                    client.close()
+            except Exception:
+                pass
+
     def _abort_turns(self, ids: set[str] | None) -> None:
         """Unblock in-flight turns: signal each cancel flag and wake each pending
         autonomy-gate confirm (as cancelled). ``ids=None`` aborts everything

{runspec_console-0.44.2 → runspec_console-0.45.0}/runspec_console/sources/chat.py

@@ -335,7 +335,10 @@ class ChatSource:
         transport = self._transport
         if transport is None:
             return
-        logger.info("chat source: listening in room %r", self._room)
+        if self.is_agent:
+            logger.info("chat source: listening on queue %r", self._namespace)
+        else:
+            logger.info("chat source: listening in room %r", self._room)
         while not self._stop.is_set():
             try:
                 obj = transport.recv()

{runspec_console-0.44.2 → runspec_console-0.45.0}/tests/test_chat_bridge.py

@@ -639,3 +639,84 @@ def test_propose_reply_rejects_empty_text():
         _propose_stub()._gated_propose_reply({"text": "  "}, "card1", "ops")
     )
     assert out.startswith("✗") and "empty" in out
+
+
+# ── connect-error hint (blocked port-forwarding → exec) ────────────────────────
+
+
+def test_chat_connect_hint_for_blocked_forwarding():
+    from runspec_console.bridge import _chat_connect_hint
+
+    exc = Exception("ChannelException(1, 'Administratively prohibited')")
+    hint = _chat_connect_hint(exc, via="tunnel")
+    assert hint is not None and 'room_via = "exec"' in hint
+
+
+def test_chat_connect_hint_none_in_exec_mode():
+    from runspec_console.bridge import _chat_connect_hint
+
+    # Already on exec → the prohibited-forwarding hint doesn't apply.
+    exc = Exception("ChannelException(1, 'Administratively prohibited')")
+    assert _chat_connect_hint(exc, via="exec") is None
+
+
+def test_chat_connect_hint_none_for_other_errors():
+    from runspec_console.bridge import _chat_connect_hint
+
+    assert _chat_connect_hint(TimeoutError("timed out"), via="tunnel") is None
+
+
+# ── room connection tester (classifier) ────────────────────────────────────────
+
+
+def test_classify_room_connection_success():
+    from runspec_console.bridge import _classify_room_connection
+
+    r = _classify_room_connection(None, via="exec")
+    assert r["ok"] and r["stage"] == "ok"
+
+
+def test_classify_room_connection_proxy_timeout():
+    from runspec_console.bridge import _classify_room_connection
+
+    r = _classify_room_connection(TimeoutError("timed out"), via="exec")
+    assert not r["ok"] and r["stage"] == "ssh"
+    assert "proxy" in r["hint"].lower()
+
+
+def test_classify_room_connection_blocked_forwarding():
+    from runspec_console.bridge import _classify_room_connection
+
+    exc = Exception("ChannelException(1, 'Administratively prohibited')")
+    r = _classify_room_connection(exc, via="tunnel")
+    assert not r["ok"] and r["stage"] == "channel"
+    assert 'room_via = "exec"' in r["hint"]
+
+
+def test_classify_room_connection_backoff():
+    from runspec_console.bridge import _classify_room_connection
+
+    from runspec_console.ssh_pool import BackoffError
+
+    r = _classify_room_connection(
+        BackoffError("host in connect-backoff for 4s"), via="exec"
+    )
+    assert not r["ok"] and r["stage"] == "ssh" and "backoff" in r["message"].lower()
+
+
+def test_classify_room_connection_auth():
+    from runspec_console.bridge import _classify_room_connection
+
+    r = _classify_room_connection(Exception("Authentication failed."), via="exec")
+    assert not r["ok"] and r["stage"] == "ssh" and "identityFile" in r["message"]
+
+
+def test_test_room_connection_unconfigured_host():
+    from runspec_console.bridge import Bridge
+
+    s = types.SimpleNamespace()
+    s._room_specs = lambda: []
+    s.get_config = lambda: {}
+    s.test_room_connection = types.MethodType(Bridge.test_room_connection, s)
+    r = s.test_room_connection("nope")
+    assert not r["ok"] and r["stage"] == "config"