Feature(Go): terminal_exec with sentinel cleaning and polling

Implement M4b of the Go MCP minimal plan: terminal_exec runs one command in a
device's persistent shell and polls the rest of a timed-out command.

Wire format follows the Win32 server: ConPTY sends "@echo off & <cmd>" plus a
sentinel line carrying %errorlevel%; POSIX PTY clears PS1 and uses $?. Output
cleaning is a byte-faithful port of the MFC stages (ANSI, CRLF, echoed input,
sentinel remnants) and is shared by commands and polls.

A timed-out call leaves the session and the command running; the next call with
only session_id delivers from the cursor it left. Per-window output is bounded
by max_output_bytes, truncated on a line boundary, and ring evictions are
reported as dropped_bytes. When the shell dies mid-command the session stays
reachable until its buffered tail has been polled, then is released without
touching the hub, which may already belong to a new viewer.

Adds ClientCapTerminal (0x8000) for the Android gate; older APKs, macOS and
legacy non-PTY shells are refused with -32005.

Co-Authored-By: deepseek-flash
This commit is contained in:
yuanyuanxianganddeepseek-flash committed 2026-11-12 21:38:00 +01:00
1 parent 12b1bd4786
commit 599c891c00
9 files changed
+1728 -20

No files matched your search

+320
View File
@@ -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
}
+170
View File
@@ -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)
}
}
+1
View File
@@ -109,6 +109,7 @@ func New(cfg Config) *Server {
s.sessions = newSessionTable(nil)
}
s.registerLocalTools()
s.registerTerminalTools()
return s
}
+43 -7
View File
@@ -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)
}
+43 -4
View File
@@ -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<end<=%d", tc.name, start, end, len(tc.in))
}
}
if _, _, ok := scanSentinel([]byte("123"), ""); ok {
if _, _, _, ok := scanSentinel([]byte("123"), ""); ok {
t.Fatal("empty sentinel must never match")
}
}
@@ -345,6 +345,45 @@ func TestSweepSkipsReplacedSession(t *testing.T) {
}
}
// A draining session's close must not tear down a hub lease that a reconnected
// viewer has since opened: the shell the session referred to is already gone.
func TestCloseOfEndedSessionLeavesNewHubLease(t *testing.T) {
s, h := terminalTestServer(t)
sess, err := s.sessions.open("1001")
if err != nil {
t.Fatalf("open: %v", err)
}
s.OnTerminalReady("1001", true)
if _, rerr := sess.beginCommand("ab12cd34", "cmd", ""); rerr != nil {
t.Fatalf("begin: %v", rerr)
}
s.OnTerminalData("1001", termPacket("out\r\n"))
// The shell ends with output the client has not polled yet: the session
// stays in the table so the tail can still be collected. The hub event is
// delivered to subscribers by cmd/main.go's wiring.
h.CloseTerminalSession("1001")
s.OnTerminalClosed("1001", "closed")
if s.sessions.get("1001") != sess {
t.Fatal("draining session was dropped")
}
// Another viewer (or the same device after reconnecting) gets a fresh lease.
if err := h.OpenTerminalSession("1001"); err != nil {
t.Fatalf("new lease: %v", err)
}
if !h.HasTerminalSession("1001") {
t.Fatal("new lease not established")
}
if !s.sessions.closeSessionIf("1001", sess) {
t.Fatal("close did not remove the draining session")
}
if !h.HasTerminalSession("1001") {
t.Fatal("closing the ended session tore down the new viewer's shell")
}
}
func TestSentinelSplitAcrossChunks(t *testing.T) {
s, _ := terminalTestServer(t)
sess, err := s.sessions.open("1001")
+23 -9
View File
@@ -19,12 +19,21 @@ const termRingCap = 256 << 10
// accumulating whether or not an HTTP request is attached.
type pendingCmd struct {
sentinel string // "__MCP_DONE_<6 hex>__"
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)
+565
View File
@@ -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))
}
+559
View File
@@ -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)
}
}
+4
View File
@@ -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