Native Socket Protocol Version 6 in pi-computer-use: macOS and Windows Transport Layers

Both macOS and Windows transport layers in pi-computer-use use protocol version 6 over local sockets—Unix-domain sockets on macOS and TCP sockets on Windows—to exchange JSON messages with native helper applications.

The pi-computer-use repository implements platform-specific transport layers that enable JavaScript applications to communicate with native operating system helpers via local sockets. Both the macOS and Windows implementations rely on a strict protocol version constant to ensure compatibility between the runtime client and the background helper daemon before executing system-level commands.

Protocol Version Constants by Platform

macOS HELPER_PROTOCOL_VERSION

In src/platform/macos/helper.ts at line 12, the constant HELPER_PROTOCOL_VERSION is explicitly set to 6. This integer represents the expected protocol revision that the macOS bridge application must advertise during the initial handshake. The client creates a Unix-domain socket at HELPER_SOCKET_PATH (typically ~/Library/Caches/pi-computer-use/bridge.sock) and initiates JSON message exchange only after validating this version.

Windows WINDOWS_HELPER_PROTOCOL_VERSION

Similarly, src/platform/windows/helper.ts at line 10 defines WINDOWS_HELPER_PROTOCOL_VERSION = 6. The Windows transport layer establishes a local TCP socket connection to the helper process running on localhost, using the same version validation mechanism before accepting commands.

Socket Architecture and Message Flow

Unix-Domain Sockets on macOS

The macOS transport layer utilizes Unix-domain sockets for inter-process communication. When the macosHelper class initializes, it spawns the bridge application and monitors the socket path for availability. All subsequent messages—including the critical "diagnostics" request—travel through this local socket as JSON payloads.

TCP Sockets on Windows

Windows employs TCP sockets bound to localhost rather than Unix-domain sockets. The windowsBackend establishes this connection during startup, forwarding API calls such as listApps() through the TCP stream. Despite the different transport mechanism, the message format remains identical to the macOS implementation.

Version Negotiation and Validation

Both platforms implement a validation routine that queries the helper's "diagnostics" endpoint immediately after connection. If the reported protocol version differs from the expected constant—6 for either platform—the client assumes a version mismatch and triggers corrective action, such as restarting the helper daemon (macOS) or throwing a compatibility error (Windows).

Implementing Protocol Checks in Your Code

macOS Socket Communication

To ensure compatibility with the native macOS helper before issuing commands, invoke the ensureProtocol() method provided by the platform helper class:

import { macosHelper } from "./platform/macos/helper.ts";

// Verify the helper daemon is running and speaks protocol version 6
await macosHelper.ensureProtocol();

// Request diagnostics to confirm version match
const diagnostics = await macosHelper.command("diagnostics", {});
console.log("macOS helper protocol version:", diagnostics.protocolVersion);

Windows Socket Communication

The Windows backend automatically performs version validation during initialization through the ensureReady() method:

import { windowsBackend } from "./platform/windows/backend.ts";

// Automatic protocol version check occurs here
await windowsBackend.ensureReady(/* ctx */{}, { lastPermissionCheckAt: 0 });

// Proceed with native commands after validation
const apps = await windowsBackend.listApps();
console.log(apps);

Key Source Files and Implementation Details

The transport layer implementation spans four critical files:

• src/platform/macos/helper.ts: Defines HELPER_PROTOCOL_VERSION = 6 (line 12), manages the Unix-domain socket lifecycle, and handles JSON serialization for the macOS bridge application.
• src/platform/macos/backend.ts: Provides the high-level macosHelper API that wraps socket operations and exposes methods like listApps() and focusWindow().
• src/platform/windows/helper.ts: Declares WINDOWS_HELPER_PROTOCOL_VERSION = 6 (line 10) and implements TCP socket management for the Windows helper process.
• src/platform/windows/backend.ts: Implements windowsBackend with automatic protocol validation and command forwarding to the Windows native layer.

Summary

• Both macOS and Windows transport layers in pi-computer-use utilize protocol version 6 for native socket communication.
• macOS uses Unix-domain sockets at ~/Library/Caches/pi-computer-use/bridge.sock with the constant HELPER_PROTOCOL_VERSION defined in src/platform/macos/helper.ts.
• Windows uses TCP sockets on localhost with the constant WINDOWS_HELPER_PROTOCOL_VERSION defined in src/platform/windows/helper.ts.
• Version mismatches trigger automatic helper restarts or error throws to prevent incompatible command execution.
• All messages follow a JSON-over-socket format validated through the "diagnostics" endpoint.

Frequently Asked Questions

What happens if the protocol version mismatches between client and helper?

If the client receives a protocol version other than 6 in the diagnostics response, it interprets this as a compatibility error. On macOS, the system automatically terminates and restarts the helper daemon to force a version sync. On Windows, the backend throws an explicit error indicating the version mismatch, halting further command execution until the helper is updated.

Why does macOS use Unix-domain sockets while Windows uses TCP?

Unix-domain sockets provide lower latency and better security for local inter-process communication on POSIX-compliant systems like macOS, bypassing network stack overhead. Windows implementations traditionally rely on TCP sockets for localhost communication due to differences in named pipe handling and cross-platform consistency requirements in the Node.js/JavaScript runtime environment.

How do I check the current protocol version of a running helper?

Query the "diagnostics" command through the platform-specific helper interface. On macOS, use await macosHelper.command("diagnostics", {}) and inspect the protocolVersion field in the response. The Windows backend performs this check automatically during ensureReady(), but you can also access version metadata through the underlying socket connection if manual verification is required.

Where is the protocol version defined in the source code?

The macOS protocol version 6 is declared at line 12 of src/platform/macos/helper.ts as HELPER_PROTOCOL_VERSION. The Windows equivalent is declared at line 10 of src/platform/windows/helper.ts as WINDOWS_HELPER_PROTOCOL_VERSION. Both constants must remain synchronized with the native helper application builds to maintain compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}