pms-infra-agent-socket
⚠️ Caution
Do not grant unrestricted control to AI.
Unsupervised use or misuse may lead to unintended consequences.
All AI systems must remain strictly under human oversight and control.
Use responsibly, with full awareness and at your own risk.
📘 Overview
pms-infra-agent-socket is a Haskell infrastructure library that provides AI agents with direct, low-level control over socket-based communication endpoints.
Unlike higher-level abstractions, this library exposes raw byte-stream access over both TCP/IP and Unix Domain Sockets, allowing agents to handle protocol-specific exchanges such as Telnet IAC negotiation, binary protocol framing, and real-time I/O monitoring with fine-grained control.
The library is a core component of the pty-mcp-server ecosystem and implements the agent-socket-* family of MCP tools.
agent-socket-open
Opens a socket connection for subsequent read/write operations.
Supports both TCP (host + port) and Unix Domain Socket (file) connections via a single tool.
host — TCP host name or IP address
port — TCP service name or port number
file — Unix domain socket path (absolute path required on Windows)
Only one socket connection can be active at a time.
agent-socket-close
Closes the active socket connection and releases all associated resources.
agent-socket-read
Reads up to the specified number of bytes from the active socket connection and returns the data as a UTF-8 string.
Returns an empty string if no data is available before timeout.
length — Maximum number of bytes to read
⚠️ If the received data contains non-UTF-8 bytes (e.g., binary protocols, IAC bytes), use agent-socket-read-byte instead.
agent-socket-read-byte
Reads up to the specified number of bytes from the active socket connection and returns the data as an uppercase hex string (e.g., FF0A1B41).
Use this for binary protocols or when precise byte-level inspection is required.
length — Maximum number of bytes to read
agent-socket-write
Writes the specified UTF-8 string to the active socket connection.
data — Text data to write
⚠️ Escape sequences such as \r\n in the string are sent as literal characters. To send exact byte sequences (e.g., CR+LF = 0D0A), use agent-socket-write-byte.
agent-socket-write-byte
Decodes the specified hex string and writes the resulting bytes to the active socket connection.
Use this for binary protocols or when precise byte-level control is required.
data — Uppercase hex string to decode and write (e.g., DEADBEEF0D0A)
💡 Usage Notes
IAC / Telnet negotiation
Telnet IAC processing is the responsibility of the agent, not the library.
Use agent-socket-read-byte and agent-socket-write-byte to handle IAC sequences at the byte level.
Example negotiation flow:
← FFFD18FFFD20FFFD23FFFD27 (Server: IAC DO TERMINAL-TYPE/SPEED/X-DISPLAY/NEW-ENVIRON)
→ FFFC18FFFC20FFFC23FFFC27 (Agent: IAC WONT x4)
← FFFB03FFFD01FFFD1FFFFB05 (Server: IAC WILL SGA / DO ECHO / DO NAWS / WILL STATUS)
→ FFFD03FFFB01FFFC1FFFFD05 (Agent: IAC DO SGA / WILL ECHO / WONT NAWS / DO STATUS)
← "localhost login: " (Login prompt — read as UTF-8 string)
→ "phoityne\r\n" (Username — send as bytes: 70686F6974796E650D0A)
← "Password: " (Password prompt)
Unix Domain Socket on Windows
Unix Domain Socket (file parameter) is supported on Windows 10 build 1803 and later at the OS level.
However, the socket server side must be implemented in a runtime that supports AF_UNIX on Windows.
- Python 3.13.7 (Windows):
socket.AF_UNIX is unavailable unless Developer Mode is enabled.
- PowerShell / .NET:
System.Net.Sockets.UnixDomainSocketEndPoint works without Developer Mode.
- pty-mcp-server (Haskell): Confirmed working on Windows 11 via
Network.Socket with AF_UNIX.
🏗️ Architecture
Module Structure
PMS.Infra.Agent.Socket
├── DM.Type -- Data type definitions (SocketData, AppData, tool parameter types)
├── DM.Constant -- Constants
├── DS.Core -- Core domain service logic
├── DS.Utility -- Utility functions (TCP connect, Unix Domain Socket connect)
└── App.Control -- Application control: tool dispatch and socket lifecycle management
Key Design Points
- Single active connection: Only one socket can be open at a time per server instance. State is managed via
STM.TMVar.
- Dual connection mode:
agent-socket-open supports both TCP (host/port) and Unix Domain Socket (file) via a single unified interface.
- Non-blocking reads: Read operations return immediately with available data, allowing the agent to poll at its own pace.
- Byte-level I/F: In addition to UTF-8 string I/F, hex string I/F is provided for binary protocol handling. IAC processing and protocol framing are delegated to the agent.
📦 Dependencies
- Execution & Process Lead: Claude Sonnet 4.6, Gemini 3 Flash, GPT-5.5
- Direction & Policy: phoityne
- License: Apache-2.0 — see LICENSE
