stdio Bus – Workers Registry

Protocol workers for stdio Bus — a high-performance message routing kernel for AI agent protocols. This package provides ready-to-use ACP and MCP workers that run as child processes, communicating via NDJSON over stdin/stdout.

Install

npm install @stdiobus/workers-registry

For embedded mode (no Docker or binary needed):

npm install @stdiobus/node @stdiobus/workers-registry

Requires Node.js ≥ 20.0.0.

Architecture

graph TB
    %% ── Clients ──
    App["🖥️ Client Application"]
    IDE["🧩 IDE / MCP Client"]

    %% ── Kernel ──
    Kernel["⚡ stdio Bus kernel<br/><i>routing · session affinity · backpressure</i>"]

    %% ── Workers ──
    Registry["📋 ACP Registry<br/><code>acp-registry</code>"]
    ACP["🤖 ACP Worker<br/><code>acp-worker</code>"]
    OpenAI["🧠 OpenAI Agent<br/><code>openai-agent</code>"]
    Echo["🔁 Echo Worker<br/><code>echo-worker</code>"]
    Proxy["🔌 MCP-to-ACP Proxy<br/><code>mcp-to-acp-proxy</code>"]
    MCP["🛠️ MCP Echo Server<br/><code>mcp-echo-server</code>"]

    %% ── External agents ──
    Claude["Claude"]
    Goose["Goose"]
    Cline["Cline"]
    Copilot["GitHub Copilot"]
    Others["..."]

    %% ── External services ──
    OpenAIAPI["OpenAI API"]
    MCPServers["MCP Servers"]

    %% ── Connections ──
    App -->|"TCP / Unix Socket / Embedded"| Kernel
    IDE -->|"MCP Protocol (stdio)"| Proxy

    Kernel -->|"NDJSON stdin/stdout"| Registry
    Kernel -->|"NDJSON stdin/stdout"| ACP
    Kernel -->|"NDJSON stdin/stdout"| OpenAI
    Kernel -->|"NDJSON stdin/stdout"| Echo
    Proxy -->|"ACP via TCP"| Kernel

    Registry -->|"Spawns & routes"| Claude
    Registry -->|"Spawns & routes"| Goose
    Registry -->|"Spawns & routes"| Cline
    Registry -->|"Spawns & routes"| Copilot
    Registry -->|"Spawns & routes"| Others

    OpenAI -->|"HTTP/SSE"| OpenAIAPI
    ACP -->|"MCP Protocol"| MCPServers

    %% ── Styles ──
    classDef kernel fill:#1a1a2e,stroke:#4a90e2,stroke-width:3px,color:#fff,font-weight:bold
    classDef worker fill:#16213e,stroke:#50c878,stroke-width:2px,color:#fff
    classDef proxy fill:#16213e,stroke:#e67e22,stroke-width:2px,color:#fff
    classDef agent fill:#0f3460,stroke:#9b59b6,stroke-width:1px,color:#ddd
    classDef client fill:#1a1a2e,stroke:#f39c12,stroke-width:2px,color:#fff
    classDef external fill:#1a1a2e,stroke:#95a5a6,stroke-width:1px,color:#bbb,font-style:italic

    class Kernel kernel
    class Registry,ACP,OpenAI,Echo,MCP worker
    class Proxy proxy
    class Claude,Goose,Cline,Copilot,Others agent
    class App,IDE client
    class OpenAIAPI,MCPServers external

Workers communicate with the kernel via NDJSON (JSON-RPC 2.0, one message per line) over stdin/stdout. All logging goes to stderr. The kernel handles routing, session affinity, backpressure, and worker lifecycle.

Quick Start

Embedded

No Docker, no binary, no TCP. The bus runs inside your Node.js process.

import { StdioBus } from '@stdiobus/node';

const bus = new StdioBus({
  config: {
    pools: [{
      id: 'openai-agent',
      command: 'npx',
      args: ['@stdiobus/workers-registry', 'openai-agent'],
      instances: 1,
    }],
  },
});

await bus.start();

const result = await bus.request('initialize', {
  protocolVersion: 1,
  clientInfo: { name: 'my-app', version: '1.0.0' },
});

console.log(result.agentInfo.name); // 'openai-agent'
await bus.stop();

Universal Launcher

Run any worker directly:

npx @stdiobus/workers-registry echo-worker
npx @stdiobus/workers-registry acp-registry
npx @stdiobus/workers-registry openai-agent

Docker / TCP Mode

docker run -p 9000:9000 \
  -v $(pwd)/config.json:/config.json:ro \
  stdiobus/stdiobus:latest \
  --config /config.json --tcp 0.0.0.0:9000

echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' \
  | nc localhost 9000

Workers

Launchable Workers

| Worker | Description | Protocol | |--------|-------------|----------| | acp-registry | Routes to any ACP Registry agent (Claude, Goose, Cline, Copilot, etc.) | ACP | | acp-worker | Standalone ACP agent for SDK/protocol testing | ACP | | openai-agent | Bridges ACP to any OpenAI-compatible Chat Completions endpoint | ACP | | mcp-to-acp-proxy | Bridges MCP clients (IDEs) to ACP agents via stdio Bus | MCP → ACP | | echo-worker | Echoes messages back — for testing and protocol learning | NDJSON | | mcp-echo-server | MCP server with echo/reverse/uppercase tools — for testing | MCP |

