cmux-tui: add familiar terminal shortcuts

.github/workflows/cmux-tui.yml

@@ -173,6 +173,10 @@ jobs:
         working-directory: cmux-tui
         run: cargo test --workspace --locked
 
+      - name: crossterm parser tests
+        working-directory: cmux-tui
+        run: cargo test --manifest-path vendor/crossterm/Cargo.toml --lib
+
       - name: TUI smoke test (scripted pty)
         working-directory: cmux-tui
         run: |

Sources/ControlSurfaceResumeTarget.swift

@@ -279,9 +279,12 @@ extension TerminalController {
         content.apply(to: alert, presentingWindow: nil)
 
         switch alert.runModal() {
-        case .alertFirstButtonReturn: .auto
-        case .alertSecondButtonReturn: .prompt
-        default: .manual
+        case .alertFirstButtonReturn:
+            return .auto
+        case .alertSecondButtonReturn:
+            return .prompt
+        default:
+            return .manual
         }
     }
 

Sources/DockSplitStore+RestoredAgentLifecycle.swift

@@ -1,3 +1,4 @@
+import CmuxWorkspaces
 import Foundation
 
 extension DockSplitStore {

Sources/DockSplitStore+SessionSnapshot.swift

@@ -41,11 +41,13 @@ extension DockSplitStore {
                 )
             }
         let persistedPanelIds = Set(panelSnapshots.map(\.id))
-        let sourceWorkspaceIdsByPanelId = Dictionary(uniqueKeysWithValues: panelSnapshots.compactMap {
-            panel in
-            guard let transfer = detachedSurfaceTransfersByPanelId[panel.id] else { return nil }
-            return (panel.id, transfer.sessionRestoreWorkspaceId)
-        })
+        let sourceWorkspaceIdsByPanelId: [UUID: UUID] = Dictionary(
+            uniqueKeysWithValues: panelSnapshots.compactMap {
+                panel in
+                guard let transfer = detachedSurfaceTransfersByPanelId[panel.id] else { return nil }
+                return (panel.id, transfer.sessionRestoreWorkspaceId)
+            }
+        )
         let layout = layoutCodec.pruned(
             rawLayout,
             keeping: persistedPanelIds
@@ -329,7 +331,7 @@ extension DockSplitStore {
         let expectedSessionId = resumeBinding?.isAgentHookBinding == true
             ? resumeBinding?.checkpointId
             : restorableAgent?.sessionId
-        let relevantObservation = observation.flatMap { entry in
+        let relevantObservation: RestorableAgentSessionIndex.Entry? = observation.flatMap { entry in
             guard entry.snapshot.kind == expectedKind, entry.snapshot.sessionId == expectedSessionId else {
                 return nil
             }

cmux-tui/Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "crates/cmux-tui-machine-protocol",
     "crates/cmux-tui",
 ]
+exclude = ["vendor/crossterm"]
 
 [workspace.package]
 edition = "2024"
@@ -54,6 +55,12 @@ fs4 = "1.1.0"
 sha2 = "0.10"
 zeroize = "1.9"
 
+[patch.crates-io]
+# Crossterm 0.29 discards Kitty's shifted key, base-layout key, and associated
+# text while parsing CSI-u input. cmux needs those fields to preserve keyboard
+# layouts across its shortcut layer and nested terminals.
+crossterm = { path = "vendor/crossterm" }
+
 [profile.release]
 lto = "thin"
 

cmux-tui/bindings/conformance/fixtures.json

@@ -309,6 +309,74 @@
         }
       ]
     },
