PTY Transport Probe¶
This integration probe asks whether a real child process can exchange the
current experimental OSC 9002 capability Messages through Windows ConPTY.
It composes the reference codec,
protocol Session, and node-pty 1.1.0.
The separate PTY demonstration builds on this transport
result with browser rendering.
Method¶
The same Node child runs first over ordinary pipes, then over the system
ConPTY and the ConPTY DLL bundled with the dependency. The PTY cases use
240 columns and 24 rows. The child enables raw stdin and writes a real
encoded capability query between printable diagnostic markers.
Once the host sees the ready marker, it writes an ordinary PTY_PING sentinel
and the capability response generated by the existing Session. It deliberately
sends this response even if the query was lost: this isolates the two transport
directions and is not the protocol’s negotiation or retry behavior.
The child reports whether it received the ordinary sentinel and decoded the
response within a two-second observation window. Each child then exits.
Observed Result¶
On 2026-09-09, Windows 10.0.19044, Node v24.20.0, node-pty 1.1.0,
with bundled ConPTY directory 1.23.251008001:
Transport |
Query decoded by host |
Ordinary input received by child |
Response decoded by child |
|---|---|---|---|
Ordinary pipes (control) |
Yes |
Yes |
Yes |
System ConPTY |
Yes |
Yes |
No |
Bundled ConPTY |
Yes |
Yes |
Yes |
Two runs with the ordinary-input control produced the same outcomes. All three children in each run exited with code zero and produced their diagnostic report. In the system-ConPTY run the child’s recorded input contained only the ordinary sentinel, not the response’s OSC bytes. This narrows the failure to the tested return path; it does not identify the responsible native implementation code or establish behavior for all Windows versions. An earlier run without the ordinary sentinel showed the same query/response outcomes.
The upstream node-pty API
exposes useConptyDll as an experimental choice between the bundled DLL and
the Windows implementation. The local test explicitly sets it for each run;
no Windows component is replaced or upgraded.
Host Choice¶
The maintainer approved using the tested bundled ConPTY for the first Windows demonstration. The demo selects the bundled DLL explicitly; the probe measures both paths independently.
Scope and Lifecycle¶
The probe checks one small query/response and an ordinary-input sentinel on the listed Windows transports. Context setup, rendering, larger frames, ordering, backpressure, and failure recovery need separate experiments. Other platforms, Node/ConPTY versions, SSH, and multiplexers are untested here.
Each child has an eight-second watchdog. The standalone probe explicitly exits after the children finish and its JSON report is flushed, because the Windows library may retain background handles.
Run¶
From the repository root, after pnpm install:
pnpm prototype:pty-transport
The command prints environment information, decoded outcomes, the first
40 received input bytes in hex, and captured output in hex. The output can
include local executable paths emitted by ConPTY; inspect before sharing it.
It exits with code 1 if any selected transport fails either direction or the
ordinary-input control. The observed system-ConPTY failure therefore makes the
overall command fail; it is not counted as a passing integration test.
This environment-dependent probe is separate from the regular pnpm test suite.