feat: serial expect/send automation sequences

[llogen]

Summary

Adds hands-off serial automation to the serial dutagent module: wait for prompts and send input, scripted end-to-end on the agent. This is what FirmwareCI/contest automation needs (login flows, running commands over the DUT console) — no human-interactive console required.

It replaces main's read-only single-expect serial module with an expect / expect-send / sequence implementation, a rolling-window matcher, terminal-escape filtering, and a configurable inter-send delay.

What's new

Argument modes

All matching and input happen server-side on the dutagent.

Mode	Arguments	Behavior
Monitor	(none)	Stream serial output until the session is cancelled.
Expect	<regex>	Wait until the regex matches the output, then exit.
Expect-send	<regex> <resp> … (even count)	For each pair: wait for the pattern, then write the response to the port.
Sequence	expect:<regex> / send:<data> tags, any order	Ordered steps run one after another; may start with a send and freely interleave sends and expects.

Tagged sequence (headline feature)

serial send:'\n' expect:'login:' send:'root\n' expect:'Password:' send:'secret\n' expect:'# '

Unlike expect-send pairs (which must start with an expect and strictly alternate), a sequence can begin with a send (e.g. an Enter to wake the console) and chain sends/expects in any order — including two sends in a row.

• Ends on an expect → exits the moment that pattern matches.
• Ends on a send → drains output for ~1s so the reply is visible, then exits.
• The whole sequence shares the -t deadline.
• send supports C-style escapes: \n \r \t \\ \xHH.
• expect is an RE2 regular expression.

delay module option

A with: option that paces input — a pause applied before every send:

- module: serial
  with:
    port: /dev/serial/by-id/usb-FTDI_...-port0
    baud: 115200
    delay: 200ms        # optional; default 50ms; "0s" disables

Default 50ms. It covers two timing problems that bite real consoles:

• a prompt appears slightly before the tty is ready to read (sending the instant
  login: shows can drop the first characters),
• back-to-back sends arriving too fast to be processed.

Expect-gating (waiting for the prompt/echo) is still the primary, deterministic
mechanism; the delay is a safety net for consoles that signal readiness early or
give nothing to expect on. Set delay: "0s" to send immediately.

Key behaviors

• Rolling-window matcher (64 KiB cap, copied tail-to-front so memory stays
  bounded) re-checked on every read, so a prompt without a trailing newline
  (login:) matches immediately instead of waiting for the next line.
• Terminal escape filtering: non-SGR CSI sequences (cursor moves, queries)
  and ANSI string sequences (DCS/OSC/SOS/PM/APC capability responses) are
  stripped from the output; SGR colour is preserved.
• Send-step responses are written to the serial port by the agent.
• A genuine read error ends the session.

Explicitly not in this PR (deferred to a follow-up)

• Interactive console (raw-mode live typing from the client)
• Client stdin → serial-port forwarding
• Auto-reconnect when the serial device disappears mid-session

These are a separate concern from automation and will land in a follow-up PR.

Backward compatibility

• serial (single expect) still works; it now uses the rolling-window
  matcher, so it also catches prompts that arrive without a trailing newline.
• Adds expect-send pairs and the tagged sequence mode on top.

Examples

dutctl serial # monitor output
dutctl serial 'login:' # wait for a prompt
dutctl serial 'login:' 'root\n' # expect-send pair
dutctl serial send:'\n' expect:'login:'
send:'root\n' expect:'# ' # sequence (any order)

Testing

• Unit tests for escape filtering (incl. DCS/OSC and split-across-reads),
  argument parsing (legacy + tagged sequence), Init (port/baud/delay defaults
  and parsing), and Run behavior (single expect, expect-send pairs, sequence:
  leading-send / send-only / ends-on-expect, timeout, CSI stripping, match
  spanning reads, context cancel, pre-send delay). go test -race and
  golangci-lint clean.
• The expect/send/sequence and escape-filtering logic was validated against a
  real HPE DL320 OpenBMC serial console (login → run command → reboot, the
  trailing-send drain, and timeout behavior).

Files changed

• pkg/module/serial/serial.go
• pkg/module/serial/serial_test.go
• pkg/module/serial/serial_run_test.go

Related (separate repos, companion PRs)

• contest: newdutctl teststep gains a structured sequence parameter that
  renders into these tagged arguments.
• firmwareci: JSON schema for the newdutctl sequence parameter.

🤖 Generated with Claude Code