What are Workers?

Workers are child processes spawned by the stdio Bus kernel that implement specific protocol functionality. The stdio Bus kernel provides the core message routing infrastructure, while workers handle the actual protocol implementations (ACP, MCP, etc.) and use cases.

Workers communicate with the stdio Bus kernel via stdin/stdout using NDJSON (Newline-Delimited JSON), enabling high-performance, language-agnostic protocol implementations.

Architecture

The stdio Bus architecture consists of two main layers:

1. stdio Bus kernel - The core message routing daemon that manages worker processes and routes messages between clients and workers
2. Workers Registry - A collection of worker implementations that run as child processes of the kernel

Workers Launcher

The Workers Launcher is responsible for initializing and managing the lifecycle of worker processes. It ensures automatic discovery of agents from the ACP Registry and provides dynamic management of worker processes with session affinity routing. The launcher serves as a critical component in maintaining the seamless execution of multiple agents with varying protocols, offering support for orchestration and scalability within the stdio Bus framework.

Launcher: npx @stdiobus/workers-registry

Available Workers

The @stdiobus/workers-registry package provides the following worker implementations:

NDJSON Protocol

Workers communicate with stdio Bus kernel via stdin/stdout using NDJSON (Newline-Delimited JSON), a simple and efficient protocol for streaming JSON messages.

Protocol Rules

1. Input (stdin): stdio Bus sends JSON-RPC messages, one per line
2. Output (stdout): Workers write JSON-RPC responses, one per line
3. Errors (stderr): All logging and debug output goes to stderr
4. Critical: Never write non-JSON to stdout - it will break the protocol

Message Types

Request (requires response):

{"jsonrpc":"2.0","id":"1","method":"test","params":{"foo":"bar"}}

Response:

{"jsonrpc":"2.0","id":"1","result":{"status":"ok"}}

Notification (no response):

{"jsonrpc":"2.0","method":"notify","params":{"event":"started"}}

Session Affinity

Messages with the same sessionId are routed to the same worker instance, ensuring session state is maintained:

{"jsonrpc":"2.0","id":"1","method":"test","sessionId":"sess-123","params":{}}

Workers must preserve sessionId in responses for proper routing.

Graceful Shutdown

Workers must handle SIGTERM for graceful shutdown:

1. Stop accepting new messages
2. Complete in-flight processing
3. Exit with code 0

stdio Bus sends SIGTERM during shutdown or worker restarts.

Getting Started

To get started with workers:

1. Install the package: npm install @stdiobus/workers-registry
2. Get stdio Bus kernel: Available via Docker or build from source
3. Configure workers: Create a configuration file specifying which workers to run
4. Run stdio Bus: Start the kernel with your configuration

See the Installation Guide for detailed setup instructions.

Next Steps

• Installation - Install and set up the workers package
• Configuration - Configure workers for your use case
• Integration - Integrate workers into your application
• ACP Worker - Learn about the ACP Worker implementation
• Registry Launcher - Discover how to use the Registry Launcher

Resources

• stdio Bus kernel - Core protocol and daemon
• stdio Bus on Docker Hub - Docker images
• ACP Registry - Available ACP agents
• Agent Client Protocol SDK - Official ACP SDK
• Model Context Protocol SDK - Official MCP SDK