pms-infra-agent-process

⚠️ 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-process is a Haskell infrastructure library that provides AI agents with direct, low-level control over external processes via standard input/output.

Unlike PTY-based tools, this library communicates with spawned processes directly through stdin/stdout/stderr handles, without allocating a pseudo-terminal. This makes it well-suited for non-TUI programs that communicate via plain text streams, such as language servers, compilers, or custom automation scripts.

The library is a core component of the pty-mcp-server ecosystem and implements the agent-proc-* family of MCP tools.

🔧 Provided MCP Tools

agent-proc-run

Spawns an external process with the specified command and options. The process's stdin/stdout are connected for subsequent agent-proc-read and agent-proc-write operations. Only one process can be active at a time.

Supports an allowedAgentCmds whitelist — if configured, only commands present in the whitelist are permitted to run.

agent-proc-read

Reads up to the specified number of bytes from the stdout of the running process. Returns immediately with available data (non-blocking). Returns an empty string if no data is available.

agent-proc-write

Writes the specified string to the stdin of the running process.

agent-proc-terminate

Forcefully terminates the currently running process. Resets internal state so agent-proc-run can be called again.

🏗️ Architecture

Module Structure

PMS.Infra.Agent.Process
├── DM.Type        -- Data type definitions (ProcData, AppData, tool parameter types)
├── DM.Constant    -- Constants
├── DS.Core        -- Core domain service logic
├── DS.Utility     -- Utility functions
└── App.Control    -- Application control: tool dispatch and process lifecycle management

Key Design Points

• Single active process: Only one process can run at a time per server instance. State is managed via STM.TMVar.
• Non-blocking reads: agent-proc-read returns immediately without blocking, allowing the agent to poll at its own pace.
• Whitelist enforcement: agent-proc-run checks the command against allowedAgentCmds from the configuration before spawning. If the list is empty, all commands are denied by default.
• Direct stdio: No PTY allocation. Suitable for programs that do not require a terminal environment.

📦 Dependencies

• pms-domain-model

📜 Credits & License

• Execution & Process Lead: Sonnet 4.6, Gemini 3 Flash
• Direction & Policy: phoityne
• License: Apache-2.0 — see LICENSE