A terminal panel beside an agent chat

A real shell on the chat's own connection, opened and closed like the
inspector and never beside it. The modes govern the model; what a person
types is theirs, since they hold the credential and could open the same
shell with an ssh client. The model cannot see the panel -- a button
copies the output you choose into the composer.

The session outlives the socket: closing the panel leaves a build
running, and coming back reattaches with the scrollback. Two tabs share
one shell and the smaller window decides the size. It ends on an idle
timeout, on deleting the chat, on disabling, moving or deleting the
connection, and on a restart -- which says why rather than quietly
opening a fresh shell that has lost the working directory.

The nginx template's `Connection ""` is right for SSE and fails every
WebSocket handshake, so `location /` now uses a `map $http_upgrade`;
update.sh grows a drift check for it, because the only symptom on a
stale vhost is a panel that cannot connect.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/lembas/api/admin_agents.py

@@ -21,6 +21,7 @@ from lembas.db.models import SshProfile
 from lembas.services import settings_store
 from lembas.services.agent import policy
 from lembas.services.agent import ssh as ssh_service
+from lembas.services.agent import terminal as terminal_service
 from lembas.web.templating import render
 
 log = logging.getLogger(__name__)
@@ -45,6 +46,7 @@ async def agents_page(request: Request, db: Db, user: AdminUser, saved: bool = F
             "deny_text": "\n".join(values.get("deny_default") or []),
             "problem": ssh_service.available(),
             "profile_count": db.scalar(select(func.count()).select_from(SshProfile)) or 0,
+            "terminal_count": terminal_service.count(),
             "modes": [(m, policy.MODE_LABELS[m], policy.MODE_HINTS[m]) for m in policy.MODES],
             "saved": saved,
         },
@@ -66,6 +68,10 @@ async def save_agents(
     allow_default: str = Form(""),
     deny_default: str = Form(""),
     ask_free_text: bool = Form(False),
+    terminal_enabled: bool = Form(False),
+    terminal_idle_timeout: int = Form(1800),
+    terminal_max_sessions: int = Form(20),
+    terminal_max_per_user: int = Form(3),
 ) -> Response:
     settings_store.update(
         db,
@@ -84,6 +90,10 @@ async def save_agents(
             "allow_default": _lines(allow_default),
             "deny_default": _lines(deny_default),
             "ask_free_text": ask_free_text,
+            "terminal_enabled": terminal_enabled,
+            "terminal_idle_timeout": min(max(terminal_idle_timeout, 60), 86400),
+            "terminal_max_sessions": min(max(terminal_max_sessions, 1), 500),
+            "terminal_max_per_user": min(max(terminal_max_per_user, 1), 50),
         },
         key=settings_store.AGENTS,
     )

src/lembas/api/agents.py

@@ -25,6 +25,7 @@ from lembas.api.pages import sidebar_context
 from lembas.db.models import AUTH_METHODS, AUTH_PASSWORD, SshProfile
 from lembas.services import settings_store
 from lembas.services.agent import ssh as ssh_service
+from lembas.services.agent import terminal as terminal_service
 from lembas.services.agent.base import ExecError
 from lembas.services.crypto import UNCHANGED_SENTINEL, decrypt, keep_or_replace, mask
 from lembas.web.templating import render