All launchable via: npx @stdiobus/workers-registry <worker-name>

Internal Modules

| Module | Description | Used by | |--------|-------------|---------| | registry-launcher | Agent discovery, routing, OAuth, runtime management | acp-registry |

Exported for programmatic use but not a direct launch target.

Configuration

Workers are configured via stdio Bus pool configs:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": ["@stdiobus/workers-registry", "acp-registry"],
      "instances": 1
    }
  ]
}

Swap "acp-registry" for any worker name. Scale with "instances": N.

Worker-Specific Configuration

| Worker | Requirements | |--------|-------------| | acp-registry | api-keys.json in working directory (or custom config with apiKeysPath) | | openai-agent | OPENAI_API_KEY env var or OAuth login | | mcp-to-acp-proxy | ACP_HOST, ACP_PORT, AGENT_ID env vars |

Limits (optional)

{
  "limits": {
    "max_input_buffer": 1048576,
    "max_output_queue": 4194304,
    "max_restarts": 5,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}

See stdio Bus documentation for full configuration reference.

Package API

Exports

// Default export — ACP Worker
import worker from '@stdiobus/workers-registry';

// Individual workers
import acpWorker from '@stdiobus/workers-registry/workers/acp-worker';
import openaiAgent from '@stdiobus/workers-registry/workers/openai-agent';
import echoWorker from '@stdiobus/workers-registry/workers/echo-worker';
import mcpEchoServer from '@stdiobus/workers-registry/workers/mcp-echo-server';
import mcpToAcpProxy from '@stdiobus/workers-registry/workers/mcp-to-acp-proxy';

// Registry Launcher (programmatic access)
import registryLauncher from '@stdiobus/workers-registry/workers/registry-launcher';
import { resolveRegistry } from '@stdiobus/workers-registry/workers/registry-launcher/registry';
import { RuntimeManager } from '@stdiobus/workers-registry/workers/registry-launcher/runtime';

// Workers metadata
import { workers } from '@stdiobus/workers-registry/workers';

TypeScript

Full type definitions included. Strict mode.

import type { ACPAgent } from '@stdiobus/workers-registry/workers/acp-worker';
import type { MCPServer } from '@stdiobus/workers-registry/workers/mcp-echo-server';

IDE Integration (MCP Client)

Connect your IDE to ACP agents via the MCP-to-ACP proxy:

{
  "mcpServers": {
    "stdio-bus-acp": {
      "command": "npx",
      "args": ["@stdiobus/workers-registry", "mcp-to-acp-proxy"],
      "env": {
        "ACP_HOST": "localhost",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    }
  }
}

Requires acp-registry running on the stdio Bus side to resolve AGENT_ID to real agents.

Authentication

Registry Launcher supports two authentication methods:

API Keys

Create api-keys.json in your working directory:

{
  "claude-acp": { "apiKey": "sk-ant-..." },
  "openai-agent": { "apiKey": "sk-..." }
}

OAuth 2.1 with PKCE

npx @stdiobus/workers-registry acp-registry --login github
npx @stdiobus/workers-registry acp-registry --auth-status
npx @stdiobus/workers-registry acp-registry --logout

Supported OAuth providers: GitHub, Google, Azure AD, AWS Cognito, OIDC.

OpenAI and Anthropic use API keys, not OAuth. Configure them via api-keys.json or --setup.

Supported providers: GitHub, Google, Azure AD, AWS Cognito, OIDC.

OAuth takes precedence when available, with automatic fallback to API keys. For headless/CI environments, use API keys or environment variables.

See OAuth documentation for details.

Deployment Modes

| Mode | Package | Infrastructure | Use case | |------|---------|---------------|----------| | Embedded | @stdiobus/node + this package | None | Applications, scripts, testing | | Docker | This package (mounted) | stdiobus/stdiobus container | Production, multi-worker setups | | Binary | This package (on disk) | stdio_bus binary | Custom deployments |

All modes use the same worker configs and the same npx @stdiobus/workers-registry <worker> command.

Troubleshooting

| Problem | Solution | |---------|----------| | node: command not found or version < 20 | Install Node.js ≥ 20 (nvm install 20) | | Worker crashes on start | Check stderr output; verify config JSON is valid | | acp-registry fails to route | Ensure api-keys.json exists with valid keys | | Connection refused on port 9000 | Verify stdio Bus kernel is running (docker ps) | | MCP proxy can't reach agent | Check ACP_HOST/ACP_PORT env vars point to running kernel |

Documentation

• stdio Bus kernel — Core daemon (source code)
• @stdiobus/node — Embedded Node.js binding
• stdio Bus on Docker Hub — Docker images
• Full documentation — Protocol reference, guides, examples
• OAuth User Guide — Authentication setup
• OAuth CLI Reference — CLI commands
• FAQ — Frequently asked questions

Contributing

git clone https://github.com/stdiobus/workers-registry
cd workers-registry
npm install
npm run build
npm test

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 — Copyright (c) 2025–present Raman Marozau, Target Insight Function.

See LICENSE for details.