+    {
+      "name": "clear-history-round-trip",
+      "requires": { "commands": ["clear-history"] },
+      "steps": [
+        {
+          "type": "command",
+          "request": { "id": 1, "cmd": "new-workspace", "name": "conf-clear-history", "cols": 80, "rows": 24 },
+          "expect": { "id": 1, "ok": true },
+          "match": "partial",
+          "bind": { "surface0": "data.surface" }
+        },
+        {
+          "type": "command",
+          "request": { "id": 2, "cmd": "clear-history", "surface": "$surface0" },
+          "expect": { "id": 2, "ok": true, "data": {} },
+          "match": "exact"
+        }
+      ]
+    },
+    {
+      "name": "clear-history-key-fallback-round-trip",
+      "requires": {
+        "commands": ["clear-history"],
+        "capabilities": ["clear-history-v1", "clear-history-key-v1"]
+      },
+      "steps": [
+        {
+          "type": "command",
+          "request": { "id": 1, "cmd": "new-workspace", "name": "conf-clear-history-key", "cols": 80, "rows": 24 },
+          "expect": { "id": 1, "ok": true },
+          "match": "partial",
+          "bind": { "surface0": "data.surface" }
+        },
+        {
+          "type": "command",
+          "request": {
+            "id": 2,
+            "cmd": "clear-history",
+            "surface": "$surface0",
+            "fallback_key": {
+              "key": "k",
+              "mods": {
+                "shift": false,
+                "control": false,
+                "alt": false,
+                "super": true,
+                "caps_lock": false,
+                "num_lock": false
+              },
+              "consumed_mods": {
+                "shift": false,
+                "control": false,
+                "alt": false,
+                "super": false,
+                "caps_lock": false,
+                "num_lock": false
+              },
+              "utf8": "",
+              "unshifted_codepoint": "k",
+              "action": "press",
+              "macos_option_as_alt": true
+            }
+          },
+          "expect": { "id": 2, "ok": true, "data": {} },
+          "match": "exact"
+        }
+      ]
+    },
     {
       "name": "overflow-event-schema",
       "steps": [

cmux-tui/bindings/conformance/runner.py

@@ -20,7 +20,13 @@
 
 sys.path.insert(0, str(PYTHON_BINDING))
 
-from cmux import CommandError, CmuxClient, TimeoutError as CmuxTimeoutError  # noqa: E402
+from cmux import (  # noqa: E402
+    CommandError,
+    CmuxClient,
+    TerminalKeyInput,
+    TerminalModifiers,
+    TimeoutError as CmuxTimeoutError,
+)
 from cmux.client import _parse_event  # noqa: E402
 
 
@@ -184,17 +190,25 @@ def execute_command(client: CmuxClient, request: Dict[str, Any]) -> Dict[str, An
 
 def check_requires(fixture: Dict[str, Any], socket_path: str) -> None:
     commands = fixture.get("requires", {}).get("commands", [])
-    if not commands:
+    capabilities = fixture.get("requires", {}).get("capabilities", [])
+    if not commands and not capabilities:
         return
     unsupported: List[str] = []
     with CmuxClient(socket_path=socket_path, timeout=3.0) as client:
+        if capabilities:
+            advertised = set(client.identify().capabilities)
+            unsupported.extend(
+                f"capability:{capability}"
+                for capability in capabilities
+                if capability not in advertised
+            )
         for command in commands:
             response = client.request(command)
             error = str(response.get("error", ""))
             if response.get("ok") is False and "unknown variant" in error:
                 unsupported.append(command)
     if unsupported:
-        raise FixtureSkipped(f"server lacks required command(s): {', '.join(unsupported)}")
+        raise FixtureSkipped(f"server lacks required feature(s): {', '.join(unsupported)}")
 
 
 def dispatch(client: CmuxClient, cmd: str, params: Dict[str, Any]) -> Any:
@@ -208,6 +222,10 @@ def dispatch(client: CmuxClient, cmd: str, params: Dict[str, Any]) -> Any:
         "export-layout": client.export_layout,
         "apply-layout": client.apply_layout,
         "send": lambda **kw: client.send(kw["surface"], text=kw.get("text"), bytes_data=kw.get("bytes")),
+        "clear-history": lambda **kw: client.clear_history(
+            kw["surface"],
+            fallback_key=terminal_key_input(kw.get("fallback_key")),
+        ),
         "read-screen": client.read_screen,
         "vt-state": client.vt_state,
         "new-tab": client.new_tab,
@@ -253,6 +271,20 @@ def dispatch(client: CmuxClient, cmd: str, params: Dict[str, Any]) -> Any:
     return mapping[cmd](**params)
 
 
+def terminal_key_input(value: Any) -> Optional[TerminalKeyInput]:
+    if value is None:
+        return None
+    return TerminalKeyInput(
+        key=value["key"],
+        mods=TerminalModifiers.from_wire(value["mods"]),
+        consumed_mods=TerminalModifiers.from_wire(value["consumed_mods"]),
+        utf8=value["utf8"],
+        unshifted_codepoint=value.get("unshifted_codepoint"),
+        action=value.get("action"),
+        macos_option_as_alt=value["macos_option_as_alt"],
+    )
+
+
 def result_to_data(result: Any) -> Any:
     if dataclasses.is_dataclass(result):
         data = dataclasses.asdict(result)

cmux-tui/bindings/go/README.md

@@ -37,6 +37,9 @@ fmt.Println(screen.Text)
 `NewClient` uses `CMUX_TUI_SOCKET` when set, then legacy `CMUX_MUX_SOCKET`, then
 the default session socket path.
 
+`ClearHistoryWithFallback` accepts a `TerminalKeyInput` and requires the server
+capability `clear-history-key-v1`.
+
 ## E2E
 
 ```bash

cmux-tui/bindings/go/client.go

@@ -284,6 +284,34 @@ func (c *Client) Send(ctx context.Context, surface uint64, opts SendOptions) err
 	return c.request(ctx, "send", params, nil)
 }
 
+func (c *Client) ClearHistory(ctx context.Context, surface uint64) error {
+	if err := c.requireCapability(ctx, "clear-history-v1", "clear-history"); err != nil {
+		return err
+	}
+	return c.request(ctx, "clear-history", map[string]any{"surface": surface}, nil)
+}
+
+func (c *Client) ClearHistoryWithFallback(
+	ctx context.Context,
+	surface uint64,
+	fallbackKey TerminalKeyInput,
+) error {
+	if err := c.requireCapability(ctx, "clear-history-v1", "clear-history"); err != nil {
+		return err
+	}
+	if err := c.requireCapability(
+		ctx,
+		"clear-history-key-v1",
+		"clear-history key fallback",
+	); err != nil {
+		return err
+	}
+	return c.request(ctx, "clear-history", map[string]any{
+		"surface":      surface,
+		"fallback_key": fallbackKey,
+	}, nil)
+}
+
 func (c *Client) ReadScreen(ctx context.Context, surface uint64) (ReadScreenResult, error) {
 	var result ReadScreenResult
 	return result, c.request(ctx, "read-screen", map[string]any{"surface": surface}, &result)

cmux-tui/bindings/go/client_test.go

@@ -196,6 +196,112 @@ func TestSetSplitRatioRejectsServersOlderThanProtocolEight(t *testing.T) {
 	}
 }
 
+func TestClearHistoryRequiresCapability(t *testing.T) {
+	protocol := uint32(9)
+	client := &Client{protocol: &protocol}
+	err := client.ClearHistory(context.Background(), 7)
+	if err == nil || !errors.Is(err, ErrProtocolMismatch) {
+		t.Fatalf("ClearHistory() error = %v, want protocol mismatch", err)
+	}
+}
+
+func TestClearHistorySendsCapabilityGatedWireCommand(t *testing.T) {
+	clientConn, serverConn := net.Pipe()
+	defer serverConn.Close()
+	protocol := uint32(9)
+	client := &Client{
+		timeout:      time.Second,
+		conn:         &jsonLineConn{conn: clientConn, reader: bufio.NewReader(clientConn)},
+		protocol:     &protocol,
+		capabilities: map[string]struct{}{"clear-history-v1": {}},
+	}
+	defer client.Close()
+
+	requests := make(chan map[string]any, 1)
+	go func() {
+		decoder := json.NewDecoder(serverConn)
+		encoder := json.NewEncoder(serverConn)
+		var request map[string]any
+		if decoder.Decode(&request) != nil {
+			return
+		}
+		requests <- request
+		_ = encoder.Encode(map[string]any{"id": request["id"], "ok": true, "data": map[string]any{}})
+	}()
+
+	if err := client.ClearHistory(context.Background(), 7); err != nil {
+		t.Fatalf("ClearHistory() error = %v", err)
+	}
+	request := <-requests
+	if request["cmd"] != "clear-history" || request["surface"] != float64(7) {
+		t.Fatalf("ClearHistory() request = %#v", request)
+	}
+}
+
+func TestClearHistoryFallbackRequiresCapabilityAndPreservesKey(t *testing.T) {
+	protocol := uint32(9)
+	codepoint := "k"
+	action := TerminalKeyPress
+	fallback := TerminalKeyInput{
+		Key:                TerminalKeyK,
+		Mods:               TerminalModifiers{Super: true},
+		UnshiftedCodepoint: &codepoint,
+		Action:             &action,
+		MacOSOptionAsAlt:   true,
+	}
+	client := &Client{
+		protocol:     &protocol,
+		capabilities: map[string]struct{}{"clear-history-v1": {}},
+	}
+	err := client.ClearHistoryWithFallback(context.Background(), 7, fallback)
+	if err == nil || !errors.Is(err, ErrProtocolMismatch) {
+		t.Fatalf("ClearHistoryWithFallback() error = %v, want protocol mismatch", err)
+	}
+
+	clientConn, serverConn := net.Pipe()
+	defer serverConn.Close()
+	client = &Client{
+		timeout:  time.Second,
+		conn:     &jsonLineConn{conn: clientConn, reader: bufio.NewReader(clientConn)},
+		protocol: &protocol,
+		capabilities: map[string]struct{}{
+			"clear-history-v1":     {},
+			"clear-history-key-v1": {},
+		},
+	}
+	defer client.Close()
+
+	requests := make(chan map[string]any, 1)
+	go func() {
+		decoder := json.NewDecoder(serverConn)
+		encoder := json.NewEncoder(serverConn)
+		var request map[string]any
+		if decoder.Decode(&request) != nil {
+			return
+		}
+		requests <- request
+		_ = encoder.Encode(map[string]any{"id": request["id"], "ok": true, "data": map[string]any{}})
+	}()
+
+	if err := client.ClearHistoryWithFallback(context.Background(), 7, fallback); err != nil {
+		t.Fatalf("ClearHistoryWithFallback() error = %v", err)
+	}
+	request := <-requests
+	key, ok := request["fallback_key"].(map[string]any)
+	if !ok {
+		t.Fatalf("fallback_key = %#v", request["fallback_key"])
+	}
+	mods, ok := key["mods"].(map[string]any)
+	if !ok ||
+		key["key"] != "k" ||
+		mods["super"] != true ||
+		key["unshifted_codepoint"] != "k" ||
+		key["action"] != "press" ||
+		key["macos_option_as_alt"] != true {
+		t.Fatalf("ClearHistoryWithFallback() fallback_key = %#v", key)
+	}
+}
+
 func TestSetSplitRatioAcceptsNewerAdditiveProtocols(t *testing.T) {
 	protocol := uint32(9)
 	client := &Client{protocol: &protocol}