@@ -293,6 +294,9 @@ async def forget_host_key(request: Request, db: Db, user: RequiredUser, profile_
     profile = _profile(db, user, profile_id)
     profile.host_key = ""
     profile.host_fingerprint = ""
+    # Un-trusting a host has to reach the shell already open on it, or the one
+    # connection that matters is the one this does not touch.
+    await terminal_service.close_for_profile(profile.id)
     db.commit()
     return render(request, "agents/_check.html", {"profile": profile, "forgotten": True})
 
@@ -301,6 +305,7 @@ async def forget_host_key(request: Request, db: Db, user: RequiredUser, profile_
 async def delete_profile(db: Db, user: RequiredUser, profile_id: str) -> Response:
     profile = _profile(db, user, profile_id)
     name = profile.name
+    await terminal_service.close_for_profile(profile.id)
     db.delete(profile)
     db.commit()
     log.info("%s deleted ssh profile %s", user.email, name)
@@ -342,6 +347,13 @@ async def update_profile(request: Request, db: Db, user: RequiredUser, profile_i
         profile.host_fingerprint = ""
         log.info("%s moved ssh profile %s; its host key was forgotten", user.email, profile.name)
 
+    # A shell already open holds its own connection and would not notice any of
+    # this. `session.profile_for` re-checks the profile on every reply, so the
+    # model stops at once; without the line below, "I disabled that connection"
+    # would simply not be true of the terminal on screen.
+    if not profile.enabled or not profile.host_key or (profile.host, profile.port) != before:
+        await terminal_service.close_for_profile(profile.id)
+
     db.commit()
     return RedirectResponse(
         f"/agents/{profile.id}?saved=Saved.", status_code=status.HTTP_303_SEE_OTHER

src/lembas/api/auth.py

@@ -34,9 +34,19 @@ def _set_session_cookie(response: Response, token: str) -> None:
         # Lax is what makes this application CSRF-safe without tokens: the
         # cookie is not sent on cross-site POSTs, and every mutating route here
         # is a POST. Do not relax to "none".
+        #
+        # One route is no longer a POST: the terminal WebSocket is a GET, and
+        # what it opens is a shell. Lax still withholds the cookie from a
+        # handshake a foreign page starts, so the attack is blocked -- but the
+        # sentence above is no longer the whole story, which is why
+        # `api/terminal.py` also *requires* a same-origin Origin header rather
+        # than merely checking one when it happens to be there.
         samesite="lax",
         # Only over HTTPS when the deployment is not plain local http. Marking
         # it secure on http would silently break sign-in for a LAN install.
+        # It has always meant "a network attacker on plain http can steal a
+        # session"; with the terminal it also means they get a shell on the
+        # machine behind that chat. See deploy/README.md.
         secure=False,
         path="/",
     )

src/lembas/api/chats.py

@@ -36,6 +36,7 @@ from lembas.services import prompts as prompts_service
 from lembas.services import settings_store, sse
 from lembas.services import tools as tools_service
 from lembas.services.agent import policy as agent_policy
+from lembas.services.agent import terminal as terminal_service
 from lembas.services.markdown import escape_text, render_markdown
 from lembas.web.templating import render, templates
 
@@ -997,6 +998,10 @@ def _clean_params(**submitted: str | None) -> dict[str, float | int | None]:
 @router.delete("/{chat_id}", dependencies=[Depends(require_permission("chat.delete"))])
 async def delete_chat(db: Db, user: RequiredUser, chat_id: str) -> Response:
     chat = _owned_chat(db, chat_id, user.id)
+    # Before the row goes: a terminal is keyed on the chat id, so afterwards
+    # there would be nothing left to find it by and a shell would sit open on
+    # somebody's machine until the idle timeout noticed.
+    await terminal_service.close_chat(chat_id)
     db.delete(chat)
     db.commit()
 

src/lembas/api/deps.py

@@ -8,6 +8,7 @@ from typing import Annotated
 from fastapi import Depends, HTTPException, Request, status
 from fastapi.responses import RedirectResponse
 from sqlalchemy.orm import Session as DBSession
+from starlette.requests import HTTPConnection
 
 from lembas.db.models import User
 from lembas.db.session import get_session_factory
@@ -26,17 +27,23 @@ def get_db() -> Iterator[DBSession]:
 Db = Annotated[DBSession, Depends(get_db)]
 
 
-def get_current_user(request: Request, db: Db) -> User | None:
+def get_current_user(conn: HTTPConnection, db: Db) -> User | None:
     """Resolve the session cookie to a user, or None when signed out.
 
-    Cached on request.state so several dependencies in one request do not each
-    hit the sessions table.
+    Cached on the connection's state so several dependencies in one request do
+    not each hit the sessions table.
+
+    `HTTPConnection` rather than `Request` because the terminal panel is a
+    WebSocket, and FastAPI injects a `WebSocket` there -- annotating this
+    `Request` fails at *connect* time rather than at import, so it would pass
+    every smoke test and break in a browser. `HTTPConnection` is the base of
+    both and carries the cookies and the state either way.
     """
-    cached = getattr(request.state, "user", None)
+    cached = getattr(conn.state, "user", None)
     if cached is not None:
         return cached
-    user = resolve_session(db, request.cookies.get(COOKIE_NAME))
-    request.state.user = user
+    user = resolve_session(db, conn.cookies.get(COOKIE_NAME))
+    conn.state.user = user
     return user
 
 

src/lembas/api/pages.py

@@ -97,9 +97,31 @@ def _agent_context(db: DBSession, user: User, chat: Chat | None) -> dict:
             (m, agent_policy.MODE_LABELS[m], agent_policy.MODE_HINTS[m])
             for m in agent_policy.MODES
         ],
+        "terminal_enabled": _terminal_enabled(db, user, chat, current),
     }
 
 
+def _terminal_enabled(db: DBSession, user: User, chat: Chat | None, profile) -> bool:
+    """Whether this chat can offer a shell of its own.
+
+    Every condition, not a subset: the button loads 280KB of terminal and opens
+    a socket, so one that cannot work is worse than none. `ssh.available()` is
+    in here because an instance that installed LLeMbas without the `ssh` extra
+    would otherwise render a button whose only outcome is an error frame.
+    """
+    from lembas.db.models import KIND_AGENT
+    from lembas.services.agent import ssh as ssh_service
+
+    if chat is None or chat.kind != KIND_AGENT or profile is None:
+        return False
+    if not permissions.has(db, user, "agent.terminal"):
+        return False
+    values = settings_store.agents(db)
+    if not values.get("enabled") or not values.get("terminal_enabled", True):
+        return False
+    return ssh_service.available() == ""
+
+
 def sidebar_context(db: DBSession, user: User) -> dict:
     """Folder tree plus the chats that belong to no folder.
 

src/lembas/api/terminal.py

@@ -0,0 +1,251 @@
+"""The socket behind the terminal panel.
+
+A WebSocket rather than SSE, because SSE is one-directional and a terminal is
+not: keystrokes have to go up, and an HTTP round trip per keypress is not a
+terminal. It is the only WebSocket in LLeMbas, and it is worth saying what that
+costs -- a cross-site page that could reach this endpoint would have a shell on
+somebody's machine, not merely a copy of their chat. So there are two locks on
+the door, and this module is mostly them.
+
+**Where a refusal happens is load-bearing.** A browser tells a page nothing
+about a handshake that *failed*: `new WebSocket()` fires `error` with no status
+and no reason. So the socket is accepted first and the reason sent as a frame
+for everything a person could act on -- no permission, the connection is
+disabled, its host key was never confirmed -- and refused before accepting only
+for the two cases where accepting is itself the risk.
+
+It holds no database session. A dependency would keep one open for the hour a
+shell sits at a prompt; `session_scope()` opens one for the authorisation and
+closes it, exactly as `generation._run` does.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from urllib.parse import urlsplit
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from lembas.db.models import KIND_AGENT, Chat
+from lembas.db.session import session_scope
+from lembas.security import permissions
+from lembas.security.sessions import COOKIE_NAME, resolve_session
+from lembas.services import settings_store
+from lembas.services.agent import session as agent_session
+from lembas.services.agent import terminal as terminal_service
+from lembas.services.agent.base import ExecError
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/chats", tags=["terminal"])
+
+# Nothing a keyboard produces is anywhere near this. Paste is the only thing
+# that comes close, and a megabyte pasted into a shell is a mistake either way.
+MAX_INPUT_BYTES = 256 * 1024
+
+# 1008 is "policy violation", the closest thing the protocol has to "no".
+CLOSE_POLICY = 1008
+
+# What the far side is told when a shell ends, in words rather than a code.
+CLOSED_WORDS = {
+    terminal_service.CLOSED_EXITED: "The shell exited.",
+    terminal_service.CLOSED_IDLE: "This terminal was closed after sitting idle.",
+    terminal_service.CLOSED_SHUTDOWN: "LLeMbas restarted, so this shell was closed.",
+    terminal_service.CLOSED_REVOKED: "The connection behind this terminal was closed.",
+    terminal_service.CLOSED_ERROR: "The connection to the machine was lost.",
+}
+
+
+def _same_origin(websocket: WebSocket) -> bool:
+    """Whether this handshake came from a page served by this site.
+
+    Required, not merely checked when present. The session cookie is SameSite
+    Lax, which already withholds it from a handshake a foreign page starts, and
+    this is the belt to that brace -- an absent Origin is not a browser, and a
+    non-browser client has no business here.
+    """
+    origin = websocket.headers.get("origin")
+    host = websocket.headers.get("host")
+    if not origin or not host:
+        return False
+    return urlsplit(origin).netloc.lower() == host.lower()
+
+
+def _prepare(db, user, chat_id: str) -> tuple[str, dict]:
+    """Everything that has to be true, and what opening needs. One or the other.
+
+    Returns a message to show, or the arguments for `open_session`. The order is
+    the order somebody would ask the questions in, and every "no" is a sentence
+    rather than a silence.
+    """
+    if not permissions.has(db, user, "agent.terminal"):
+        return "You do not have permission to open a terminal.", {}
+
+    chat = db.get(Chat, chat_id)
+    if chat is None or chat.user_id != user.id:
+        return "That chat no longer exists.", {}
+    if chat.kind != KIND_AGENT:
+        return "This is an ordinary chat, so it has no machine to open a shell on.", {}
+
+    values = settings_store.agents(db)
+    if not values.get("terminal_enabled", True):
+        return "The terminal is switched off on this instance.", {}
+
+    context = agent_session.resolve(db, chat, user)
+    if context is None:
+        return (
+            "This chat's connection is not usable: it may have been deleted, "
+            "disabled, or agent chats may be switched off here.",
+            {},
+        )
+
+    return "", {
+        "owner_id": user.id,
+        "profile_id": chat.ssh_profile_id or "",
+        "label": context.label,
+        "spec": context.spec,
+        "project_dir": context.project_dir,
+        "idle_timeout": float(values["terminal_idle_timeout"]),
+        "max_sessions": int(values["terminal_max_sessions"]),
+        "max_per_user": int(values["terminal_max_per_user"]),
+    }
+
+
+@router.websocket("/{chat_id}/terminal/ws")
+async def terminal_socket(
+    websocket: WebSocket,
+    chat_id: str,
+    cols: int = 80,
+    rows: int = 24,
+) -> None:
+    if not _same_origin(websocket):
+        await websocket.close(code=CLOSE_POLICY)
+        return
+
+    with session_scope() as db:
+        user = resolve_session(db, websocket.cookies.get(COOKIE_NAME))
+        if user is None:
+            await websocket.close(code=CLOSE_POLICY)
+            return
+        problem, opening = _prepare(db, user, chat_id)
+        owner_email = user.email
+
+    await websocket.accept()
+    if problem:
+        await _refuse(websocket, problem)
+        return
+
+    try:
+        session = await terminal_service.open_session(chat_id, cols=cols, rows=rows, **opening)
+    except ExecError as exc:
+        await _refuse(websocket, str(exc))
+        return
+    except Exception:  # noqa: BLE001 - a failure here is one socket, not the app
+        log.exception("could not open a terminal for %s", owner_email)
+        await _refuse(websocket, "The shell could not be started.")
+        return
+
+    viewer = session.attach(cols, rows)
+    await websocket.send_text(
+        json.dumps(
+            {
+                "t": "ready",
+                "label": session.label,
+                "dir": session.project_dir,
+                "cols": session.cols,
+                "rows": session.rows,
+                # Two tabs share one shell, and a size neither of them chose is
+                # otherwise a mystery.
+                "shared": len(session.viewers) > 1,
+            }
+        )
+    )
+    if viewer.snapshot:
+        await websocket.send_bytes(viewer.snapshot)
+
+    downward = asyncio.create_task(_to_browser(websocket, session, viewer))
+    upward = asyncio.create_task(_from_browser(websocket, session, viewer))
+    try:
+        await asyncio.wait({downward, upward}, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        for task in (downward, upward):
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await task
+        # The session is deliberately left running. Closing the panel, or
+        # navigating away, is not "I am finished with this machine" -- a build
+        # carries on and the scrollback is still there on the way back. The
+        # idle timeout is what eventually ends it.
+        session.detach(viewer)
+
+
+async def _to_browser(websocket: WebSocket, session, viewer) -> None:
+    """Everything the shell says, plus the one frame that says it stopped."""
+    while True:
+        chunk = await viewer.queue.get()
+        if chunk is None:
+            reason = terminal_service.CLOSED_EXITED if viewer.dropped else session.closed_reason
+            payload = {"t": "closed", "reason": reason, "message": _words(reason)}
+            if viewer.dropped:
+                # Not the session's doing: this browser stopped reading and was
+                # disconnected so the others kept up. Reconnecting costs it
+                # nothing, because the scrollback is the state.
+                payload = {"t": "behind", "message": "Reconnecting: output arrived faster than "
+                           "this window could draw it."}
+            with contextlib.suppress(Exception):
+                await websocket.send_text(json.dumps(payload))
+            return
+        await websocket.send_bytes(chunk)
+
+
+async def _from_browser(websocket: WebSocket, session, viewer) -> None:
+    """Keystrokes as binary, everything else as JSON.
+
+    Binary for the hot path is what makes multi-byte characters safe: a read on
+    the far side lands mid-sequence often enough to matter, and decoding each
+    frame here would corrupt every boundary. Nothing decodes, so nothing splits.
+    """
+    while True:
+        try:
+            message = await websocket.receive()
+        except WebSocketDisconnect:
+            return
+        if message["type"] == "websocket.disconnect":
+            return
+
+        data = message.get("bytes")
+        if data is not None:
+            if len(data) > MAX_INPUT_BYTES:
+                continue
+            await session.send(data)
+            continue
+
+        text = message.get("text")
+        if text:
+            _control(session, viewer, text)
+
+
+def _control(session, viewer, text: str) -> None:
+    try:
+        payload = json.loads(text)
+    except ValueError:
+        return
+    if not isinstance(payload, dict) or payload.get("t") != "resize":
+        return
+    session.resize(viewer, payload.get("cols", 80), payload.get("rows", 24))
+
+
+def _words(reason: str) -> str:
+    return CLOSED_WORDS.get(reason, "This terminal closed.")
+
+
+async def _refuse(websocket: WebSocket, message: str) -> None:
+    """Say why, then close. Sent as a frame because a browser cannot read a
+    rejected handshake -- the reason would be lost exactly when it is needed."""
+    with contextlib.suppress(Exception):
+        await websocket.send_text(json.dumps({"t": "error", "message": message}))
+    with contextlib.suppress(Exception):
+        await websocket.close()