Merge main into feat/acp-discriminated-union-v2 (picks up #2869)

Author: Debug Agent

openhands-sdk/openhands/sdk/agent/acp_agent.py

@@ -752,12 +752,22 @@ def init_state(
 
         self._initialized = True
 
-        # Store agent info in agent_state so it's accessible from remote
-        # conversations (PrivateAttrs aren't serialized in state updates).
+        # Persist agent info + the ACP session id + its cwd in agent_state.
+        # Keeping these here (rather than on the frozen ACPAgent model) means
+        # ConversationState's existing base_state.json persistence carries
+        # them across agent-server restarts, and ``_start_acp_server`` on the
+        # next launch reads them back to call ``load_session`` instead of
+        # starting from scratch.  We record ``acp_session_cwd`` alongside the
+        # id because ACP servers key their persistence by ``cwd``: resuming
+        # in a different working directory would at best silently miss the
+        # prior session and at worst load a different session that happens to
+        # exist at the new cwd.
         state.agent_state = {
             **state.agent_state,
             "acp_agent_name": self._agent_name,
             "acp_agent_version": self._agent_version,
+            "acp_session_id": self._session_id,
+            "acp_session_cwd": self._working_dir,
         }
 
     def _start_acp_server(self, state: ConversationState) -> None:
@@ -777,6 +787,27 @@ def _start_acp_server(self, state: ConversationState) -> None:
 
         working_dir = str(state.workspace.working_dir)
 
+        # Prior ACP session id — survives agent-server restarts via
+        # ConversationState.agent_state (serialized into base_state.json).
+        # Its presence is the signal to resume; its absence means fresh start.
+        # ACP servers key persistence by ``cwd``; if the workspace moved we
+        # drop the id so we don't accidentally resume (or silently load) a
+        # session the server associates with a different directory.
+        prior_session_id: str | None = state.agent_state.get("acp_session_id")
+        prior_session_cwd: str | None = state.agent_state.get("acp_session_cwd")
+        if prior_session_id is not None and prior_session_cwd not in (
+            None,
+            working_dir,
+        ):
+            logger.warning(
+                "ACP session %s was created with cwd=%s; current cwd=%s differs, "
+                "starting a fresh session instead of resuming",
+                prior_session_id,
+                prior_session_cwd,
+                working_dir,
+            )
+            prior_session_id = None
+
         async def _init() -> tuple[Any, Any, Any, str, str, str]:
             # Spawn the subprocess directly so we can install a
             # filtering reader that skips non-JSON-RPC lines some
@@ -845,14 +876,43 @@ async def _init() -> tuple[Any, Any, Any, str, str, str]:
                         [m.id for m in auth_methods],
                     )
 
-            # Build _meta content for session options (e.g. model selection).
-            # Extra kwargs to new_session() become the _meta dict in the
-            # JSON-RPC request — do NOT wrap in _meta= (that double-nests).
-            session_meta = _build_session_meta(agent_name, self.acp_model)
+            # Resume the prior ACP session if we have its id.  If the server
+            # has forgotten it (state wiped, new host, etc.) fall through to
+            # new_session so the conversation still starts cleanly.
+            #
+            # We only swallow ACPRequestError here: that is the protocol-level
+            # "I don't know this session" signal and is recoverable by
+            # starting fresh.  Transport failures (broken pipe, EOF, timeout,
+            # subprocess crash) propagate — there is no working connection to
+            # fall back on, and the outer init_state handler cleans up.
+            session_id: str | None = None
+            if prior_session_id is not None:
+                try:
+                    await conn.load_session(
+                        cwd=working_dir,
+                        session_id=prior_session_id,
+                        mcp_servers=[],
+                    )
+                    session_id = prior_session_id
+                    logger.info(
+                        "Resumed ACP session: %s (cwd=%s)",
+                        session_id,
+                        working_dir,
+                    )
+                except ACPRequestError as e:
+                    logger.warning(
+                        "ACP load_session(%s) failed (%s); starting a fresh session",
+                        prior_session_id,
+                        e,
+                    )
 
-            # Create a new session
-            response = await conn.new_session(cwd=working_dir, **session_meta)
-            session_id = response.session_id
+            if session_id is None:
+                # Build _meta content for session options (e.g. model selection).
+                # Extra kwargs to new_session() become the _meta dict in the
+                # JSON-RPC request — do NOT wrap in _meta= (that double-nests).
+                session_meta = _build_session_meta(agent_name, self.acp_model)
+                response = await conn.new_session(cwd=working_dir, **session_meta)
+                session_id = response.session_id
             await _maybe_set_session_model(
                 conn,
                 agent_name,

openhands-tools/openhands/tools/terminal/definition.py

@@ -33,7 +33,17 @@ class TerminalAction(Action):
     """Schema for bash command execution."""
 
     command: str = Field(
-        description="The bash command to execute. Can be empty string to view additional logs when previous exit code is `-1`. Can be `C-c` (Ctrl+C) to interrupt the currently running process. Note: You can only execute one bash command at a time. If you need to run multiple commands sequentially, you can use `&&` or `;` to chain them together."  # noqa
+        description=(
+            "The bash command to execute. Can be empty string to view"
+            " additional logs when previous exit code is `-1`. Can be a"
+            " special key name when `is_input` is True: `C-c` (Ctrl+C),"
+            " `C-d` (Ctrl+D/EOF), `C-z` (Ctrl+Z), or any `C-<letter>`"
+            " for Ctrl sequences; navigation keys `UP`, `DOWN`, `LEFT`,"
+            " `RIGHT`, `HOME`, `END`, `PGUP`, `PGDN`; and `TAB`, `ESC`,"
+            " `BS` (Backspace), `ENTER`. Note: You can only execute one"
+            " bash command at a time. If you need to run multiple commands"
+            " sequentially, you can use `&&` or `;` to chain them together."
+        )
     )
     is_input: bool = Field(
         default=False,
@@ -217,6 +227,8 @@ def visualize(self) -> Text:
   - Send empty `command` to retrieve additional logs
   - Send text (set `command` to the text) to STDIN of the running process
   - Send control commands like `C-c` (Ctrl+C), `C-d` (Ctrl+D), or `C-z` (Ctrl+Z) to interrupt the process
+  - Send navigation keys like `UP`, `DOWN`, `LEFT`, `RIGHT`, `TAB`, `ESC`, `BS` (Backspace), `HOME`, `END`, `PGUP`, `PGDN`
+  - Any `C-<letter>` Ctrl sequence is supported (e.g. `C-a`, `C-e`, `C-l`)
   - If you do C-c, you can re-start the process with a longer "timeout" parameter to let it run to completion
 
 ### Best Practices

openhands-tools/openhands/tools/terminal/terminal/__init__.py

@@ -3,8 +3,10 @@
 
 from openhands.tools.terminal.terminal.factory import create_terminal_session
 from openhands.tools.terminal.terminal.interface import (
+    SUPPORTED_SPECIAL_KEYS,
     TerminalInterface,
     TerminalSessionBase,
+    parse_ctrl_key,
 )
 from openhands.tools.terminal.terminal.terminal_session import (
     TerminalCommandStatus,
@@ -27,11 +29,13 @@
 
 
 __all__ = [
+    "SUPPORTED_SPECIAL_KEYS",
     "TerminalInterface",
     "TerminalSessionBase",
     "TmuxTerminal",
     "SubprocessTerminal",
     "TerminalSession",
     "TerminalCommandStatus",
     "create_terminal_session",
+    "parse_ctrl_key",
 ]

openhands-tools/openhands/tools/terminal/terminal/interface.py

@@ -12,6 +12,50 @@
 )
 
 
+# Canonical set of named special keys that all TerminalInterface
+# implementations must support.  Each backend maps these to its own
+# representation (ANSI escape bytes for PTY, tmux key names for tmux).
+SUPPORTED_SPECIAL_KEYS: frozenset[str] = frozenset(
+    {
+        "ENTER",
+        "TAB",
+        "BS",
+        "ESC",
+        "UP",
+        "DOWN",
+        "LEFT",
+        "RIGHT",
+        "HOME",
+        "END",
+        "PGUP",
+        "PGDN",
+        "C-L",
+        "C-D",
+        "C-C",
+    }
+)
+
+
+def parse_ctrl_key(text: str) -> str | None:
+    """Parse a Ctrl-<letter> token and return the normalized form ``C-x``.
+
+    Accepts ``C-x``, ``CTRL-x``, and ``CTRL+x`` (case-insensitive)
+    where *x* is a single ASCII letter.  Returns ``None`` when *text*
+    is not a recognized Ctrl sequence.
+    """
+    upper = text.strip().upper()
+    key: str | None = None
+    if upper.startswith("C-"):
+        key = upper[2:]
+    elif upper.startswith("CTRL-"):
+        key = upper[5:]
+    elif upper.startswith("CTRL+"):
+        key = upper[5:]
+    if key and len(key) == 1 and "A" <= key <= "Z":
+        return f"C-{key.lower()}"
+    return None
+
+
 class TerminalInterface(ABC):
     """Abstract interface for terminal backends.
 
@@ -63,9 +107,17 @@ def close(self) -> None:
     def send_keys(self, text: str, enter: bool = True) -> None:
         """Send text/keys to the terminal.
 
+        All implementations must support:
+          - Plain text (sent verbatim)
+          - Named specials: ENTER, TAB, BS, ESC, UP, DOWN, LEFT, RIGHT,
+            HOME, END, PGUP, PGDN, C-L, C-D, C-C
+          - Generic Ctrl sequences: ``C-<letter>``, ``CTRL-<letter>``,
+            ``CTRL+<letter>`` (case-insensitive, a-z)
+
         Args:
             text: Text or key sequence to send to the terminal.
-            enter: Whether to send Enter key after the text. Defaults to True.
+            enter: Whether to send Enter key after the text.
+                   Defaults to True.  Ignored for special/ctrl keys.
         """
 
     @abstractmethod

openhands-tools/openhands/tools/terminal/terminal/subprocess_terminal.py

@@ -30,12 +30,32 @@
 )
 from openhands.tools.terminal.metadata import CmdOutputMetadata
 from openhands.tools.terminal.terminal import TerminalInterface
+from openhands.tools.terminal.terminal.interface import parse_ctrl_key
 
 
 logger = get_logger(__name__)
 
 ENTER = b"\n"
 
+# Map normalized special key names to ANSI escape bytes for PTY.
+_SUBPROCESS_SPECIALS: dict[str, bytes] = {
+    "ENTER": ENTER,
+    "TAB": b"\t",
+    "BS": b"\x7f",  # Backspace (DEL)
+    "ESC": b"\x1b",
+    "UP": b"\x1b[A",
+    "DOWN": b"\x1b[B",
+    "RIGHT": b"\x1b[C",
+    "LEFT": b"\x1b[D",
+    "HOME": b"\x1b[H",
+    "END": b"\x1b[F",
+    "PGUP": b"\x1b[5~",
+    "PGDN": b"\x1b[6~",
+    "C-L": b"\x0c",  # Ctrl+L
+    "C-D": b"\x04",  # Ctrl+D (EOF)
+    "C-C": b"\x03",  # Ctrl+C (SIGINT)
+}
+
 
 def _normalize_eols(raw: bytes) -> bytes:
     # CRLF/LF/CR -> CR, so each logical line is terminated with \r for the TTY
@@ -341,7 +361,7 @@ def send_keys(self, text: str, enter: bool = True) -> None:
           - Plain text
           - Ctrl sequences: 'C-a'..'C-z' (Ctrl+C sends ^C byte)
           - Special names: 'ENTER','TAB','BS','ESC','UP','DOWN','LEFT','RIGHT',
-                           'HOME','END','PGUP','PGDN','C-L','C-D'
+                           'HOME','END','PGUP','PGDN','C-L','C-D','C-C'
 
         For multi-line commands exceeding _MULTILINE_THRESHOLD lines, sends
         line-by-line with pacing to prevent overwhelming the shell's input
@@ -350,40 +370,19 @@ def send_keys(self, text: str, enter: bool = True) -> None:
         if not self._initialized:
             raise RuntimeError("PTY terminal is not initialized")
 
-        specials = {
-            "ENTER": ENTER,
-            "TAB": b"\t",
-            "BS": b"\x7f",  # Backspace (DEL)
-            "ESC": b"\x1b",
-            "UP": b"\x1b[A",
-            "DOWN": b"\x1b[B",
-            "RIGHT": b"\x1b[C",
-            "LEFT": b"\x1b[D",
-            "HOME": b"\x1b[H",
-            "END": b"\x1b[F",
-            "PGUP": b"\x1b[5~",
-            "PGDN": b"\x1b[6~",
-            "C-L": b"\x0c",  # Ctrl+L
-            "C-D": b"\x04",  # Ctrl+D (EOF)
-        }
-
         upper = text.upper().strip()
         payload: bytes | None = None
 
         # Named specials
-        if upper in specials:
-            payload = specials[upper]
+        if upper in _SUBPROCESS_SPECIALS:
+            payload = _SUBPROCESS_SPECIALS[upper]
             # Do NOT auto-append another EOL; special already includes it when needed.
             append_eol = False
-        # Generic Ctrl-<letter>, including C-C (preferred over sending SIGINT directly)
-        elif upper.startswith(("C-", "CTRL-", "CTRL+")):
-            # last char after dash/plus is the key
-            key = upper.split("-", 1)[-1].split("+", 1)[-1]
-            if len(key) == 1 and "A" <= key <= "Z":
-                payload = bytes([ord(key) & 0x1F])
-            else:
-                # Unknown form; fall back to raw text
-                payload = text.encode("utf-8", "ignore")
+        # Generic Ctrl-<letter>
+        elif (ctrl := parse_ctrl_key(text)) is not None:
+            # ctrl is "C-x" — extract the letter
+            key_char = ctrl[-1].upper()
+            payload = bytes([ord(key_char) & 0x1F])
             append_eol = False  # ctrl combos are "instant"
         else:
             # Check if this is a long multi-line command that needs chunked sending

openhands-tools/openhands/tools/terminal/terminal/tmux_terminal.py

@@ -15,10 +15,30 @@
 )
 from openhands.tools.terminal.metadata import CmdOutputMetadata
 from openhands.tools.terminal.terminal import TerminalInterface
+from openhands.tools.terminal.terminal.interface import parse_ctrl_key
 
 
 logger = get_logger(__name__)
 
+# Map normalized special key names to tmux key names.
+_TMUX_SPECIALS: dict[str, str] = {
+    "ENTER": "Enter",
+    "TAB": "Tab",
+    "BS": "BSpace",
+    "ESC": "Escape",
+    "UP": "Up",
+    "DOWN": "Down",
+    "LEFT": "Left",
+    "RIGHT": "Right",
+    "HOME": "Home",
+    "END": "End",
+    "PGUP": "PPage",
+    "PGDN": "NPage",
+    "C-L": "C-l",
+    "C-D": "C-d",
+    "C-C": "C-c",
+}
+
 
 class TmuxTerminal(TerminalInterface):
     """Tmux-based terminal backend.
@@ -114,14 +134,39 @@ def close(self) -> None:
     def send_keys(self, text: str, enter: bool = True) -> None:
         """Send text/keys to the tmux pane.
 
+        Supports:
+          - Plain text (uses literal paste; preserves spaces/newlines)
+          - Named specials: ENTER, TAB, BS, ESC, UP, DOWN, LEFT, RIGHT,
+            HOME, END, PGUP, PGDN, C-L, C-D, C-C
+          - Generic Ctrl sequences: C-a..C-z, CTRL-x, CTRL+x
+
         Args:
             text: Text or key sequence to send
-            enter: Whether to send Enter key after the text
+            enter: Whether to send Enter key after the text.
+                   Ignored for special/ctrl keys.
         """
         if not self._initialized or not isinstance(self.pane, libtmux.Pane):
             raise RuntimeError("Tmux terminal is not initialized")
 
-        self.pane.send_keys(text, enter=enter)
+        # Map normalized names to tmux key names
+        upper = text.strip().upper()
+
+        # 1) Named specials
+        if upper in _TMUX_SPECIALS:
+            self.pane.send_keys(_TMUX_SPECIALS[upper], enter=False)
+            return
+
+        # 2) Generic Ctrl-<letter>
+        ctrl = parse_ctrl_key(text)
+        if ctrl is not None:
+            self.pane.send_keys(ctrl, enter=False)
+            return
+
+        # 3) Plain text — use literal=True so tmux doesn't split on
+        #    whitespace or interpret special tokens.
+        self.pane.send_keys(text, enter=False, literal=True)
+        if enter and not text.endswith("\n"):
+            self.pane.send_keys("Enter", enter=False)
 
     def read_screen(self) -> str:
         """Read the current tmux pane content.