feat: Terminal Backend PTY Support

[guitarrapc]

Summary

• Add MiniPty.Terminal, a terminal backend package for xterm.js and editor terminal integrations.
• Introduce PtyTerminal as a push-based PTY facade with output callbacks, completion ordering, input, resize, kill, and pause/resume flow control.
• Introduce PtyWebSocketBridge for raw binary PTY I/O plus JSON control messages over WebSocket.
• Add focused tests, documentation, and a browser terminal sample.

Intent

MiniPty’s core session API is pull-based, while frontend terminals usually expect a node-pty-like backend shape. This PR adds that backend layer without changing the core PTY ownership model or adding third-party dependencies, while preserving NativeAOT compatibility.

Expected Behavior

• PTY output is delivered to the configured handler before Completion resolves.
• Slow output handlers apply backpressure instead of buffering unbounded data.
• Pause() and Resume() stop and resume output delivery without dropping data.
• WebSocket binary frames carry raw PTY input/output bytes.
• WebSocket text frames handle resize, ack, and server-side exit control messages.
• Client disconnects, protocol violations, cancellation, and disposal deterministically tear down the child process.

[Copilot]

Pull request overview

Adds a new MiniPty.Terminal layer to provide a node-pty-shaped, push-based PTY backend suitable for xterm.js/editor integrations, while extending core MiniPty with exit-status + signal parity needed by those frontends.

Changes:

• Introduces MiniPty.Terminal (PtyTerminal push facade + PtyWebSocketBridge with ACK/watermark flow control).
• Extends core session lifecycle with PtyExitStatus, Unix termination signal reporting (ExitStatus, WaitForExitStatusAsync), and Kill(PtySignal).
• Adds focused tests, a browser WebSocket sample (WebTerminal), and updates docs/CI/packaging to include the new package and sample.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/MiniPty.Tests/PtyWebSocketBridgeTests.cs	Adds in-memory WebSocket bridge tests (framing, control messages, flow control, teardown).
tests/MiniPty.Tests/PtyTests.cs	Adds core tests for exit-status/signal reporting and signal-based kill semantics.
tests/MiniPty.Tests/PtyTerminalTests.cs	Adds tests for the push-based terminal facade ordering, pause/resume, and teardown semantics.
tests/MiniPty.Tests/MiniPty.Tests.csproj	References the new MiniPty.Terminal project from tests.
src/MiniPty/PtySignal.cs	Introduces PtySignal enum for cross-platform logical signal identifiers.
src/MiniPty/PtySession.cs	Adds ExitStatus, Kill(PtySignal), and WaitForExitStatusAsync.
src/MiniPty/PtyExitStatus.cs	Adds PtyExitStatus value type (exit code + optional Unix signal).
src/MiniPty/Internal/WindowsPtyBackend.cs	Implements ExitSignal (null) and Kill(PtySignal) validation/termination behavior.
src/MiniPty/Internal/UnixPtyBackend.cs	Captures termination signal from wait status, implements ExitSignal and Kill(PtySignal).
src/MiniPty/Internal/UnixInterop.cs	Adds Unix signal constants (HUP/INT/QUIT/TERM/USR1/USR2 variants).
src/MiniPty/Internal/IPtyBackend.cs	Extends backend contract with ExitSignal and Kill(PtySignal).
src/MiniPty.Terminal/PtyWebSocketBridge.cs	Adds the WebSocket bridge with protocol handling and teardown semantics.
src/MiniPty.Terminal/PtyTerminalOptions.cs	Adds terminal output handler delegate/options (backpressure via awaiting).
src/MiniPty.Terminal/PtyTerminal.cs	Adds push-based terminal facade with pause/resume and deterministic teardown.
src/MiniPty.Terminal/PtyBridgeOptions.cs	Adds bridge configuration (watermarks, caps, close timeouts) + validation.
src/MiniPty.Terminal/MiniPty.Terminal.csproj	New packable package project for the terminal backend.
src/MiniPty.Terminal/Internal/BridgeJson.cs	Source-generated STJ control-message parsing/serialization (AOT-safe).
src/MiniPty.Terminal/Internal/BridgeFlowControl.cs	Implements watermark/ACK flow control driving Pause/Resume.
scripts/pack-with-native.sh	Packs the new MiniPty.Terminal NuGet alongside existing packages.
samples/WebTerminal.cs	Adds browser demo + smoke mode for CI, using HttpListener + WebSocket bridge.
README.md	Documents new Terminal package, signal exit-status, and sample usage.
MiniPty.slnx	Adds MiniPty.Terminal to the solution.
.github/workflows/build.yaml	Adds WebTerminal to the NativeAOT publish/run sample loop.
.github/workflows/benchmark.yaml	Switches dotnet setup action usage for benchmark workflow.
.github/docs/specs/terminal.md	New spec describing terminal facade + WebSocket bridge protocol/flow control.
.github/docs/specs/lifecycle.md	Documents WaitForExitStatusAsync and Kill(PtySignal) lifecycle semantics.
.github/docs/specs/core_session.md	Adds exit-status/signal contract and updates use case 4 to use Terminal package.
.github/docs/specs/console.md	Updates console spec to point editor backend work to MiniPty.Terminal.
.github/docs/spec.md	Updates package map and implemented scope to include MiniPty.Terminal.
.github/docs/references/pty_crossplatform.md	Documents cross-platform signal kill + signal exit-status reporting behavior.
.github/docs/plans/plan_minipty_next.md	Records that editor backend parity items are now implemented.
.github/docs/plans/plan_editor_backend.md	Adds implemented plan/decision record for the editor/terminal backend.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.