Skip to main content
Glama
Host Process & Sub-Agent Governor

Host Process & Sub-Agent Governor

by jasonroject
README.md
# Host Process & Sub-Agent Governor (`host-governor-plugin`)

A lightweight Model Context Protocol (MCP) server providing host process supervision, multi-process management, and sub-agent concurrency control for AI agent environments including Google Antigravity and OpenAI Codex.

---

## Key Capabilities

- **Sub-Agent Quota Enforcement**: Strictly caps concurrent sub-agents to a configurable threshold (default: 3 per AI model) across Harness windows via atomic lockfiles and priority queueing.
- **Detached Background Execution**: Spawns and manages asynchronous background software processes without blocking agent tool loops.
- **Process-Tree Termination**: Ensures clean lifecycle management (`taskkill /t` on Windows, POSIX process groups on Unix) with graceful shutdown windows before force killing.
- **Bounded Ring Buffering**: Retains head and tail logs while streaming high-throughput processes without unbounded memory consumption.
- **Automated Secret Redaction**: Masks Bearer tokens, API credentials, and sensitive environment keys from stdout/stderr captures.
- **Cross-Harness Interoperability**: Compatible with Antigravity (`hooks.json` PreToolUse hook) and standard MCP stdio clients.

---

## Quickstart

### Prerequisites
- Node.js (v18 or later)
- npm

### Installation & Build

```bash
# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run Vitest test suite
npm test
```

### Running the MCP Server

```bash
node dist/index.js
```

All JSON-RPC messages are communicated strictly over `stdio`. Diagnostics and internal logs are routed to `stderr`.

---

## MCP Tools Reference

| Tool | Purpose |
|---|---|
| `host_exec_start` | Launch a host process in the background |
| `host_exec_status` | Query state and metadata of running or completed processes |
| `host_exec_logs` | Retrieve bounded, secret-redacted process output |
| `host_exec_input` | Send input to a running interactive process via stdin |
| `host_exec_stop` | Terminate a process and its child process tree |
| `governor_acquire_slot` | Request a sub-agent concurrency lease |
| `governor_release_slot` | Release an active lease and unblock queue |
| `governor_status` | View global concurrency quotas and active processes |
| `governor_diagnose` | Inspect host platform, memory usage, and saturation status |

---

## Documentation

Detailed technical documentation is available in the `docs/` directory:
- [System Architecture](docs/ARCHITECTURE.md)
- [MCP Tool Reference](docs/TOOL_REFERENCE.md)
- [Compatibility Matrix](docs/COMPATIBILITY.md)
- [Deployment & Rollback Guide](docs/DEPLOYMENT_AND_ROLLBACK.md)

---

## License

MIT License. See [LICENSE](LICENSE) for details.

TDQS

A3.7/5.0

Scored across 9 tools

Disambiguation4/5

The tools are split into two clear domains, governor and host process management, with mostly distinct actions. The only mild overlap is between governor_status and governor_diagnose, but the descriptions distinguish routine state inspection from deeper diagnostics.

Naming Consistency5/5

All tool names use lowercase snake_case with consistent governor_ and host_exec_ prefixes. Verb choices are predictable: status, start, logs, input, stop, acquire, release, diagnose.

Tool Count5/5

Nine tools is well-scoped for managing host background processes and sub-agent concurrency. Each tool has a clear lifecycle role and no obvious redundant operations.

Completeness4/5

The host process lifecycle is well covered: start, inspect, read logs, send input, and stop. Governor concurrency is covered through status, acquire, release, and diagnose, though there is no explicit queue-management or stale-lock cleanup operation.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues