diff --git a/server/go/mcp/clean.go b/server/go/mcp/clean.go new file mode 100644 index 0000000..92ca4cf --- /dev/null +++ b/server/go/mcp/clean.go @@ -0,0 +1,320 @@ +package mcp + +import "strings" + +// Terminal output cleaning, ported byte-for-byte from the Win32 server +// (server/2015Remote/McpServer.cpp:3875-4060). The stage order is load-bearing +// — ConPTY is a screen-rendering stream, not a byte stream, so echoed input, +// ANSI repaints and sentinel remnants all interact. clean_test.go locks the +// behaviour against samples captured from the MFC implementation; do not +// "simplify" the matchers. +// +// MFC's CleanTerminalOutput runs: StripAnsi → CRLF normalize → StripEchoedInput +// (which itself ends with StripSentinelText) → TrimRight. We keep that order. + +// stripAnsi drops CSI/OSC and other single-byte ESC sequences so terminal +// colour codes never reach the model. +func stripAnsi(s string) string { + var b strings.Builder + b.Grow(len(s)) + for i := 0; i < len(s); i++ { + if s[i] != 0x1b { + b.WriteByte(s[i]) + continue + } + i++ // swallow ESC + if i < len(s) && s[i] == '[' { // CSI ... ends at @..~ + i++ + for i < len(s) && !(s[i] >= '@' && s[i] <= '~') { + i++ + } + } else if i < len(s) && s[i] == ']' { // OSC ... ends at BEL or ST + i++ + for i < len(s) && s[i] != 0x07 && s[i] != 0x1b { + i++ + } + // ST is the two-byte sequence ESC '\'; consume both. + if i+1 < len(s) && s[i] == 0x1b && s[i+1] == '\\' { + i++ + } + } + // Any other one-byte ESC sequence: the byte after ESC is swallowed by + // the loop increment. + } + return b.String() +} + +// stripEchoedLine removes the first occurrence of line, ignoring CR/LF inside +// the match because ConPTY wraps a long echo at 80 columns. The echoed line's +// trailing newlines are removed with it. +func stripEchoedLine(s, line string) string { + if line == "" || s == "" { + return s + } + for i := 0; i < len(s); i++ { + j, k := 0, i + for j < len(line) && k < len(s) { + c := s[k] + if c == '\r' || c == '\n' { + k++ + continue + } + if c != line[j] { + break + } + j++ + k++ + } + if j != len(line) { + continue + } + for k < len(s) && (s[k] == '\r' || s[k] == '\n') { + k++ + } + return s[:i] + s[k:] + } + return s +} + +// cutThroughEchoedLine deletes everything up to and including the echoed input +// line. ConPTY replays the boot screen and prompt just before our input echo, +// so the echo marks where real output starts. ok=false means the client did +// not echo; the caller then falls back to stripEchoedLine. +func cutThroughEchoedLine(s, line string) (string, bool) { + if line == "" || s == "" { + return s, false + } + for i := 0; i < len(s); i++ { + j, k := 0, i + for j < len(line) && k < len(s) { + c := s[k] + if c == '\r' || c == '\n' { + k++ + continue + } + if c != line[j] { + break + } + j++ + k++ + } + if j != len(line) { + continue + } + for k < len(s) && (s[k] == '\r' || s[k] == '\n') { + k++ + } + return s[k:], true + } + return s, false +} + +// trimLeadingNewlines drops the blank lines left by the boot screen or the +// previous command's trailing newline. +func trimLeadingNewlines(s string) string { + i := 0 + for i < len(s) && (s[i] == '\r' || s[i] == '\n') { + i++ + } + return s[i:] +} + +// stripSentinelText erases sentinel remnants that a ConPTY repaint duplicated +// into the output (e.g. `cmd /c echo abc` renders as "abc__MCP_DONE_x__0"). +// The nonce is random per command, so real output cannot contain the marker; +// matching skips CR/LF (wrapped echoes) and also eats a trailing +// "%errorlevel%" echo template. A preceding "echo " is removed with it. +func stripSentinelText(s, nonce string) string { + if nonce == "" || s == "" { + return s + } + marker := "__MCP_DONE_" + nonce + "__" + i := 0 + for i < len(s) { + j, k := 0, i + for j < len(marker) && k < len(s) { + c := s[k] + if c == '\r' || c == '\n' { + k++ + continue + } + if c != marker[j] { + break + } + j++ + k++ + } + if j != len(marker) { + i++ + continue + } + end := k + if end < len(s) && s[end] == '-' { + end++ + } + for end < len(s) && s[end] >= '0' && s[end] <= '9' { + end++ + } + if end < len(s) && s[end] == '%' { // echoed template ...__%errorlevel% + for end < len(s) && s[end] != '\r' && s[end] != '\n' { + end++ + } + } + begin := i // also remove a stray "echo " left in front of it + if begin >= 5 && strings.EqualFold(s[begin-5:begin], "echo ") { + begin -= 5 + } + s = s[:begin] + s[end:] + i = begin + } + return s +} + +// stripEchoedInput removes the PTY's echo of the command line and sentinel +// line. Non-PTY sessions only remove the sentinel line: the legacy shell +// manager skips the echo by written length, so deleting the command echo could +// eat real output (e.g. `echo echo hello`). +func stripEchoedInput(s string, isPTY bool, cmdLine, sentLine, nonce string) string { + out := s + cut := false + if isPTY { + out, cut = cutThroughEchoedLine(out, cmdLine) + } + if isPTY && !cut { + out = stripEchoedLine(out, cmdLine) + } + out = stripEchoedLine(out, sentLine) + out = stripSentinelText(out, nonce) + return trimLeadingNewlines(out) +} + +// buildSentinelLines builds the command line and sentinel line for one +// platform. PTY platforms send them as two lines so line-swallowing commands +// (rem / cmd / exit / if / for) cannot eat the sentinel; the legacy non-PTY +// path keeps the single-line &&/|| form. +func buildSentinelLines(isPTY, posix bool, command, nonce string) (cmdLine, sentLine string) { + if posix { + return command, "echo __MCP_DONE_" + nonce + "__$?" + } + if !isPTY { + return command + " 2>&1 && echo __MCP_DONE_" + nonce + "__0 || echo __MCP_DONE_" + nonce + "__1", "" + } + return "@echo off & " + command, "echo __MCP_DONE_" + nonce + "__%errorlevel%" +} + +// buildTerminalWire assembles what goes to the shell. POSIX shells print PS1 +// on every read, which would pollute stdout, so it is cleared first; that +// line's echo is cut together with the boot noise. +func buildTerminalWire(posix bool, cmdLine, sentLine string) []byte { + var b strings.Builder + if posix { + b.WriteString("PS1=\r\n") + } + b.WriteString(cmdLine) + b.WriteString("\r\n") + if sentLine != "" { + b.WriteString(sentLine) + b.WriteString("\r\n") + } + return []byte(b.String()) +} + +// containsControlChar reports a byte < 0x20, including CR/LF. A newline would +// split the command into extra lines, only the last of which carries the +// sentinel, so the exit code would be wrong. +func containsControlChar(s string) bool { + for i := 0; i < len(s); i++ { + if s[i] < 0x20 { + return true + } + } + return false +} + +// hasPosixBackgroundAmpersand reports an unquoted, unescaped '&' that is not +// part of &&, &> or >&. A background command's output and exit code cannot be +// attributed to the sentinel, so it is refused. +func hasPosixBackgroundAmpersand(s string) bool { + var inSingle, inDouble, esc bool + for i := 0; i < len(s); i++ { + c := s[i] + if esc { + esc = false + continue + } + if c == '\\' && !inSingle { + esc = true + continue + } + if inSingle { + if c == '\'' { + inSingle = false + } + continue + } + if inDouble { + if c == '"' { + inDouble = false + } + continue + } + if c == '\'' { + inSingle = true + continue + } + if c == '"' { + inDouble = true + continue + } + if c != '&' { + continue + } + if i+1 < len(s) && (s[i+1] == '&' || s[i+1] == '>') { + i++ + continue + } + if i > 0 && s[i-1] == '>' { // 2>&1 / >&2 + continue + } + return true + } + return false +} + +// normalizeCRLF drops the '\r' of every CRLF pair, as MFC does. +func normalizeCRLF(s string) string { + if !strings.Contains(s, "\r\n") { + return s + } + var b strings.Builder + b.Grow(len(s)) + for i := 0; i < len(s); i++ { + if s[i] == '\r' && i+1 < len(s) && s[i+1] == '\n' { + continue + } + b.WriteByte(s[i]) + } + return b.String() +} + +// cleanTerminalOutput is one delivery window's worth of cleaning. first is +// true only for the command-issuing call's first window (echo exists only +// there); trimTrailing stays false for a partial window so the next window's +// first line does not get glued onto this one. +func cleanTerminalOutput(raw []byte, isPTY, first bool, cmdLine, sentLine, nonce string, trimTrailing bool) string { + if len(raw) == 0 { + return "" + } + s := stripAnsi(string(raw)) + s = normalizeCRLF(s) + if first { + s = stripEchoedInput(s, isPTY, cmdLine, sentLine, nonce) + } else { + s = stripSentinelText(s, nonce) + s = trimLeadingNewlines(s) + } + if trimTrailing { + s = strings.TrimRight(s, " \t\r\n") + } + return s +} diff --git a/server/go/mcp/clean_test.go b/server/go/mcp/clean_test.go new file mode 100644 index 0000000..4e16127 --- /dev/null +++ b/server/go/mcp/clean_test.go @@ -0,0 +1,170 @@ +package mcp + +import ( + "strings" + "testing" +) + +func TestStripAnsi(t *testing.T) { + cases := []struct{ in, want string }{ + {"plain", "plain"}, + {"\x1b[31mred\x1b[0m text", "red text"}, + {"a\x1b[?25hb", "ab"}, + {"\x1b]0;title\x07after", "after"}, + {"\x1b]0;title\x1b\\after", "after"}, + {"\x1b]8;;http://x\x07link\x1b]8;;\x07", "link"}, + {"\x1b(Bcharset", "Bcharset"}, // ESC ( is a two-byte sequence; only '(' is swallowed + {"\x1b", ""}, + {"tail\x1b[", "tail"}, + } + for _, tc := range cases { + if got := stripAnsi(tc.in); got != tc.want { + t.Errorf("stripAnsi(%q) = %q, want %q", tc.in, got, tc.want) + } + } +} + +func TestBuildSentinelLines(t *testing.T) { + const cmd, nonce = "echo hi", "ab12cd34" + var cmdLine, sentLine string + + cmdLine, sentLine = buildSentinelLines(true, true, cmd, nonce) + if cmdLine != cmd || sentLine != "echo __MCP_DONE_ab12cd34__$?" { + t.Fatalf("posix: %q / %q", cmdLine, sentLine) + } + wire := string(buildTerminalWire(true, cmdLine, sentLine)) + if want := "PS1=\r\necho hi\r\necho __MCP_DONE_ab12cd34__$?\r\n"; wire != want { + t.Fatalf("posix wire = %q, want %q", wire, want) + } + + cmdLine, sentLine = buildSentinelLines(true, false, cmd, nonce) + if cmdLine != "@echo off & echo hi" || sentLine != "echo __MCP_DONE_ab12cd34__%errorlevel%" { + t.Fatalf("conpty: %q / %q", cmdLine, sentLine) + } + if wire := string(buildTerminalWire(false, cmdLine, sentLine)); !strings.HasPrefix(wire, "@echo off & echo hi\r\necho ") { + t.Fatalf("conpty wire = %q", wire) + } + + cmdLine, sentLine = buildSentinelLines(false, false, cmd, nonce) + if cmdLine != "echo hi 2>&1 && echo __MCP_DONE_ab12cd34__0 || echo __MCP_DONE_ab12cd34__1" || sentLine != "" { + t.Fatalf("legacy: %q / %q", cmdLine, sentLine) + } +} + +// Samples follow the ConPTY repaint behaviour documented in +// McpServer.cpp:3946-3989: the boot prompt and echoed input precede the real +// output, and a repaint can glue the sentinel onto the last output line. +func TestStripEchoedInputWindows(t *testing.T) { + const nonce = "ab12cd34" + cmdLine, sentLine := buildSentinelLines(true, false, "rem hello", nonce) + got := cleanTerminalOutput([]byte( + "\x1b[?25l@echo off & rem hello\r\n\r\n__MCP_DONE_ab12cd34__%errorlevel%\r\n__MCP_DONE_ab12cd34__0\r\n"), + true, true, cmdLine, sentLine, nonce, true) + if got != "" { + t.Fatalf("rem hello output = %q, want empty", got) + } + + cmdLine, sentLine = buildSentinelLines(true, false, "cmd /c echo abc", nonce) + got = cleanTerminalOutput([]byte( + "@echo off & cmd /c echo abc\r\nabc__MCP_DONE_ab12cd34__0\r\n"), + true, true, cmdLine, sentLine, nonce, true) + if got != "abc" { + t.Fatalf("cmd /c echo abc output = %q, want %q", got, "abc") + } + + cmdLine, sentLine = buildSentinelLines(true, false, "type .env", nonce) + got = cleanTerminalOutput([]byte( + "@echo off & type .env\r\nKEY=value\r\nSECOND=line\r\n__MCP_DONE_ab12cd34__1\r\n"), + true, true, cmdLine, sentLine, nonce, true) + if got != "KEY=value\nSECOND=line" { + t.Fatalf("type .env output = %q", got) + } + + // A long command line is wrapped at 80 columns by ConPTY; the echo matcher + // skips the inserted newlines. "cmd /\c" is a literal path, not an escape. + long := "cmd /c " + strings.Repeat("x", 100) + cmdLine, sentLine = buildSentinelLines(true, false, long, nonce) + wrapped := "@echo off & cmd /c " + strings.Repeat("x", 60) + "\r\n" + strings.Repeat("x", 40) + + "\r\nwrapped-ok\r\n__MCP_DONE_ab12cd34__0\r\n" + got = cleanTerminalOutput([]byte(wrapped), true, true, cmdLine, sentLine, nonce, true) + if got != "wrapped-ok" { + t.Fatalf("wrapped echo output = %q, want %q", got, "wrapped-ok") + } +} + +// The legacy non-PTY shell skips the echo by written length, so the command +// echo must not be removed (it could be real output, e.g. `echo echo hello`). +func TestCleanNonPTYKeepsCommandEcho(t *testing.T) { + const nonce = "ab12cd34" + cmdLine, sentLine := buildSentinelLines(false, false, "echo echo hello", nonce) + raw := []byte("echo echo hello\r\nhello\r\n__MCP_DONE_ab12cd34__0\r\n") + got := cleanTerminalOutput(raw, false, true, cmdLine, sentLine, nonce, true) + if got != "echo echo hello\nhello" { + t.Fatalf("non-PTY output = %q", got) + } +} + +func TestCleanTerminalOutputTrimOnlyOnFinalChunk(t *testing.T) { + const nonce = "ab12cd34" + if got := cleanTerminalOutput([]byte("LINE-17\r\n"), true, false, "", "", nonce, false); got != "LINE-17\n" { + t.Fatalf("partial window = %q, want trailing newline kept", got) + } + if got := cleanTerminalOutput([]byte("LINE-17\r\n"), true, false, "", "", nonce, true); got != "LINE-17" { + t.Fatalf("final window = %q, want trimmed", got) + } +} + +func TestStripSentinelTextEchoTemplate(t *testing.T) { + got := stripSentinelText("before\necho __MCP_DONE_ab12cd34__%errorlevel%\nafter\n", "ab12cd34") + // The template line's own newline stays: stripEchoedLine removes the + // echoed sentinel line first in the real pipeline; this is the fallback. + if got != "before\n\nafter\n" { + t.Fatalf("template removal = %q", got) + } + // A negative exit code (%errorlevel% of a crashed process) is removed too. + got = stripSentinelText("out\n__MCP_DONE_ab12cd34__-1073741510\n", "ab12cd34") + if got != "out\n" { + t.Fatalf("negative removal = %q", got) + } +} + +func TestContainsControlChar(t *testing.T) { + for _, s := range []string{"a\nb", "a\rb", "a\tb", "\x01"} { + if !containsControlChar(s) { + t.Errorf("containsControlChar(%q) = false", s) + } + } + for _, s := range []string{"", "echo ok", "中文", "a|b&&c"} { + if containsControlChar(s) { + t.Errorf("containsControlChar(%q) = true", s) + } + } +} + +func TestHasPosixBackgroundAmpersand(t *testing.T) { + cases := []struct { + in string + want bool + }{ + {"sleep 1 &", true}, + {"echo a & echo b", true}, + {"a && b", false}, + {"a &> /dev/null", false}, + {"a 2>&1", false}, + {"echo 'a & b'", false}, + {`echo a\&b`, false}, + {`echo "a & b"`, false}, + {"grep -v '^#' /etc/hosts", false}, + } + for _, tc := range cases { + if got := hasPosixBackgroundAmpersand(tc.in); got != tc.want { + t.Errorf("hasPosixBackgroundAmpersand(%q) = %v, want %v", tc.in, got, tc.want) + } + } +} + +func TestNormalizeCRLF(t *testing.T) { + if got := normalizeCRLF("a\r\nb\rc"); got != "a\nb\rc" { + t.Fatalf("normalizeCRLF = %q", got) + } +} diff --git a/server/go/mcp/server.go b/server/go/mcp/server.go index 4db241e..83caad1 100644 --- a/server/go/mcp/server.go +++ b/server/go/mcp/server.go @@ -109,6 +109,7 @@ func New(cfg Config) *Server { s.sessions = newSessionTable(nil) } s.registerLocalTools() + s.registerTerminalTools() return s } diff --git a/server/go/mcp/session.go b/server/go/mcp/session.go index a14f219..6acc6d8 100644 --- a/server/go/mcp/session.go +++ b/server/go/mcp/session.go @@ -25,6 +25,7 @@ type terminalHub interface { OpenTerminalSession(deviceID string) error CloseTerminalSession(deviceID string) HasTerminalSession(deviceID string) bool + SendToTerminal(deviceID string, data []byte) error } // sessionTable owns the MCP-created terminal sessions, keyed by device. A @@ -119,6 +120,12 @@ func (t *sessionTable) ready(deviceID string, isPTY bool) { // closed runs when the shell ends for any reason — device-side exit, sub-conn // drop, or an explicit teardown. Waiters wake up and deliver whatever output // is already buffered. +// +// A session with a command still in flight stays in the table even after the +// shell is gone: the bytes it produced but nobody has polled yet must remain +// reachable (MFC's closed branch keeps it for the same reason). The entry is +// dropped by forget once the tail is delivered, or by the M4c idle reaper if +// the model never comes back. func (t *sessionTable) closed(deviceID, reason string) { // A web console's teardown can race a fresh open: by the time this event is // delivered, the hub lease may already belong to a new MCP session. The hub @@ -128,25 +135,50 @@ func (t *sessionTable) closed(deviceID, reason string) { return } t.mu.Lock() + defer t.mu.Unlock() sess, ok := t.byDevice[deviceID] if !ok { - t.mu.Unlock() return } sess.mu.Lock() + defer sess.mu.Unlock() if sess.opening { // Our own hub call has not returned yet, so any close for this device // still refers to whoever held the lease before us. - sess.mu.Unlock() - t.mu.Unlock() return } - delete(t.byDevice, deviceID) - t.mu.Unlock() + if !sess.hasUndrainedLocked() { + delete(t.byDevice, deviceID) + } sess.closed = true sess.closeReason = reason sess.cond.Broadcast() - sess.mu.Unlock() +} + +// hasUndrainedLocked reports whether the in-flight command still has output the +// client has not received. An ended shell delivers everything up to total, so a +// running command's undelivered bytes all count. +func (s *termSession) hasUndrainedLocked() bool { + p := s.pending + if p == nil { + return false + } + end := s.total + if p.done { + end = min(p.outputEnd, s.total) + } + return s.delivered < end +} + +// forget removes a session whose shell is already gone. It must not call the +// hub: the device may have reconnected and a new viewer may hold a fresh shell +// by now. +func (t *sessionTable) forget(deviceID string, want *termSession) { + t.mu.Lock() + if t.byDevice[deviceID] == want { + delete(t.byDevice, deviceID) + } + t.mu.Unlock() } // closeSession tears down the MCP-owned session for deviceID, if any. It is @@ -169,11 +201,15 @@ func (t *sessionTable) closeSessionIf(deviceID string, want *termSession) bool { delete(t.byDevice, deviceID) t.mu.Unlock() sess.mu.Lock() + wasClosed := sess.closed sess.closed = true sess.closeReason = "closed" sess.cond.Broadcast() sess.mu.Unlock() - if t.hub != nil { + // A session that was already closed lost its hub lease when the close event + // arrived; the hub may since have handed a fresh shell to another viewer (a + // reconnected device). Only an explicit close of a live session may touch it. + if t.hub != nil && !wasClosed { // Fires OnTerminalClosed, which is a no-op now that the entry is gone. t.hub.CloseTerminalSession(deviceID) } diff --git a/server/go/mcp/session_test.go b/server/go/mcp/session_test.go index 15a26bb..83be532 100644 --- a/server/go/mcp/session_test.go +++ b/server/go/mcp/session_test.go @@ -117,7 +117,7 @@ func TestScanSentinel(t *testing.T) { {"empty", "", 0, false}, } for _, tc := range cases { - code, end, ok := scanSentinel([]byte(tc.in), sentinel) + code, start, end, ok := scanSentinel([]byte(tc.in), sentinel) if ok != tc.ok { t.Errorf("%s: ok = %v, want %v", tc.name, ok, tc.ok) continue @@ -125,11 +125,11 @@ func TestScanSentinel(t *testing.T) { if ok && code != tc.code { t.Errorf("%s: code = %d, want %d", tc.name, code, tc.code) } - if ok && (end <= 0 || end > len(tc.in)) { - t.Errorf("%s: end = %d, want 1..%d", tc.name, end, len(tc.in)) + if ok && (start < 0 || start >= end || end > len(tc.in)) { + t.Errorf("%s: start/end = %d/%d, want 0<=start__" + nonce string // the 6-hex id inside sentinel, for output cleaning + cmdLine string // wire command line, removed from the PTY's echo + sentLine string // wire sentinel line, removed from the PTY's echo start uint64 // absolute offset where this command's output begins scanPos uint64 // absolute offset scanned so far (sentinel may span chunks) - deadline time.Time // when the waiter gives up (the session survives) + deadline time.Time // when the current waiter gives up (the session survives) done bool exitCode int - outputEnd uint64 // absolute offset just past the sentinel's exit code + outputEnd uint64 // absolute offset where the delivered output ends (sentinel start) + lost uint64 // this command's bytes evicted by the ring, cumulative + + // firstChunk is true until the command's first delivery window is cleaned: + // the PTY echoes the input exactly once, at the start. + firstChunk bool + busySince time.Time // when the command started, for the M4c busy reaper } // termSession is the server-side view of one shell child. All mutable state @@ -47,6 +56,7 @@ type termSession struct { isPTY bool ready bool // OnTerminalReady seen + sawOutput bool // shell printed its first screen (prompt); bootstrap done opening bool // hub.OpenTerminalSession still in flight closed bool closeReason string @@ -78,6 +88,7 @@ func (s *termSession) appendLocked(p []byte) { if len(p) == 0 { return } + s.sawOutput = true if len(p) > len(s.buf) { drop := len(p) - len(s.buf) s.droppedBytes += uint64(drop) @@ -137,10 +148,12 @@ func (s *termSession) scanPendingLocked() { return } data, next, _ := s.readLocked(from, int(s.total-from)) - if code, end, ok := scanSentinel(data, p.sentinel); ok { + if code, start, _, ok := scanSentinel(data, p.sentinel); ok { p.done = true p.exitCode = code - p.outputEnd = from + uint64(end) + // Deliver only up to the sentinel itself: the echoed sentinel line and + // the prompt printed after it are not the command's output. + p.outputEnd = from + uint64(start) s.cond.Broadcast() return } @@ -157,23 +170,24 @@ func (s *termSession) scanPendingLocked() { // scanSentinel finds the first occurrence of sentinel followed by a decimal // exit code. The Windows %errorlevel% is signed (0xC000013A prints as -// -1073741510), so a leading '-' is accepted. end is one past the last digit. +// -1073741510), so a leading '-' is accepted. start is where the sentinel +// begins (delivery stops there); end is one past the last digit. // // Echoed command lines contain the sentinel too but not the exit code // ("__MCP_DONE_x__$?" / "__MCP_DONE_x__%errorlevel%"), so occurrences without // digits are skipped rather than reported. -func scanSentinel(data []byte, sentinel string) (code int, end int, ok bool) { +func scanSentinel(data []byte, sentinel string) (code, start, end int, ok bool) { if sentinel == "" { // Defensive: an empty needle matches everywhere and would spin the // device read loop. Callers always mint a non-empty sentinel. - return 0, 0, false + return 0, 0, 0, false } needle := []byte(sentinel) from := 0 for { idx := bytes.Index(data[from:], needle) if idx < 0 { - return 0, 0, false + return 0, 0, 0, false } idx += from rest := data[idx+len(needle):] @@ -187,7 +201,7 @@ func scanSentinel(data []byte, sentinel string) (code int, end int, ok bool) { } if i > digits { if n, err := strconv.Atoi(string(rest[:i])); err == nil { - return n, idx + len(needle) + i, true + return n, idx, idx + len(needle) + i, true } } from = idx + len(needle) diff --git a/server/go/mcp/tools_term.go b/server/go/mcp/tools_term.go new file mode 100644 index 0000000..92e9037 --- /dev/null +++ b/server/go/mcp/tools_term.go @@ -0,0 +1,565 @@ +package mcp + +import ( + "context" + "crypto/rand" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "strings" + "sync/atomic" + "time" + + "github.com/yuanyuanxiang/SimpleRemoter/server/go/hub" + "github.com/yuanyuanxiang/SimpleRemoter/server/go/protocol" +) + +// terminal_exec bounds. They mirror the Win32 server (McpServer.cpp:4669-4674) +// except the per-command buffer, which is the M4a session ring (256 KiB). +const ( + termDefaultTimeoutMS = 20000 + termMaxTimeoutMS = 600000 + termDefaultMaxOutput = 65536 + termMinMaxOutput = 1024 + termMaxMaxOutput = 1 << 20 + // termTruncBackup is how far back a truncated window may move to end on a + // newline: neither UTF-8 nor GBK can hide a '\n' inside a multibyte char, + // so truncating on a line boundary never corrupts the encoding. + termTruncBackup = 4096 + // termBootstrapWait is the longest we wait for a POSIX shell's first + // prompt before writing, so the line discipline does not echo our input + // twice (MFC WaitTerminalBootstrap). + termBootstrapWait = 2 * time.Second +) + +// terminalExecArgs is the published inputSchema as Go. +type terminalExecArgs struct { + ID string `json:"id"` + Command string `json:"command"` + SessionID string `json:"session_id"` + TimeoutMS int `json:"timeout_ms"` + MaxOutputBytes int `json:"max_output_bytes"` +} + +type terminalExecOutput struct { + Stdout string `json:"stdout"` + Done bool `json:"done"` + SessionID string `json:"session_id"` + IsPTY bool `json:"is_pty"` + Reused bool `json:"reused"` + ExitCode *int `json:"exit_code,omitempty"` + Truncated bool `json:"truncated"` + DroppedBytes uint64 `json:"dropped_bytes,omitempty"` + ElapsedMS int64 `json:"elapsed_ms"` +} + +func (s *Server) registerTerminalTools() { + s.handlers["terminal_exec"] = s.callTerminalExec +} + +// callTerminalExec runs one command or polls the output of the previous one. +// +// A call without session_id reuses the device's existing MCP session or opens +// one implicitly, so the model never needs a separate open/close round trip. +// A timeout never destroys the session: the command keeps running on the +// target and the next call with only session_id continues from the delivered +// cursor (design §6.6). +func (s *Server) callTerminalExec(ctx context.Context, raw json.RawMessage) (any, *rpcError) { + if s.cfg.Hub == nil { + return nil, errf(CodeInternal, "server device registry is not configured") + } + var args terminalExecArgs + if rerr := decodeArgs(raw, &args); rerr != nil { + return nil, rerr + } + if args.ID == "" { + return nil, errf(CodeInvalidParams, "Missing required parameter: id") + } + if !isDecimalID(args.ID) { + return nil, errf(CodeInvalidParams, "Invalid id: expected a decimal host id string") + } + + command := strings.TrimSpace(args.Command) + isPoll := command == "" + if isPoll && args.SessionID == "" { + return nil, errf(CodeInvalidParams, + "Missing required parameter: session_id (polling needs the session token)") + } + + // Polling never writes to the target, so a host that went offline can still + // drain the output already buffered for its ended shell. Everything that + // touches the device (platform gates, validation, opening) is command-only. + var posix bool + if !isPoll { + main := s.cfg.Hub.MainConn(args.ID) + if main == nil { + return nil, errf(CodeOffline, "Host not found or offline: %s", args.ID) + } + platform := main.GetInfo().ClientType + posix = platform == "LNX" || platform == "APK" + if platform == "MAC" { + return nil, errf(CodeUnsupported, + "terminal_exec is only supported on Windows, Linux and Android hosts") + } + if platform == "APK" && + !protocol.SupportsCap(s.cfg.Hub.Capability(args.ID), protocol.ClientCapTerminal) { + return nil, errf(CodeUnsupported, + "Android client is too old for terminal_exec: the APK has no COMMAND_SHELL handler, upgrade the client first") + } + // Validate before opening a shell: a rejected command must not reserve + // the device's single terminal slot. + if containsControlChar(command) { + return nil, errf(CodeInvalidParams, + "Command contains a control character (newline/tab); send one line per call") + } + if posix && hasPosixBackgroundAmpersand(command) { + return nil, errf(CodeInvalidParams, + "Background execution (&) breaks output capture; use && to chain commands or run it in a separate session") + } + } + timeout := termTimeout(args.TimeoutMS) + maxOut := termMaxOutput(args.MaxOutputBytes) + started := time.Now() + + sess, reused, rerr := s.terminalSessionFor(args.ID, args.SessionID) + if rerr != nil { + return nil, rerr + } + if !isPoll { + if rerr := s.waitTermReady(ctx, sess, timeout); rerr != nil { + // A shell that ended with undrained output is kept so the next + // session_id poll can still collect its tail; say so, since the + // caller cannot see the session behind an implicit open. + if sess.isClosed() && sess.hasPending() { + return nil, errf(rerr.Code, + "%s. Its output is still buffered; call terminal_exec with only session_id %s to collect it", + rerr.Message, sess.id) + } + // A shell that never came up would otherwise hold the device's single + // terminal slot until an idle sweep; release it now (MFC erases too). + s.sessions.closeSessionIf(args.ID, sess) + return nil, rerr + } + } + sess.mu.Lock() + isPTY := sess.isPTY + sess.mu.Unlock() + if !isPoll && !isPTY { + s.sessions.closeSessionIf(args.ID, sess) + return nil, errf(CodeUnsupported, + "The client on host %s uses the legacy non-PTY shell; this server only supports PTY sessions (ConPTY / POSIX PTY). Upgrade the client", + args.ID) + } + + var p *pendingCmd + if isPoll { + p, rerr = sess.pollPending() + if rerr != nil { + return nil, rerr + } + } else { + nonce := newTermNonce() + cmdLine, sentLine := buildSentinelLines(true, posix, command, nonce) + p, rerr = sess.beginCommand(nonce, cmdLine, sentLine) + if rerr != nil { + return nil, rerr + } + // A first command can race the shell's own startup; writing before the + // prompt appears makes the driver echo the input a second time. + if posix { + s.waitTermBootstrap(ctx, sess, timeout) + } + if !sess.isClosed() { + if err := s.sessions.send(args.ID, buildTerminalWire(posix, cmdLine, sentLine)); err != nil { + sess.abortCommand(p) + return nil, errf(CodeSendFailed, "Failed to send command to host: %v", err) + } + } + } + + out, rerr := s.awaitAndDeliver(ctx, sess, p, maxOut, timeout) + if rerr != nil { + return nil, rerr + } + // An ended shell's session outlives it only until its last bytes are + // delivered (sessionTable.closed keeps it); drop it now without touching the + // hub, which may already belong to a new viewer. + if out.Done && sess.isClosed() && !sess.hasPending() { + s.sessions.forget(args.ID, sess) + } + out.SessionID = sess.id + out.IsPTY = isPTY + out.Reused = reused + out.ElapsedMS = time.Since(started).Milliseconds() + return terminalExecResult(out), nil +} + +// terminalSessionFor resolves the session: an explicit id must match the +// device's MCP session; without one, an existing session is reused, otherwise +// a new shell is opened. +func (s *Server) terminalSessionFor(deviceID, sessionID string) (*termSession, bool, *rpcError) { + if sessionID != "" { + sess := s.sessions.get(deviceID) + if sess == nil { + return nil, true, errf(CodeOffline, + "Terminal session not found: %s (pass a command without session_id to open a new one)", sessionID) + } + if sess.id != sessionID { + return nil, true, errf(CodeOffline, "Terminal session_id mismatch: %s", sessionID) + } + return sess, true, nil + } + if sess := s.sessions.get(deviceID); sess != nil { + return sess, true, nil + } + sess, err := s.sessions.open(deviceID) + if err == nil { + return sess, false, nil + } + switch { + case errors.Is(err, hub.ErrTerminalBusy): + return nil, false, errf(CodeBusy, + "Device busy: the terminal for host %s is held by another viewer (web console or another MCP call); close it first", deviceID) + case errors.Is(err, hub.ErrDeviceOffline): + return nil, false, errf(CodeOffline, "Host not found or offline: %s", deviceID) + case errors.Is(err, errNoDeviceHub): + return nil, false, errf(CodeInternal, "server device registry is not configured") + case errors.Is(err, errSessionClosed): + return nil, false, errf(CodeBusy, + "Device busy: the terminal session for host %s closed while opening; retry", deviceID) + default: + return nil, false, errf(CodeSendFailed, "Failed to open terminal on host: %v", err) + } +} + +// waitTermReady waits for OnTerminalReady. Failing here means no shell exists to +// command, so the caller releases the slot. +func (s *Server) waitTermReady(ctx context.Context, sess *termSession, timeout time.Duration) *rpcError { + deadline := time.Now().Add(timeout) + stop := wakeOn(ctx, sess, deadline) + defer stop() + + sess.mu.Lock() + defer sess.mu.Unlock() + for !sess.ready && !sess.closed && ctx.Err() == nil && time.Now().Before(deadline) { + sess.cond.Wait() + } + if sess.ready && !sess.closed { + return nil + } + if sess.closed { + reason := sess.closeReason + if reason == "" { + reason = "closed" + } + return errf(CodeOffline, "Terminal session ended while starting: %s", reason) + } + if ctx.Err() != nil { + return errf(CodeTimeout, "Request cancelled while waiting for the shell to start") + } + return errf(CodeTimeout, + "Timeout waiting for shell to start (the client may not support remote shell, or the host is unresponsive)") +} + +// waitTermBootstrap waits for the shell's first screen so the input is echoed +// once, not twice. The wait is bounded by the call's own timeout as well as the +// bootstrap cap (MFC uses min(timeoutMs, 2000)); a timeout is not an error: the +// command is still written. +func (s *Server) waitTermBootstrap(ctx context.Context, sess *termSession, timeout time.Duration) { + deadline := time.Now().Add(min(timeout, termBootstrapWait)) + stop := wakeOn(ctx, sess, deadline) + defer stop() + + sess.mu.Lock() + defer sess.mu.Unlock() + for !sess.sawOutput && !sess.closed && ctx.Err() == nil && time.Now().Before(deadline) { + sess.cond.Wait() + } +} + +// awaitAndDeliver waits for the command to finish (or the call's deadline) and +// returns the next window of output. The session survives either outcome; only +// its delivered cursor moves. +func (s *Server) awaitAndDeliver(ctx context.Context, sess *termSession, p *pendingCmd, + maxOut int, timeout time.Duration) (terminalExecOutput, *rpcError) { + deadline := time.Now().Add(timeout) + sess.mu.Lock() + p.deadline = deadline + sess.mu.Unlock() + + stop := wakeOn(ctx, sess, deadline) + defer stop() + + sess.mu.Lock() + defer sess.mu.Unlock() + for !p.done && !sess.closed && ctx.Err() == nil && time.Now().Before(deadline) { + sess.cond.Wait() + } + if ctx.Err() != nil { + // The HTTP client is gone; the command keeps running (design §6.6). + return terminalExecOutput{}, errf(CodeTimeout, + "Request cancelled; the command is still running, poll with session_id to collect its output") + } + + var out terminalExecOutput + out.Done = p.done || sess.closed + if p.done && !sess.closed { + code := p.exitCode + out.ExitCode = &code + } else if out.Done { + code := -1 // shell exited or was closed: the real code is unknown + out.ExitCode = &code + } + + base := sess.baseLocked() + if base > sess.delivered { + // The ring evicted bytes this command produced but never delivered. + p.lost += base - sess.delivered + sess.delivered = base + } + end := sess.total + if p.done { + end = min(p.outputEnd, sess.total) + } + if sess.delivered > end { + sess.delivered = end + } + + window, truncated := readDeliveryWindow(sess, sess.delivered, end, maxOut) + sess.delivered += uint64(len(window)) + sess.lastUsed = time.Now() + + finalChunk := out.Done && !truncated + out.Stdout = cleanTerminalOutput(window, sess.isPTY, p.firstChunk, + p.cmdLine, p.sentLine, p.nonce, finalChunk) + // The PTY echoes the input exactly once, so the flag may only fall after a + // window actually carried bytes: a call that timed out before the echo + // arrived must not leave the echo for the next poll to print. + if len(window) > 0 { + p.firstChunk = false + } + out.Truncated = truncated + out.DroppedBytes = p.lost + + // The identity check matters when a command was started after the previous + // one finished but before this call could collect its last window: that + // waiter must not clear the new command's pending entry. + if out.Done && sess.delivered >= end && sess.pending == p { + // Fully delivered: the session is idle again. Keeping the pending entry + // would make the next command answer "busy" forever. + sess.pending = nil + sess.cond.Broadcast() + } + return out, nil +} + +// readDeliveryWindow returns the next window of raw output starting at from, +// bounded by maxOut and, when truncated, backed up to the last newline within +// termTruncBackup bytes. It never returns bytes past end (the sentinel start +// when the command finished). +func readDeliveryWindow(sess *termSession, from, end uint64, maxOut int) ([]byte, bool) { + if from >= end { + return nil, false + } + want := end - from + n := int(min(want, uint64(maxOut))) + window, _, _ := sess.readLocked(from, n) + truncated := want > uint64(n) + if truncated { + floor := 0 + if len(window) > termTruncBackup { + floor = len(window) - termTruncBackup + } + for i := len(window); i > floor; i-- { + if window[i-1] == '\n' { + window = window[:i] + break + } + } + } + return window, truncated +} + +// ----- session state machine ------------------------------------------------ + +// beginCommand marks the session busy with a new command. The output cursor +// starts at the current end of the stream, so earlier prompt/output bytes are +// never delivered as this command's result. +func (s *termSession) beginCommand(nonce, cmdLine, sentLine string) (*pendingCmd, *rpcError) { + s.mu.Lock() + defer s.mu.Unlock() + if s.closed { + return nil, errf(CodeOffline, "Terminal session ended: %s", s.closeReason) + } + if !s.ready { + return nil, errf(CodeOffline, "Terminal session is not ready yet: %s", s.id) + } + if s.pending != nil { + if !s.pending.done { + return nil, errf(CodeBusy, "Device busy: another terminal_exec is already running for this session") + } + end := min(s.pending.outputEnd, s.total) + if s.delivered < end { + return nil, errf(CodeBusy, + "Device busy: the previous command finished but its output is not fully drained; call terminal_exec with only session_id to collect the rest first") + } + // The finished command has no bytes left to collect (a waiter timed out + // after the sentinel was seen). Start the new command instead of making + // the caller poll for nothing; a stale waiter still holding the old + // pointer is fenced by the identity check in awaitAndDeliver. + s.pending = nil + } + now := time.Now() + p := &pendingCmd{ + sentinel: "__MCP_DONE_" + nonce + "__", + nonce: nonce, + cmdLine: cmdLine, + sentLine: sentLine, + start: s.total, + scanPos: s.total, + busySince: now, + firstChunk: true, + } + s.pending = p + s.delivered = s.total + s.lastUsed = now + s.cond.Broadcast() + return p, nil +} + +// pollPending returns the command already in flight, including the tail of one +// whose shell has ended (the session stays reachable until the bytes are +// delivered). Polling an idle session is a caller mistake: it would otherwise +// wait out the whole timeout. +func (s *termSession) pollPending() (*pendingCmd, *rpcError) { + s.mu.Lock() + defer s.mu.Unlock() + if s.pending == nil { + if s.closed { + return nil, errf(CodeOffline, "Terminal session ended: %s", s.closeReason) + } + return nil, errf(CodeOffline, + "Terminal session is idle: no command is running; pass command to execute one") + } + return s.pending, nil +} + +// hasPending reports whether a command still owns the session. Its output may +// be undrained even when the shell has already ended. +func (s *termSession) hasPending() bool { + s.mu.Lock() + defer s.mu.Unlock() + return s.pending != nil +} + +// abortCommand clears a command whose bytes could not be written, so the +// session does not stay busy for a command that never existed. +func (s *termSession) abortCommand(p *pendingCmd) { + s.mu.Lock() + defer s.mu.Unlock() + if s.pending == p { + s.pending = nil + s.cond.Broadcast() + } +} + +func (t *sessionTable) send(deviceID string, data []byte) error { + if t.hub == nil { + return errNoDeviceHub + } + return t.hub.SendToTerminal(deviceID, data) +} + +// isClosed reports the session's terminal state. Its fields are immutable +// once set, so this is race-free with the lock held briefly. +func (s *termSession) isClosed() bool { + s.mu.Lock() + defer s.mu.Unlock() + return s.closed +} + +// wakeOn broadcasts on the session's condition when ctx ends, the deadline +// passes, or the returned stop function is called. sync.Cond has no timeout or +// cancellation, so every waiter pairs it with this helper. +func wakeOn(ctx context.Context, sess *termSession, deadline time.Time) func() { + timer := time.NewTimer(time.Until(deadline)) + done := make(chan struct{}) + go func() { + select { + case <-ctx.Done(): + case <-timer.C: + case <-done: + } + sess.mu.Lock() + sess.cond.Broadcast() + sess.mu.Unlock() + }() + return func() { + timer.Stop() + close(done) + } +} + +// terminalExecResult wraps the output in the MCP result shape. The text item +// carries stdout; a second compact-JSON item carries the status fields so a +// client that only reads content still sees done/exit_code/truncated. +func terminalExecResult(out terminalExecOutput) toolResult { + text := out.Stdout + if text == "" { + if out.Done { + text = "(无输出)" + } else { + text = "(暂无新输出,命令仍在运行,继续轮询)" + } + } + status := map[string]any{ + "done": out.Done, + "session_id": out.SessionID, + "truncated": out.Truncated, + } + if out.ExitCode != nil { + status["exit_code"] = *out.ExitCode + } + if out.DroppedBytes > 0 { + status["dropped_bytes"] = out.DroppedBytes + } + statusJSON, err := json.Marshal(status) + if err != nil { + statusJSON = []byte("{}") + } + return toolResult{ + Content: []contentItem{ + {Type: "text", Text: text}, + {Type: "text", Text: string(statusJSON)}, + }, + StructuredContent: out, + IsError: false, + } +} + +func termTimeout(ms int) time.Duration { + if ms <= 0 || ms > termMaxTimeoutMS { + ms = termDefaultTimeoutMS + } + return time.Duration(ms) * time.Millisecond +} + +func termMaxOutput(n int) int { + if n < termMinMaxOutput || n > termMaxMaxOutput { + return termDefaultMaxOutput + } + return n +} + +// termNonceFallback numbers nonces when crypto/rand is unavailable. The nonce +// only has to be unique enough that output cannot contain the marker. +var termNonceFallback atomic.Uint32 + +func newTermNonce() string { + var b [4]byte + if _, err := rand.Read(b[:]); err == nil { + return hex.EncodeToString(b[:]) + } + return fmt.Sprintf("%08x", termNonceFallback.Add(1)) +} diff --git a/server/go/mcp/tools_term_test.go b/server/go/mcp/tools_term_test.go new file mode 100644 index 0000000..b7e3f4b --- /dev/null +++ b/server/go/mcp/tools_term_test.go @@ -0,0 +1,559 @@ +package mcp + +import ( + "context" + "encoding/json" + "fmt" + "net" + "strings" + "testing" + "time" + + "github.com/yuanyuanxiang/SimpleRemoter/server/go/connection" + "github.com/yuanyuanxiang/SimpleRemoter/server/go/hub" + "github.com/yuanyuanxiang/SimpleRemoter/server/go/protocol" +) + +// termRig is a live MCP server plus a hub whose device's shell answers every +// open request immediately. Tests drive the shell by feeding OnTerminalData +// packets, i.e. exactly what cmd/main.go delivers from the TCP read loop. +type termRig struct { + t *testing.T + s *Server + h *hub.Hub + main *connection.Context + sub *connection.Context + writes chan []byte + opened chan struct{} + stop chan struct{} +} + +func newTermRig(t *testing.T, clientType, capability string, isPTY bool) *termRig { + t.Helper() + h := hub.New() + main := &connection.Context{RemoteAddr: "10.0.0.1:4000"} + main.Info.ClientType = clientType + // The hub closes the shell sub-conn 500 ms after teardown; a real net.Conn + // keeps that path from dereferencing nil. + shellConn, peer := net.Pipe() + t.Cleanup(func() { _ = shellConn.Close(); _ = peer.Close() }) + sub := &connection.Context{RemoteAddr: "10.0.0.1:4001", Conn: shellConn} + rig := &termRig{ + t: t, h: h, main: main, sub: sub, + writes: make(chan []byte, 64), + opened: make(chan struct{}, 4), + stop: make(chan struct{}), + } + h.SetSender(func(ctx *connection.Context, data []byte) error { + switch ctx { + case main: + if len(data) == 1 && data[0] == protocol.CommandShell { + select { + case rig.opened <- struct{}{}: + default: + } + } + case sub: + select { + case rig.writes <- append([]byte(nil), data...): + default: + } + } + return nil + }) + h.Register(&hub.Device{ID: "1001", PeerIP: "10.0.0.1", Capability: capability}, main) + rig.s = New(Config{Token: testToken, Hub: h}) + t.Cleanup(func() { close(rig.stop) }) + // Subscribe like cmd/main.go does, so OnTerminalReady/Data/Closed flow. + unsub := h.Subscribe(rig.s) + t.Cleanup(unsub) + t.Cleanup(rig.s.Close) + + // The device answers COMMAND_SHELL by opening a shell sub-connection. + go func() { + select { + case <-rig.opened: + h.BindTerminalConn("1001", sub, isPTY) + case <-rig.stop: + } + }() + return rig +} + +type termCall struct { + out terminalExecOutput + err *rpcError +} + +func (r *termRig) callAsync(args string) <-chan termCall { + ch := make(chan termCall, 1) + go func() { + res, rerr := r.s.callTerminalExec(context.Background(), json.RawMessage(args)) + if rerr != nil { + ch <- termCall{err: rerr} + return + } + tr, ok := res.(toolResult) + if !ok { + ch <- termCall{err: errf(CodeInternal, "unexpected result type %T", res)} + return + } + out, ok := tr.StructuredContent.(terminalExecOutput) + if !ok { + ch <- termCall{err: errf(CodeInternal, "unexpected structured content %T", tr.StructuredContent)} + return + } + ch <- termCall{out: out} + }() + return ch +} + +func (r *termRig) wait(ch <-chan termCall) termCall { + r.t.Helper() + select { + case c := <-ch: + return c + case <-time.After(5 * time.Second): + r.t.Fatal("timed out waiting for the tool call") + return termCall{} + } +} + +// nextCommandWire returns the next write to the shell that carries a sentinel +// and the nonce embedded in it. +func (r *termRig) nextCommandWire() (wire, nonce string) { + r.t.Helper() + deadline := time.After(5 * time.Second) + for { + select { + case b := <-r.writes: + s := string(b) + i := strings.Index(s, "__MCP_DONE_") + if i < 0 { + continue + } + rest := s[i+len("__MCP_DONE_"):] + j := strings.Index(rest, "__") + if j <= 0 { + continue + } + return s, rest[:j] + case <-deadline: + r.t.Fatal("timed out waiting for the command wire") + return "", "" + } + } +} + +func (r *termRig) feed(text string) { + r.s.OnTerminalData("1001", termPacket(text)) +} + +func TestTerminalExecRunsCommand(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"echo hello","timeout_ms":5000}`) + wire, nonce := rig.nextCommandWire() + if !strings.HasPrefix(wire, "@echo off & echo hello\r\necho __MCP_DONE_"+nonce+"__%errorlevel%\r\n") { + t.Fatalf("wire = %q", wire) + } + + // ConPTY: the first line is the echoed command; the real output follows. + rig.feed("@echo off & echo hello\r\nhello\r\n__MCP_DONE_" + nonce + "__0\r\n") + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("call failed: %v", res.err) + } + out := res.out + if out.Stdout != "hello" || !out.Done || out.ExitCode == nil || *out.ExitCode != 0 { + t.Fatalf("out = %+v", out) + } + if !out.IsPTY || out.Reused || out.Truncated || out.DroppedBytes != 0 { + t.Fatalf("flags = %+v", out) + } + if !strings.HasPrefix(out.SessionID, "s-") { + t.Fatalf("session id = %q", out.SessionID) + } + if out.ElapsedMS < 0 { + t.Fatalf("elapsed = %d", out.ElapsedMS) + } +} + +func TestTerminalExecTimeoutThenPoll(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":100}`) + _, nonce := rig.nextCommandWire() + + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("first call: %v", res.err) + } + if res.out.Done || res.out.Stdout != "" { + t.Fatalf("timeout result = %+v", res.out) + } + sid := res.out.SessionID + + rig.feed("part1\r\n") + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":100}`, sid)) + res = rig.wait(ch) + if res.err != nil { + t.Fatalf("poll 1: %v", res.err) + } + if res.out.Done || res.out.Stdout != "part1\n" { + t.Fatalf("poll 1 = %+v", res.out) + } + if res.out.SessionID != sid { + t.Fatalf("poll 1 session id = %q, want %q", res.out.SessionID, sid) + } + + rig.feed("part2\r\n__MCP_DONE_" + nonce + "__3\r\n") + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":1000}`, sid)) + res = rig.wait(ch) + if res.err != nil { + t.Fatalf("poll 2: %v", res.err) + } + if !res.out.Done || res.out.Stdout != "part2" || res.out.ExitCode == nil || *res.out.ExitCode != 3 { + t.Fatalf("poll 2 = %+v", res.out) + } + + // The command is drained; polling an idle session is a caller mistake. + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":100}`, sid)) + res = rig.wait(ch) + if res.err == nil || res.err.Code != CodeOffline || !strings.Contains(res.err.Message, "idle") { + t.Fatalf("idle poll = %+v", res.err) + } +} + +func TestTerminalExecBusyWhileRunning(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":50}`) + _, nonce := rig.nextCommandWire() + if res := rig.wait(ch); res.err != nil || res.out.Done { + t.Fatalf("first call = %+v / %v", res.out, res.err) + } + + ch = rig.callAsync(`{"id":"1001","command":"echo again","timeout_ms":100}`) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeBusy { + t.Fatalf("busy call = %+v", res.err) + } + + // Finish the first command so cleanup does not tear down a running shell. + rig.feed("__MCP_DONE_" + nonce + "__0\r\n") +} + +func TestTerminalExecRejectsNonPTY(t *testing.T) { + rig := newTermRig(t, "", "", false) + ch := rig.callAsync(`{"id":"1001","command":"echo hi","timeout_ms":1000}`) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeUnsupported || !strings.Contains(res.err.Message, "PTY") { + t.Fatalf("non-PTY = %+v", res.err) + } + if rig.s.sessions.get("1001") != nil { + t.Fatal("rejected session still in the table") + } + if rig.h.HasTerminalSession("1001") { + t.Fatal("rejected session still holds the hub lease") + } +} + +func TestTerminalExecUnknownSession(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","session_id":"s-abcdef","timeout_ms":100}`) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeOffline || !strings.Contains(res.err.Message, "not found") { + t.Fatalf("unknown session = %+v", res.err) + } +} + +func TestTerminalExecRejectsBadArgs(t *testing.T) { + rig := newTermRig(t, "", "", true) + cases := []string{ + `{"id":"1001","timeout_ms":100}`, // poll without session_id + `{"id":"1001","command":"a\nb","timeout_ms":100}`, // control char + `{"command":"echo hi","timeout_ms":100}`, // missing id + `{"id":"abc","command":"echo hi","timeout_ms":100}`, // id not decimal + } + for _, args := range cases { + ch := rig.callAsync(args) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeInvalidParams { + t.Fatalf("%s: %+v", args, res.err) + } + } + select { + case b := <-rig.writes: + t.Fatalf("rejected command was written to the shell: %q", b) + default: + } +} + +func TestTerminalExecAPKCapabilityGate(t *testing.T) { + rig := newTermRig(t, "APK", "0400", true) // no CLIENT_CAP_TERMINAL (0x8000) + ch := rig.callAsync(`{"id":"1001","command":"echo hi","timeout_ms":100}`) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeUnsupported || !strings.Contains(res.err.Message, "too old") { + t.Fatalf("APK gate = %+v", res.err) + } +} + +func TestTerminalExecAPKWithTerminalCap(t *testing.T) { + rig := newTermRig(t, "APK", "8400", true) // 0x8000 | 0x0400 + ch := rig.callAsync(`{"id":"1001","command":"echo hi","timeout_ms":5000}`) + wire, nonce := rig.nextCommandWire() + // POSIX PTY: PS1 is cleared first and the sentinel uses $?. + if !strings.HasPrefix(wire, "PS1=\r\necho hi\r\necho __MCP_DONE_"+nonce+"__$?\r\n") { + t.Fatalf("POSIX wire = %q", wire) + } + rig.feed("PS1=\r\necho hi\r\nhi\r\n__MCP_DONE_" + nonce + "__0\r\n") + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("APK exec: %v", res.err) + } + if res.out.Stdout != "hi" || !res.out.Done { + t.Fatalf("APK out = %+v", res.out) + } +} + +func TestTerminalExecMACRejected(t *testing.T) { + rig := newTermRig(t, "MAC", "", true) + ch := rig.callAsync(`{"id":"1001","command":"echo hi","timeout_ms":100}`) + res := rig.wait(ch) + if res.err == nil || res.err.Code != CodeUnsupported { + t.Fatalf("MAC = %+v", res.err) + } +} + +func TestTerminalExecTruncatesOnLineBoundary(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"dump","timeout_ms":5000,"max_output_bytes":1024}`) + _, nonce := rig.nextCommandWire() + + var payload strings.Builder + for i := 0; i < 300; i++ { + fmt.Fprintf(&payload, "line-%03d-xxxxxxxxxxxxxx\r\n", i) + } + payload.WriteString("__MCP_DONE_" + nonce + "__0\r\n") + rig.feed(payload.String()) + + var got strings.Builder + const wantLines = 300 + for i := 0; i < 100; i++ { + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("window %d: %v", i, res.err) + } + got.WriteString(res.out.Stdout) + if res.out.ExitCode == nil || *res.out.ExitCode != 0 { + t.Fatalf("window %d exit = %+v", i, res.out) + } + if !res.out.Done { + t.Fatalf("window %d: command should already be done", i) + } + if !res.out.Truncated { + break + } + if len(res.out.Stdout) > 1024 { + t.Fatalf("window %d exceeded max_output_bytes: %d", i, len(res.out.Stdout)) + } + ch = rig.callAsync(fmt.Sprintf( + `{"id":"1001","session_id":%q,"timeout_ms":5000,"max_output_bytes":1024}`, res.out.SessionID)) + } + + lines := strings.Split(strings.TrimRight(got.String(), "\n"), "\n") + if len(lines) != wantLines { + t.Fatalf("got %d lines, want %d", len(lines), wantLines) + } + for i, line := range lines { + if want := fmt.Sprintf("line-%03d-xxxxxxxxxxxxxx", i); line != want { + t.Fatalf("line %d = %q, want %q", i, line, want) + } + } +} + +// A shell that dies mid-command keeps its undelivered output in the session: +// the device is offline, but the next poll must still collect the tail. +func TestTerminalExecDrainsAfterClose(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":50}`) + _, _ = rig.nextCommandWire() + first := rig.wait(ch) + if first.err != nil || first.out.Done { + t.Fatalf("first call = %+v / %v", first.out, first.err) + } + sid := first.out.SessionID + + rig.feed("partial output\r\n") + // The device goes away: the hub releases the shell, then the main conn. + rig.h.CloseTerminalSession("1001") + rig.h.Unregister("1001") + + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":1000}`, sid)) + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("drain poll: %v", res.err) + } + if res.out.Stdout != "partial output" || !res.out.Done { + t.Fatalf("drain = %+v", res.out) + } + if res.out.ExitCode == nil || *res.out.ExitCode != -1 { + t.Fatalf("closed exit code = %+v", res.out.ExitCode) + } + if res.out.SessionID != sid { + t.Fatalf("session id = %q, want %q", res.out.SessionID, sid) + } + + // Fully delivered: the ended session is released, so the offline host now + // reports it as gone instead of serving it forever. + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":100}`, sid)) + res = rig.wait(ch) + if res.err == nil || res.err.Code != CodeOffline || !strings.Contains(res.err.Message, "not found") { + t.Fatalf("post-drain poll = %+v", res.err) + } +} + +// Closing with more than max_output_bytes buffered must still deliver every +// line across polls, even though the shell is gone after the first window. +func TestTerminalExecCloseKeepsTruncatedTail(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"dump","timeout_ms":50}`) + _, _ = rig.nextCommandWire() + first := rig.wait(ch) + if first.err != nil || first.out.Done { + t.Fatalf("first call = %+v / %v", first.out, first.err) + } + sid := first.out.SessionID + + var payload strings.Builder + for i := 0; i < 100; i++ { + fmt.Fprintf(&payload, "line-%03d-xxxxxxxx\r\n", i) + } + rig.feed(payload.String()) + rig.h.CloseTerminalSession("1001") + + var got strings.Builder + ch = rig.callAsync(fmt.Sprintf( + `{"id":"1001","session_id":%q,"timeout_ms":1000,"max_output_bytes":1024}`, sid)) + for i := 0; i < 20; i++ { + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("window %d: %v", i, res.err) + } + got.WriteString(res.out.Stdout) + if !res.out.Done { + t.Fatalf("window %d should be done: %+v", i, res.out) + } + if res.out.ExitCode == nil || *res.out.ExitCode != -1 { + t.Fatalf("window %d exit = %+v", i, res.out.ExitCode) + } + if !res.out.Truncated { + break + } + ch = rig.callAsync(fmt.Sprintf( + `{"id":"1001","session_id":%q,"timeout_ms":1000,"max_output_bytes":1024}`, sid)) + } + lines := strings.Split(strings.TrimRight(got.String(), "\n"), "\n") + if len(lines) != 100 { + t.Fatalf("got %d lines, want 100", len(lines)) + } + for i, line := range lines { + if want := fmt.Sprintf("line-%03d-xxxxxxxx", i); line != want { + t.Fatalf("line %d = %q, want %q", i, line, want) + } + } +} + +// The PTY echo can arrive after the command call timed out. The poll must still +// recognise it as the echo and not print the command line as output. +func TestTerminalExecPollStripsLateEcho(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"echo hello","timeout_ms":50}`) + _, nonce := rig.nextCommandWire() + first := rig.wait(ch) + if first.err != nil || first.out.Done || first.out.Stdout != "" { + t.Fatalf("first = %+v / %v", first.out, first.err) + } + + rig.feed("@echo off & echo hello\r\nhello\r\n__MCP_DONE_" + nonce + "__0\r\n") + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":1000}`, first.out.SessionID)) + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("poll: %v", res.err) + } + if res.out.Stdout != "hello" || !res.out.Done { + t.Fatalf("poll = %+v, want the echo removed", res.out) + } +} + +// A finished command with nothing left to collect must not answer "busy": its +// stale pending entry is dropped and the new command runs. +func TestTerminalExecCommandAfterDrainedFinish(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"slow","timeout_ms":50}`) + _, nonce := rig.nextCommandWire() + rig.feed("early\r\n") + first := rig.wait(ch) + if first.err != nil || first.out.Done || first.out.Stdout != "early\n" { + t.Fatalf("first = %+v / %v", first.out, first.err) + } + + // The sentinel arrives after the call returned; everything it ends was + // already delivered, so the session is effectively idle. + rig.feed("__MCP_DONE_" + nonce + "__0\r\n") + + ch = rig.callAsync(`{"id":"1001","command":"echo next","timeout_ms":5000}`) + _, nonce2 := rig.nextCommandWire() + rig.feed("next-out\r\n__MCP_DONE_" + nonce2 + "__0\r\n") + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("next command: %v", res.err) + } + if res.out.Stdout != "next-out" || !res.out.Done { + t.Fatalf("next command = %+v", res.out) + } +} + +// A command naming a session that already ended must not destroy the tail it +// still holds; the caller is told to poll instead. +func TestTerminalExecEndedSessionAsksForPoll(t *testing.T) { + rig := newTermRig(t, "", "", true) + ch := rig.callAsync(`{"id":"1001","command":"ping -n 30 127.0.0.1","timeout_ms":50}`) + _, _ = rig.nextCommandWire() + first := rig.wait(ch) + if first.err != nil || first.out.Done { + t.Fatalf("first = %+v / %v", first.out, first.err) + } + sid := first.out.SessionID + + rig.feed("tail\r\n") + rig.h.CloseTerminalSession("1001") + ch = rig.callAsync(fmt.Sprintf( + `{"id":"1001","session_id":%q,"command":"echo again","timeout_ms":200}`, sid)) + if res := rig.wait(ch); res.err == nil || + !strings.Contains(res.err.Message, sid) || !strings.Contains(res.err.Message, "session_id") { + t.Fatalf("command on an ended session = %+v, want a pointer to drain it by id", res.err) + } + + ch = rig.callAsync(fmt.Sprintf(`{"id":"1001","session_id":%q,"timeout_ms":1000}`, sid)) + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("drain after ended command: %v", res.err) + } + if res.out.Stdout != "tail" || !res.out.Done { + t.Fatalf("drain = %+v", res.out) + } +} + +// The POSIX bootstrap wait is capped by the call's own timeout, not always 2 s. +func TestTerminalExecBootstrapHonoursCallTimeout(t *testing.T) { + rig := newTermRig(t, "APK", "8400", true) // POSIX: the bootstrap wait applies + start := time.Now() + ch := rig.callAsync(`{"id":"1001","command":"echo hi","timeout_ms":300}`) + _, _ = rig.nextCommandWire() + res := rig.wait(ch) + if res.err != nil { + t.Fatalf("call: %v", res.err) + } + if elapsed := time.Since(start); elapsed > 1500*time.Millisecond { + t.Fatalf("bootstrap ignored the call timeout: %v", elapsed) + } +} diff --git a/server/go/protocol/commands.go b/server/go/protocol/commands.go index 8960c2b..b8fec62 100644 --- a/server/go/protocol/commands.go +++ b/server/go/protocol/commands.go @@ -76,6 +76,10 @@ const ( ClientCapVirtualDesktop uint32 = 0x0080 // CLIENT_CAP_VIRTUAL_DESKTOP — whole virtual desktop capture ClientCapWindowInfo uint32 = 0x0100 // CLIENT_CAP_WINDOW_INFO — window enumeration / rects ClientCapScreenRegion uint32 = 0x0200 // CLIENT_CAP_SCREEN_REGION — region/window/monitor capture + // CLIENT_CAP_TERMINAL is only declared by recent Android builds: Windows + // and Linux always had COMMAND_SHELL but never advertise it, so this bit + // must only gate the APK path (common/commands.h:151). + ClientCapTerminal uint32 = 0x8000 // CLIENT_CAP_TERMINAL — PTY shell sub-connection ) // SupportsCap returns true when the client's reported capability hex string