@stdiobus/workers-registry 1.5.3 → 1.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +199 -989
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,536 +1,280 @@
|
|
|
1
|
-
# stdio Bus –
|
|
1
|
+
# stdio Bus – Workers Registry
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@stdiobus/workers-registry)
|
|
4
|
-
[](https://www.npmjs.com/package/@stdiobus/workers-registry)
|
|
5
5
|
[](https://agentclientprotocol.com)
|
|
6
6
|
[](https://modelcontextprotocol.io)
|
|
7
|
+
[](https://github.com/stdiobus)
|
|
7
8
|
[](https://nodejs.org)
|
|
8
|
-
[](https://esbuild.github.io)
|
|
9
|
-
[](https://hub.docker.com/r/stdiobus/stdiobus)
|
|
10
|
-
[](https://github.com/stdiobus/workers-registry)
|
|
11
|
-
[](https://github.com/stdiobus/workers-registry)
|
|
12
|
-
[](https://github.com/stdiobus/workers-registry/blob/main/LICENSE)
|
|
13
9
|
[](https://www.typescriptlang.org)
|
|
10
|
+
[](https://github.com/stdiobus/workers-registry)
|
|
14
11
|
[](https://github.com/stdiobus/workers-registry)
|
|
15
|
-
[](https://ndjson.org)
|
|
17
|
-
[](https://www.jsonrpc.org)
|
|
12
|
+
[](https://github.com/stdiobus/workers-registry/blob/main/LICENSE)
|
|
18
13
|
|
|
19
|
-
|
|
14
|
+
Protocol workers for [stdio Bus](https://github.com/stdiobus/stdiobus) — 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.
|
|
20
15
|
|
|
21
|
-
|
|
22
|
-
- Full ACP (Agent Client Protocol) implementation
|
|
23
|
-
- MCP (Model Context Protocol) server integration
|
|
24
|
-
- Protocol bridges (MCP ↔ ACP)
|
|
25
|
-
- TypeScript support with full type definitions
|
|
26
|
-
- High-performance NDJSON protocol
|
|
27
|
-
- Docker-ready
|
|
16
|
+
---
|
|
28
17
|
|
|
29
|
-
##
|
|
18
|
+
## Install
|
|
30
19
|
|
|
31
20
|
```bash
|
|
32
21
|
npm install @stdiobus/workers-registry
|
|
33
22
|
```
|
|
34
23
|
|
|
35
|
-
For embedded
|
|
24
|
+
For embedded mode (no Docker or binary needed):
|
|
36
25
|
|
|
37
26
|
```bash
|
|
38
27
|
npm install @stdiobus/node @stdiobus/workers-registry
|
|
39
28
|
```
|
|
40
29
|
|
|
41
|
-
**
|
|
42
|
-
- Node.js ≥20.0.0
|
|
43
|
-
- [stdio Bus kernel](https://github.com/stdiobus/stdiobus) (Docker or binary) — or [`@stdiobus/node`](https://www.npmjs.com/package/@stdiobus/node) for embedded mode
|
|
44
|
-
|
|
45
|
-
**Keywords:** `stdiobus`, `protocol`, `acp`, `mcp`, `agent`, `transport`, `json-rpc`, `stdio-bus`, `worker`
|
|
30
|
+
Requires **Node.js ≥ 20.0.0**.
|
|
46
31
|
|
|
47
32
|
---
|
|
48
33
|
|
|
49
|
-
## Overview
|
|
50
|
-
|
|
51
|
-
stdio Bus kernel provides the core protocol and message routing infrastructure. This package contains the worker implementations that run as child processes of stdio Bus kernel, handling various agent protocols and use cases.
|
|
52
|
-
|
|
53
34
|
## Architecture
|
|
54
35
|
|
|
55
36
|
```mermaid
|
|
56
37
|
graph TB
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
Registry
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
**Note:** `acp-registry` is a worker runtime launched via
|
|
122
|
-
`@stdiobus/workers-registry/launch` and is not exported as a module.
|
|
123
|
-
|
|
124
|
-
### TypeScript Support
|
|
38
|
+
%% ── Clients ──
|
|
39
|
+
App["🖥️ Client Application"]
|
|
40
|
+
IDE["🧩 IDE / MCP Client"]
|
|
41
|
+
|
|
42
|
+
%% ── Kernel ──
|
|
43
|
+
Kernel["⚡ stdio Bus kernel<br/><i>routing · session affinity · backpressure</i>"]
|
|
44
|
+
|
|
45
|
+
%% ── Workers ──
|
|
46
|
+
Registry["📋 ACP Registry<br/><code>acp-registry</code>"]
|
|
47
|
+
ACP["🤖 ACP Worker<br/><code>acp-worker</code>"]
|
|
48
|
+
OpenAI["🧠 OpenAI Agent<br/><code>openai-agent</code>"]
|
|
49
|
+
Echo["🔁 Echo Worker<br/><code>echo-worker</code>"]
|
|
50
|
+
Proxy["🔌 MCP-to-ACP Proxy<br/><code>mcp-to-acp-proxy</code>"]
|
|
51
|
+
MCP["🛠️ MCP Echo Server<br/><code>mcp-echo-server</code>"]
|
|
52
|
+
|
|
53
|
+
%% ── External agents ──
|
|
54
|
+
Claude["Claude"]
|
|
55
|
+
Goose["Goose"]
|
|
56
|
+
Cline["Cline"]
|
|
57
|
+
Copilot["GitHub Copilot"]
|
|
58
|
+
Others["..."]
|
|
59
|
+
|
|
60
|
+
%% ── External services ──
|
|
61
|
+
OpenAIAPI["OpenAI API"]
|
|
62
|
+
MCPServers["MCP Servers"]
|
|
63
|
+
|
|
64
|
+
%% ── Connections ──
|
|
65
|
+
App -->|"TCP / Unix Socket / Embedded"| Kernel
|
|
66
|
+
IDE -->|"MCP Protocol (stdio)"| Proxy
|
|
67
|
+
|
|
68
|
+
Kernel -->|"NDJSON stdin/stdout"| Registry
|
|
69
|
+
Kernel -->|"NDJSON stdin/stdout"| ACP
|
|
70
|
+
Kernel -->|"NDJSON stdin/stdout"| OpenAI
|
|
71
|
+
Kernel -->|"NDJSON stdin/stdout"| Echo
|
|
72
|
+
Proxy -->|"ACP via TCP"| Kernel
|
|
73
|
+
|
|
74
|
+
Registry -->|"Spawns & routes"| Claude
|
|
75
|
+
Registry -->|"Spawns & routes"| Goose
|
|
76
|
+
Registry -->|"Spawns & routes"| Cline
|
|
77
|
+
Registry -->|"Spawns & routes"| Copilot
|
|
78
|
+
Registry -->|"Spawns & routes"| Others
|
|
79
|
+
|
|
80
|
+
OpenAI -->|"HTTP/SSE"| OpenAIAPI
|
|
81
|
+
ACP -->|"MCP Protocol"| MCPServers
|
|
82
|
+
|
|
83
|
+
%% ── Styles ──
|
|
84
|
+
classDef kernel fill:#1a1a2e,stroke:#4a90e2,stroke-width:3px,color:#fff,font-weight:bold
|
|
85
|
+
classDef worker fill:#16213e,stroke:#50c878,stroke-width:2px,color:#fff
|
|
86
|
+
classDef proxy fill:#16213e,stroke:#e67e22,stroke-width:2px,color:#fff
|
|
87
|
+
classDef agent fill:#0f3460,stroke:#9b59b6,stroke-width:1px,color:#ddd
|
|
88
|
+
classDef client fill:#1a1a2e,stroke:#f39c12,stroke-width:2px,color:#fff
|
|
89
|
+
classDef external fill:#1a1a2e,stroke:#95a5a6,stroke-width:1px,color:#bbb,font-style:italic
|
|
90
|
+
|
|
91
|
+
class Kernel kernel
|
|
92
|
+
class Registry,ACP,OpenAI,Echo,MCP worker
|
|
93
|
+
class Proxy proxy
|
|
94
|
+
class Claude,Goose,Cline,Copilot,Others agent
|
|
95
|
+
class App,IDE client
|
|
96
|
+
class OpenAIAPI,MCPServers external
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
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.
|
|
125
100
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
```typescript
|
|
129
|
-
import type { ACPAgent } from '@stdiobus/workers-registry/workers/acp-worker';
|
|
130
|
-
import type { MCPServer } from '@stdiobus/workers-registry/workers/mcp-echo-server';
|
|
131
|
-
```
|
|
101
|
+
---
|
|
132
102
|
|
|
133
103
|
## Quick Start
|
|
134
104
|
|
|
135
|
-
###
|
|
136
|
-
|
|
137
|
-
No Docker, no binary, no TCP — just npm packages. The bus runs inside your Node.js process.
|
|
105
|
+
### Embedded
|
|
138
106
|
|
|
139
|
-
|
|
140
|
-
npm install @stdiobus/node @stdiobus/workers-registry
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
Create `config.json`:
|
|
144
|
-
|
|
145
|
-
```json
|
|
146
|
-
{
|
|
147
|
-
"pools": [
|
|
148
|
-
{
|
|
149
|
-
"id": "openai-agent",
|
|
150
|
-
"command": "npx",
|
|
151
|
-
"args": ["@stdiobus/workers-registry", "openai-agent"],
|
|
152
|
-
"instances": 1
|
|
153
|
-
}
|
|
154
|
-
]
|
|
155
|
-
}
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
Use it in code:
|
|
107
|
+
No Docker, no binary, no TCP. The bus runs inside your Node.js process.
|
|
159
108
|
|
|
160
109
|
```javascript
|
|
161
110
|
import { StdioBus } from '@stdiobus/node';
|
|
162
111
|
|
|
163
|
-
const bus = new StdioBus({
|
|
112
|
+
const bus = new StdioBus({
|
|
113
|
+
config: {
|
|
114
|
+
pools: [{
|
|
115
|
+
id: 'openai-agent',
|
|
116
|
+
command: 'npx',
|
|
117
|
+
args: ['@stdiobus/workers-registry', 'openai-agent'],
|
|
118
|
+
instances: 1,
|
|
119
|
+
}],
|
|
120
|
+
},
|
|
121
|
+
});
|
|
122
|
+
|
|
164
123
|
await bus.start();
|
|
165
124
|
|
|
166
|
-
// Send ACP initialize request
|
|
167
125
|
const result = await bus.request('initialize', {
|
|
168
126
|
protocolVersion: 1,
|
|
169
127
|
clientInfo: { name: 'my-app', version: '1.0.0' },
|
|
170
128
|
});
|
|
171
129
|
|
|
172
|
-
console.log(result.agentInfo.name);
|
|
173
|
-
console.log(result.authMethods); // [{ id: 'oauth2', ... }]
|
|
174
|
-
|
|
130
|
+
console.log(result.agentInfo.name); // 'openai-agent'
|
|
175
131
|
await bus.stop();
|
|
176
132
|
```
|
|
177
133
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
```json
|
|
181
|
-
{
|
|
182
|
-
"pools": [
|
|
183
|
-
{
|
|
184
|
-
"id": "acp-registry",
|
|
185
|
-
"command": "npx",
|
|
186
|
-
"args": ["@stdiobus/workers-registry", "acp-registry"],
|
|
187
|
-
"instances": 1
|
|
188
|
-
}
|
|
189
|
-
]
|
|
190
|
-
}
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
See [`@stdiobus/node` on npm](https://www.npmjs.com/package/@stdiobus/node) for TCP mode, Unix socket mode, Docker backend, and full API reference.
|
|
194
|
-
|
|
195
|
-
### Option B: Docker / Binary (TCP mode)
|
|
196
|
-
|
|
197
|
-
#### 1. Install Package
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
npm install @stdiobus/workers-registry
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
#### 2. Get stdio Bus kernel
|
|
134
|
+
### Universal Launcher
|
|
204
135
|
|
|
205
|
-
|
|
136
|
+
Run any worker directly:
|
|
206
137
|
|
|
207
138
|
```bash
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
**Option B: Build from source**
|
|
212
|
-
|
|
213
|
-
See [stdio Bus kernel repository](https://github.com/stdiobus/stdiobus) for build instructions.
|
|
214
|
-
|
|
215
|
-
#### 3. Run with ACP Registry (recommended for real agents)
|
|
216
|
-
|
|
217
|
-
**Create config.json:**
|
|
218
|
-
```json
|
|
219
|
-
{
|
|
220
|
-
"pools": [
|
|
221
|
-
{
|
|
222
|
-
"id": "acp-registry",
|
|
223
|
-
"command": "npx",
|
|
224
|
-
"args": [
|
|
225
|
-
"@stdiobus/workers-registry",
|
|
226
|
-
"acp-registry"
|
|
227
|
-
],
|
|
228
|
-
"instances": 1
|
|
229
|
-
}
|
|
230
|
-
]
|
|
231
|
-
}
|
|
139
|
+
npx @stdiobus/workers-registry echo-worker
|
|
140
|
+
npx @stdiobus/workers-registry acp-registry
|
|
141
|
+
npx @stdiobus/workers-registry openai-agent
|
|
232
142
|
```
|
|
233
143
|
|
|
234
|
-
|
|
235
|
-
or pass a custom config file (third arg to `launch acp-registry`) with an absolute
|
|
236
|
-
`apiKeysPath`. In this repo, the default file is
|
|
237
|
-
`workers-registry/acp-registry/acp-registry-config.json`.
|
|
238
|
-
Use the same Docker/binary commands below (they run `config.json`), and ensure
|
|
239
|
-
`api-keys.json` is mounted into the container when using Docker.
|
|
240
|
-
|
|
241
|
-
#### 4. Run with ACP Worker
|
|
242
|
-
|
|
243
|
-
**Note:** `acp-worker` is a standalone ACP agent for SDK/protocol testing. It does **not**
|
|
244
|
-
route to the ACP Registry. Use `acp-registry` when you need real registry agents.
|
|
245
|
-
|
|
246
|
-
**Create config.json:**
|
|
247
|
-
```json
|
|
248
|
-
{
|
|
249
|
-
"pools": [
|
|
250
|
-
{
|
|
251
|
-
"id": "acp-worker",
|
|
252
|
-
"command": "npx",
|
|
253
|
-
"args": [
|
|
254
|
-
"@stdiobus/workers-registry",
|
|
255
|
-
"acp-worker"
|
|
256
|
-
],
|
|
257
|
-
"instances": 1
|
|
258
|
-
}
|
|
259
|
-
]
|
|
260
|
-
}
|
|
261
|
-
```
|
|
144
|
+
### Docker / TCP Mode
|
|
262
145
|
|
|
263
|
-
**Run with Docker:**
|
|
264
146
|
```bash
|
|
265
147
|
docker run -p 9000:9000 \
|
|
266
|
-
-v $(pwd):/stdiobus:ro \
|
|
267
148
|
-v $(pwd)/config.json:/config.json:ro \
|
|
268
149
|
stdiobus/stdiobus:latest \
|
|
269
150
|
--config /config.json --tcp 0.0.0.0:9000
|
|
270
151
|
```
|
|
271
152
|
|
|
272
|
-
**Or with binary:**
|
|
273
153
|
```bash
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
#### 5. Test Connection
|
|
278
|
-
|
|
279
|
-
```bash
|
|
280
|
-
# ACP worker (standalone)
|
|
281
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' | nc localhost 9000
|
|
282
|
-
|
|
283
|
-
# ACP Registry worker (route to a registry agent)
|
|
284
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"agentId":"claude-acp","clientInfo":{"name":"test","version":"1.0"}}}' | nc localhost 9000
|
|
154
|
+
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' \
|
|
155
|
+
| nc localhost 9000
|
|
285
156
|
```
|
|
286
157
|
|
|
287
158
|
---
|
|
288
159
|
|
|
289
|
-
##
|
|
160
|
+
## Workers
|
|
290
161
|
|
|
291
|
-
###
|
|
162
|
+
### Launchable Workers
|
|
292
163
|
|
|
293
|
-
|
|
164
|
+
| Worker | Description | Protocol |
|
|
165
|
+
|--------|-------------|----------|
|
|
166
|
+
| `acp-registry` | Routes to any [ACP Registry](https://agentclientprotocol.com) agent (Claude, Goose, Cline, Copilot, etc.) | ACP |
|
|
167
|
+
| `acp-worker` | Standalone ACP agent for SDK/protocol testing | ACP |
|
|
168
|
+
| `openai-agent` | Bridges ACP to any OpenAI-compatible Chat Completions endpoint | ACP |
|
|
169
|
+
| `mcp-to-acp-proxy` | Bridges MCP clients (IDEs) to ACP agents via stdio Bus | MCP → ACP |
|
|
170
|
+
| `echo-worker` | Echoes messages back — for testing and protocol learning | NDJSON |
|
|
171
|
+
| `mcp-echo-server` | MCP server with echo/reverse/uppercase tools — for testing | MCP |
|
|
294
172
|
|
|
295
|
-
|
|
296
|
-
# Run any worker by name (recommended)
|
|
297
|
-
npx @stdiobus/workers-registry <worker-name>
|
|
173
|
+
All launchable via: `npx @stdiobus/workers-registry <worker-name>`
|
|
298
174
|
|
|
299
|
-
|
|
300
|
-
node ./launch/index.js <worker-name>
|
|
175
|
+
### Internal Modules
|
|
301
176
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
# - echo-worker
|
|
306
|
-
# - mcp-echo-server
|
|
307
|
-
# - mcp-to-acp-proxy
|
|
308
|
-
# - openai-agent
|
|
177
|
+
| Module | Description | Used by |
|
|
178
|
+
|--------|-------------|---------|
|
|
179
|
+
| `registry-launcher` | Agent discovery, routing, OAuth, runtime management | `acp-registry` |
|
|
309
180
|
|
|
310
|
-
|
|
311
|
-
npx @stdiobus/workers-registry echo-worker
|
|
312
|
-
```
|
|
181
|
+
Exported for programmatic use but not a direct launch target.
|
|
313
182
|
|
|
314
|
-
|
|
183
|
+
---
|
|
315
184
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
"pools": [{
|
|
320
|
-
"id": "acp-worker",
|
|
321
|
-
"command": "npx",
|
|
322
|
-
"args": [
|
|
323
|
-
"@stdiobus/workers-registry",
|
|
324
|
-
"acp-worker"
|
|
325
|
-
],
|
|
326
|
-
"instances": 1
|
|
327
|
-
}]
|
|
328
|
-
}
|
|
329
|
-
```
|
|
185
|
+
## Configuration
|
|
186
|
+
|
|
187
|
+
Workers are configured via stdio Bus pool configs:
|
|
330
188
|
|
|
331
|
-
**ACP Registry Worker with API Keys:**
|
|
332
189
|
```json
|
|
333
190
|
{
|
|
334
191
|
"pools": [
|
|
335
192
|
{
|
|
336
193
|
"id": "acp-registry",
|
|
337
194
|
"command": "npx",
|
|
338
|
-
"args": [
|
|
339
|
-
"@stdiobus/workers-registry",
|
|
340
|
-
"acp-registry"
|
|
341
|
-
],
|
|
195
|
+
"args": ["@stdiobus/workers-registry", "acp-registry"],
|
|
342
196
|
"instances": 1
|
|
343
197
|
}
|
|
344
198
|
]
|
|
345
199
|
}
|
|
346
200
|
```
|
|
347
|
-
**Note:** `acp-registry` reads `api-keys.json` via its config. The default
|
|
348
|
-
`apiKeysPath` is `./api-keys.json`. You can pass a custom config file as the third
|
|
349
|
-
arg to `launch acp-registry`.
|
|
350
201
|
|
|
351
|
-
|
|
352
|
-
```json
|
|
353
|
-
{
|
|
354
|
-
"pools": [
|
|
355
|
-
{
|
|
356
|
-
"id": "acp-worker",
|
|
357
|
-
"command": "npx",
|
|
358
|
-
"args": [
|
|
359
|
-
"@stdiobus/workers-registry",
|
|
360
|
-
"acp-worker"
|
|
361
|
-
],
|
|
362
|
-
"instances": 2
|
|
363
|
-
},
|
|
364
|
-
{
|
|
365
|
-
"id": "echo-worker",
|
|
366
|
-
"command": "npx",
|
|
367
|
-
"args": [
|
|
368
|
-
"@stdiobus/workers-registry",
|
|
369
|
-
"echo-worker"
|
|
370
|
-
],
|
|
371
|
-
"instances": 1
|
|
372
|
-
}
|
|
373
|
-
]
|
|
374
|
-
}
|
|
375
|
-
```
|
|
202
|
+
Swap `"acp-registry"` for any worker name. Scale with `"instances": N`.
|
|
376
203
|
|
|
377
|
-
###
|
|
204
|
+
### Worker-Specific Configuration
|
|
378
205
|
|
|
379
|
-
|
|
206
|
+
| Worker | Requirements |
|
|
207
|
+
|--------|-------------|
|
|
208
|
+
| `acp-registry` | `api-keys.json` in working directory (or custom config with `apiKeysPath`) |
|
|
209
|
+
| `openai-agent` | `OPENAI_API_KEY` env var or OAuth login |
|
|
210
|
+
| `mcp-to-acp-proxy` | `ACP_HOST`, `ACP_PORT`, `AGENT_ID` env vars |
|
|
211
|
+
|
|
212
|
+
### Limits (optional)
|
|
380
213
|
|
|
381
214
|
```json
|
|
382
215
|
{
|
|
383
|
-
"
|
|
384
|
-
"
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
"env": {
|
|
391
|
-
"ACP_HOST": "localhost",
|
|
392
|
-
"ACP_PORT": "9000",
|
|
393
|
-
"AGENT_ID": "claude-acp"
|
|
394
|
-
}
|
|
395
|
-
}
|
|
216
|
+
"limits": {
|
|
217
|
+
"max_input_buffer": 1048576,
|
|
218
|
+
"max_output_queue": 4194304,
|
|
219
|
+
"max_restarts": 5,
|
|
220
|
+
"restart_window_sec": 60,
|
|
221
|
+
"drain_timeout_sec": 30,
|
|
222
|
+
"backpressure_timeout_sec": 60
|
|
396
223
|
}
|
|
397
224
|
}
|
|
398
225
|
```
|
|
399
226
|
|
|
400
|
-
|
|
401
|
-
ACP Registry agents. `acp-worker` is a standalone agent and will not route to the registry.
|
|
402
|
-
|
|
403
|
-
---
|
|
404
|
-
|
|
405
|
-
## Worker Documentation
|
|
406
|
-
|
|
407
|
-
### ACP Worker
|
|
408
|
-
|
|
409
|
-
Full implementation of the Agent Client Protocol using the official `@agentclientprotocol/sdk`.
|
|
410
|
-
|
|
411
|
-
**Location:** `workers-registry/acp-worker/`
|
|
412
|
-
|
|
413
|
-
**Features:**
|
|
414
|
-
- Complete ACP protocol support (initialize, session management, prompts)
|
|
415
|
-
- MCP server integration for tool execution
|
|
416
|
-
- Session-based routing
|
|
417
|
-
- Graceful shutdown handling
|
|
418
|
-
|
|
419
|
-
**Build:**
|
|
420
|
-
```bash
|
|
421
|
-
cd workers-registry/acp-worker
|
|
422
|
-
npm install
|
|
423
|
-
npm run build
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
**Run with stdio Bus:**
|
|
427
|
-
|
|
428
|
-
Using Docker:
|
|
429
|
-
```bash
|
|
430
|
-
docker run \
|
|
431
|
-
--name stdiobus-acp \
|
|
432
|
-
-p 9000:9000 \
|
|
433
|
-
-v $(pwd):/stdiobus:ro \
|
|
434
|
-
-v $(pwd)/workers-registry/acp-worker/acp-worker-config.json:/config.json:ro \
|
|
435
|
-
stdiobus/stdiobus:latest \
|
|
436
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
437
|
-
```
|
|
438
|
-
|
|
439
|
-
Using binary:
|
|
440
|
-
```bash
|
|
441
|
-
./stdio_bus --config workers-registry/acp-worker/acp-worker-config.json --tcp 0.0.0.0:9000
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
**Configuration:** See `workers-registry/acp-worker/src/` for implementation details.
|
|
227
|
+
See [stdio Bus documentation](https://stdiobus.com) for full configuration reference.
|
|
445
228
|
|
|
446
229
|
---
|
|
447
230
|
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
Routes messages to any agent in the [ACP Registry](https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json).
|
|
231
|
+
## Package API
|
|
451
232
|
|
|
452
|
-
|
|
233
|
+
### Exports
|
|
453
234
|
|
|
454
|
-
|
|
235
|
+
```javascript
|
|
236
|
+
// Default export — ACP Worker
|
|
237
|
+
import worker from '@stdiobus/workers-registry';
|
|
455
238
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
239
|
+
// Individual workers
|
|
240
|
+
import acpWorker from '@stdiobus/workers-registry/workers/acp-worker';
|
|
241
|
+
import openaiAgent from '@stdiobus/workers-registry/workers/openai-agent';
|
|
242
|
+
import echoWorker from '@stdiobus/workers-registry/workers/echo-worker';
|
|
243
|
+
import mcpEchoServer from '@stdiobus/workers-registry/workers/mcp-echo-server';
|
|
244
|
+
import mcpToAcpProxy from '@stdiobus/workers-registry/workers/mcp-to-acp-proxy';
|
|
461
245
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
- `github-copilot` - GitHub Copilot
|
|
467
|
-
- And many more from the registry
|
|
246
|
+
// Registry Launcher (programmatic access)
|
|
247
|
+
import registryLauncher from '@stdiobus/workers-registry/workers/registry-launcher';
|
|
248
|
+
import { resolveRegistry } from '@stdiobus/workers-registry/workers/registry-launcher/registry';
|
|
249
|
+
import { RuntimeManager } from '@stdiobus/workers-registry/workers/registry-launcher/runtime';
|
|
468
250
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
{
|
|
472
|
-
"pools": [
|
|
473
|
-
{
|
|
474
|
-
"id": "acp-registry",
|
|
475
|
-
"command": "npx",
|
|
476
|
-
"args": [
|
|
477
|
-
"@stdiobus/workers-registry",
|
|
478
|
-
"acp-registry"
|
|
479
|
-
],
|
|
480
|
-
"instances": 1
|
|
481
|
-
}
|
|
482
|
-
]
|
|
483
|
-
}
|
|
251
|
+
// Workers metadata
|
|
252
|
+
import { workers } from '@stdiobus/workers-registry/workers';
|
|
484
253
|
```
|
|
485
|
-
**Note:** `acp-registry` uses its default config when no path is provided. You can
|
|
486
|
-
pass a custom config file as the third arg to `launch acp-registry`. The default
|
|
487
|
-
file in this repo is `workers-registry/acp-registry/acp-registry-config.json`, which
|
|
488
|
-
expects `api-keys.json` at `./api-keys.json` unless you override `apiKeysPath`.
|
|
489
254
|
|
|
490
|
-
|
|
255
|
+
### TypeScript
|
|
491
256
|
|
|
492
|
-
|
|
493
|
-
```bash
|
|
494
|
-
docker run \
|
|
495
|
-
--name stdiobus-registry \
|
|
496
|
-
-p 9000:9000 \
|
|
497
|
-
-v $(pwd):/stdiobus:ro \
|
|
498
|
-
-v $(pwd)/workers-registry/acp-registry/acp-registry-config.json:/config.json:ro \
|
|
499
|
-
-v $(pwd)/api-keys.json:/api-keys.json:ro \
|
|
500
|
-
stdiobus/stdiobus:latest \
|
|
501
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
502
|
-
```
|
|
257
|
+
Full type definitions included. Strict mode.
|
|
503
258
|
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
259
|
+
```typescript
|
|
260
|
+
import type { ACPAgent } from '@stdiobus/workers-registry/workers/acp-worker';
|
|
261
|
+
import type { MCPServer } from '@stdiobus/workers-registry/workers/mcp-echo-server';
|
|
507
262
|
```
|
|
508
263
|
|
|
509
264
|
---
|
|
510
265
|
|
|
511
|
-
|
|
266
|
+
## IDE Integration (MCP Client)
|
|
512
267
|
|
|
513
|
-
|
|
268
|
+
Connect your IDE to ACP agents via the MCP-to-ACP proxy:
|
|
514
269
|
|
|
515
|
-
**Location:** `workers-registry/mcp-to-acp-proxy/`
|
|
516
|
-
|
|
517
|
-
**Architecture:**
|
|
518
|
-
```
|
|
519
|
-
IDE (MCP Client) → MCP-to-ACP Proxy → stdio Bus → ACP Registry Worker (acp-registry) → ACP Agent
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
**Configuration for IDE:**
|
|
523
270
|
```json
|
|
524
271
|
{
|
|
525
272
|
"mcpServers": {
|
|
526
273
|
"stdio-bus-acp": {
|
|
527
274
|
"command": "npx",
|
|
528
|
-
"args": [
|
|
529
|
-
"@stdiobus/workers-registry",
|
|
530
|
-
"mcp-to-acp-proxy"
|
|
531
|
-
],
|
|
275
|
+
"args": ["@stdiobus/workers-registry", "mcp-to-acp-proxy"],
|
|
532
276
|
"env": {
|
|
533
|
-
"ACP_HOST": "
|
|
277
|
+
"ACP_HOST": "localhost",
|
|
534
278
|
"ACP_PORT": "9000",
|
|
535
279
|
"AGENT_ID": "claude-acp"
|
|
536
280
|
}
|
|
@@ -539,505 +283,79 @@ IDE (MCP Client) → MCP-to-ACP Proxy → stdio Bus → ACP Registry Worker (acp
|
|
|
539
283
|
}
|
|
540
284
|
```
|
|
541
285
|
|
|
542
|
-
|
|
286
|
+
Requires `acp-registry` running on the stdio Bus side to resolve `AGENT_ID` to real agents.
|
|
543
287
|
|
|
544
288
|
---
|
|
545
289
|
|
|
546
|
-
|
|
290
|
+
## Authentication
|
|
547
291
|
|
|
548
|
-
|
|
292
|
+
Registry Launcher supports two authentication methods:
|
|
549
293
|
|
|
550
|
-
|
|
294
|
+
### API Keys
|
|
551
295
|
|
|
552
|
-
|
|
553
|
-
- Testing stdio Bus kernel functionality
|
|
554
|
-
- Reference implementation for custom workers
|
|
555
|
-
- Protocol documentation through code
|
|
296
|
+
Create `api-keys.json` in your working directory:
|
|
556
297
|
|
|
557
|
-
**Run standalone:**
|
|
558
|
-
```bash
|
|
559
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{"foo":"bar"}}' | node workers-registry/echo-worker/echo-worker.js
|
|
560
|
-
```
|
|
561
|
-
|
|
562
|
-
**Run with stdio Bus:**
|
|
563
|
-
|
|
564
|
-
Using Docker:
|
|
565
|
-
```bash
|
|
566
|
-
docker run \
|
|
567
|
-
--name stdiobus-echo \
|
|
568
|
-
-p 9000:9000 \
|
|
569
|
-
-v $(pwd):/stdiobus:ro \
|
|
570
|
-
-v $(pwd)/workers-registry/echo-worker/echo-worker-config.json:/config.json:ro \
|
|
571
|
-
stdiobus/stdiobus:latest \
|
|
572
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
573
|
-
```
|
|
574
|
-
|
|
575
|
-
Using binary:
|
|
576
|
-
```bash
|
|
577
|
-
./stdio_bus --config workers-registry/echo-worker/echo-worker-config.json --tcp 0.0.0.0:9000
|
|
578
|
-
```
|
|
579
|
-
|
|
580
|
-
---
|
|
581
|
-
|
|
582
|
-
### MCP Echo Server
|
|
583
|
-
|
|
584
|
-
TypeScript MCP server example for testing MCP integration.
|
|
585
|
-
|
|
586
|
-
**Location:** `workers-registry/mcp-echo-server/`
|
|
587
|
-
|
|
588
|
-
**Tools provided:**
|
|
589
|
-
- `echo` - Echoes input text
|
|
590
|
-
- `reverse` - Reverses input text
|
|
591
|
-
- `uppercase` - Converts to uppercase
|
|
592
|
-
- `delay` - Echoes after a delay (for testing cancellation)
|
|
593
|
-
- `error` - Always returns an error (for testing error handling)
|
|
594
|
-
|
|
595
|
-
**Build:**
|
|
596
|
-
```bash
|
|
597
|
-
cd workers-registry/mcp-echo-server
|
|
598
|
-
npm install
|
|
599
|
-
npm run build
|
|
600
|
-
```
|
|
601
|
-
|
|
602
|
-
**Run:**
|
|
603
|
-
```bash
|
|
604
|
-
node workers-registry/mcp-echo-server/dist/index.js
|
|
605
|
-
```
|
|
606
|
-
|
|
607
|
-
---
|
|
608
|
-
|
|
609
|
-
## stdio Bus Configuration
|
|
610
|
-
|
|
611
|
-
stdio Bus kernel is configured via JSON files. This repository includes example configurations for each worker.
|
|
612
|
-
|
|
613
|
-
### Configuration File Structure
|
|
614
|
-
|
|
615
|
-
```json
|
|
616
|
-
{
|
|
617
|
-
"pools": [
|
|
618
|
-
{
|
|
619
|
-
"id": "worker-id",
|
|
620
|
-
"command": "/path/to/executable",
|
|
621
|
-
"args": ["arg1", "arg2"],
|
|
622
|
-
"instances": 1
|
|
623
|
-
}
|
|
624
|
-
],
|
|
625
|
-
"limits": {
|
|
626
|
-
"max_input_buffer": 1048576,
|
|
627
|
-
"max_output_queue": 4194304,
|
|
628
|
-
"max_restarts": 5,
|
|
629
|
-
"restart_window_sec": 60,
|
|
630
|
-
"drain_timeout_sec": 30,
|
|
631
|
-
"backpressure_timeout_sec": 60
|
|
632
|
-
}
|
|
633
|
-
}
|
|
634
|
-
```
|
|
635
|
-
|
|
636
|
-
### Pool Configuration
|
|
637
|
-
|
|
638
|
-
| Field | Type | Required | Description |
|
|
639
|
-
|-------|------|----------|-------------|
|
|
640
|
-
| `id` | string | Yes | Unique identifier for this worker pool |
|
|
641
|
-
| `command` | string | Yes | Path to the executable |
|
|
642
|
-
| `args` | string[] | No | Command-line arguments |
|
|
643
|
-
| `instances` | number | Yes | Number of worker instances (≥ 1) |
|
|
644
|
-
|
|
645
|
-
### Limits Configuration
|
|
646
|
-
|
|
647
|
-
| Field | Type | Default | Description |
|
|
648
|
-
|-------|------|---------|-------------|
|
|
649
|
-
| `max_input_buffer` | number | 1048576 (1 MB) | Maximum input buffer size per connection |
|
|
650
|
-
| `max_output_queue` | number | 4194304 (4 MB) | Maximum output queue size per connection |
|
|
651
|
-
| `max_restarts` | number | 5 | Maximum worker restarts within restart window |
|
|
652
|
-
| `restart_window_sec` | number | 60 | Time window for counting restarts |
|
|
653
|
-
| `drain_timeout_sec` | number | 30 | Timeout for graceful shutdown |
|
|
654
|
-
| `backpressure_timeout_sec` | number | 60 | Timeout before closing connection when queue is full |
|
|
655
|
-
|
|
656
|
-
### Example Configurations
|
|
657
|
-
|
|
658
|
-
**Minimal Configuration:**
|
|
659
|
-
```json
|
|
660
|
-
{
|
|
661
|
-
"pools": [{
|
|
662
|
-
"id": "echo-worker",
|
|
663
|
-
"command": "npx",
|
|
664
|
-
"args": [
|
|
665
|
-
"@stdiobus/workers-registry",
|
|
666
|
-
"echo-worker"
|
|
667
|
-
],
|
|
668
|
-
"instances": 1
|
|
669
|
-
}]
|
|
670
|
-
}
|
|
671
|
-
```
|
|
672
|
-
|
|
673
|
-
**High-Throughput Configuration:**
|
|
674
|
-
```json
|
|
675
|
-
{
|
|
676
|
-
"pools": [
|
|
677
|
-
{
|
|
678
|
-
"id": "acp-worker",
|
|
679
|
-
"command": "npx",
|
|
680
|
-
"args": [
|
|
681
|
-
"@stdiobus/workers-registry",
|
|
682
|
-
"acp-worker"
|
|
683
|
-
],
|
|
684
|
-
"instances": 4
|
|
685
|
-
}
|
|
686
|
-
],
|
|
687
|
-
"limits": {
|
|
688
|
-
"max_input_buffer": 4194304,
|
|
689
|
-
"max_output_queue": 16777216,
|
|
690
|
-
"backpressure_timeout_sec": 120
|
|
691
|
-
}
|
|
692
|
-
}
|
|
693
|
-
```
|
|
694
|
-
|
|
695
|
-
**Multiple Worker Pools:**
|
|
696
298
|
```json
|
|
697
299
|
{
|
|
698
|
-
"
|
|
699
|
-
|
|
700
|
-
"id": "acp-worker",
|
|
701
|
-
"command": "npx",
|
|
702
|
-
"args": [
|
|
703
|
-
"@stdiobus/workers-registry",
|
|
704
|
-
"acp-worker"
|
|
705
|
-
],
|
|
706
|
-
"instances": 2
|
|
707
|
-
},
|
|
708
|
-
{
|
|
709
|
-
"id": "echo-worker",
|
|
710
|
-
"command": "npx",
|
|
711
|
-
"args": [
|
|
712
|
-
"@stdiobus/workers-registry",
|
|
713
|
-
"echo-worker"
|
|
714
|
-
],
|
|
715
|
-
"instances": 1
|
|
716
|
-
}
|
|
717
|
-
]
|
|
300
|
+
"claude-acp": { "apiKey": "sk-ant-..." },
|
|
301
|
+
"openai-agent": { "apiKey": "sk-..." }
|
|
718
302
|
}
|
|
719
303
|
```
|
|
720
304
|
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
## NDJSON Protocol
|
|
724
|
-
|
|
725
|
-
Workers communicate with stdio Bus kernel via stdin/stdout using NDJSON (Newline-Delimited JSON).
|
|
726
|
-
|
|
727
|
-
### Protocol Rules
|
|
728
|
-
|
|
729
|
-
1. **Input (stdin):** stdio Bus sends JSON-RPC messages, one per line
|
|
730
|
-
2. **Output (stdout):** Workers write JSON-RPC responses, one per line
|
|
731
|
-
3. **Errors (stderr):** All logging and debug output goes to stderr
|
|
732
|
-
4. **Never write non-JSON to stdout** - it will break the protocol
|
|
733
|
-
|
|
734
|
-
### Message Types
|
|
735
|
-
|
|
736
|
-
**Request** (requires response):
|
|
737
|
-
```json
|
|
738
|
-
{"jsonrpc":"2.0","id":"1","method":"test","params":{"foo":"bar"}}
|
|
739
|
-
```
|
|
740
|
-
|
|
741
|
-
**Response:**
|
|
742
|
-
```json
|
|
743
|
-
{"jsonrpc":"2.0","id":"1","result":{"status":"ok"}}
|
|
744
|
-
```
|
|
745
|
-
|
|
746
|
-
**Notification** (no response):
|
|
747
|
-
```json
|
|
748
|
-
{"jsonrpc":"2.0","method":"notify","params":{"event":"started"}}
|
|
749
|
-
```
|
|
750
|
-
|
|
751
|
-
### Session Affinity
|
|
752
|
-
|
|
753
|
-
Messages with the same `sessionId` are routed to the same worker instance:
|
|
754
|
-
|
|
755
|
-
```json
|
|
756
|
-
{"jsonrpc":"2.0","id":"1","method":"test","sessionId":"sess-123","params":{}}
|
|
757
|
-
```
|
|
758
|
-
|
|
759
|
-
Workers must preserve `sessionId` in responses for proper routing.
|
|
760
|
-
|
|
761
|
-
### Graceful Shutdown
|
|
762
|
-
|
|
763
|
-
Workers must handle SIGTERM for graceful shutdown:
|
|
764
|
-
1. Stop accepting new messages
|
|
765
|
-
2. Complete in-flight processing
|
|
766
|
-
3. Exit with code 0
|
|
767
|
-
|
|
768
|
-
stdio Bus sends SIGTERM during shutdown or worker restarts.
|
|
769
|
-
|
|
770
|
-
---
|
|
771
|
-
|
|
772
|
-
## Testing
|
|
773
|
-
|
|
774
|
-
### Unit Tests
|
|
775
|
-
|
|
776
|
-
```bash
|
|
777
|
-
# Run all tests
|
|
778
|
-
npm test
|
|
779
|
-
|
|
780
|
-
# Run specific test suites
|
|
781
|
-
npm run test:unit
|
|
782
|
-
npm run test:integration
|
|
783
|
-
npm run test:property
|
|
784
|
-
```
|
|
785
|
-
|
|
786
|
-
### Manual Testing
|
|
787
|
-
|
|
788
|
-
**Test echo worker:**
|
|
789
|
-
```bash
|
|
790
|
-
# Start stdio Bus with Docker
|
|
791
|
-
docker run \
|
|
792
|
-
--name stdiobus-test \
|
|
793
|
-
-p 9000:9000 \
|
|
794
|
-
-v $(pwd):/stdiobus:ro \
|
|
795
|
-
-v $(pwd)/workers-registry/echo-worker/echo-worker-config.json:/config.json:ro \
|
|
796
|
-
stdiobus/stdiobus:latest \
|
|
797
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
798
|
-
|
|
799
|
-
# Send test message
|
|
800
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"echo","params":{"test":true}}' | nc localhost 9000
|
|
801
|
-
|
|
802
|
-
# Cleanup
|
|
803
|
-
docker stop stdiobus-test && docker rm stdiobus-test
|
|
804
|
-
```
|
|
805
|
-
|
|
806
|
-
**Test ACP worker:**
|
|
807
|
-
```bash
|
|
808
|
-
# Start stdio Bus with ACP worker
|
|
809
|
-
docker run \
|
|
810
|
-
--name stdiobus-acp-test \
|
|
811
|
-
-p 9000:9000 \
|
|
812
|
-
-v $(pwd):/stdiobus:ro \
|
|
813
|
-
-v $(pwd)/workers-registry/acp-worker/acp-worker-config.json:/config.json:ro \
|
|
814
|
-
stdiobus/stdiobus:latest \
|
|
815
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
816
|
-
|
|
817
|
-
# Send initialize request
|
|
818
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' | nc localhost 9000
|
|
819
|
-
|
|
820
|
-
# Cleanup
|
|
821
|
-
docker stop stdiobus-acp-test && docker rm stdiobus-acp-test
|
|
822
|
-
```
|
|
305
|
+
### OAuth 2.1 with PKCE
|
|
823
306
|
|
|
824
|
-
**Test ACP Registry Worker – acp-registry:**
|
|
825
307
|
```bash
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
-p 9000:9000 \
|
|
830
|
-
-v $(pwd):/stdiobus:ro \
|
|
831
|
-
-v $(pwd)/workers-registry/acp-registry/acp-registry-config.json:/config.json:ro \
|
|
832
|
-
-v $(pwd)/api-keys.json:/api-keys.json:ro \
|
|
833
|
-
stdiobus/stdiobus:latest \
|
|
834
|
-
--config /config.json --tcp 0.0.0.0:9000
|
|
835
|
-
|
|
836
|
-
# Send message with agentId
|
|
837
|
-
echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"agentId":"claude-acp","clientInfo":{"name":"test"}}}' | nc localhost 9000
|
|
838
|
-
|
|
839
|
-
# Cleanup
|
|
840
|
-
docker stop stdiobus-registry-test && docker rm stdiobus-registry-test
|
|
841
|
-
```
|
|
842
|
-
|
|
843
|
-
---
|
|
844
|
-
|
|
845
|
-
## Development
|
|
846
|
-
|
|
847
|
-
### Creating a Custom Worker
|
|
848
|
-
|
|
849
|
-
1. Workers must read NDJSON from stdin and write NDJSON to stdout
|
|
850
|
-
2. All logging goes to stderr
|
|
851
|
-
3. Handle SIGTERM for graceful shutdown
|
|
852
|
-
4. Preserve `sessionId` in responses when present in requests
|
|
853
|
-
|
|
854
|
-
**Minimal worker template (Node.js):**
|
|
855
|
-
|
|
856
|
-
```javascript
|
|
857
|
-
#!/usr/bin/env node
|
|
858
|
-
import readline from 'readline';
|
|
859
|
-
|
|
860
|
-
const rl = readline.createInterface({
|
|
861
|
-
input: process.stdin,
|
|
862
|
-
output: process.stdout,
|
|
863
|
-
terminal: false
|
|
864
|
-
});
|
|
865
|
-
|
|
866
|
-
rl.on('line', (line) => {
|
|
867
|
-
try {
|
|
868
|
-
const msg = JSON.parse(line);
|
|
869
|
-
|
|
870
|
-
if (msg.id !== undefined) {
|
|
871
|
-
// Request - send response
|
|
872
|
-
const response = {
|
|
873
|
-
jsonrpc: '2.0',
|
|
874
|
-
id: msg.id,
|
|
875
|
-
result: { /* your result */ }
|
|
876
|
-
};
|
|
877
|
-
|
|
878
|
-
if (msg.sessionId) {
|
|
879
|
-
response.sessionId = msg.sessionId;
|
|
880
|
-
}
|
|
881
|
-
|
|
882
|
-
console.log(JSON.stringify(response));
|
|
883
|
-
}
|
|
884
|
-
} catch (err) {
|
|
885
|
-
console.error('Parse error:', err.message);
|
|
886
|
-
}
|
|
887
|
-
});
|
|
888
|
-
|
|
889
|
-
process.on('SIGTERM', () => {
|
|
890
|
-
console.error('Shutting down...');
|
|
891
|
-
rl.close();
|
|
892
|
-
});
|
|
893
|
-
|
|
894
|
-
rl.on('close', () => process.exit(0));
|
|
895
|
-
```
|
|
896
|
-
|
|
897
|
-
### Project Structure
|
|
898
|
-
|
|
899
|
-
```
|
|
900
|
-
workers-registry/
|
|
901
|
-
├── index.ts # Package entry point
|
|
902
|
-
├── launch/ # Universal launcher (npx entry point)
|
|
903
|
-
├── acp-worker/ # Full ACP protocol implementation
|
|
904
|
-
│ ├── src/
|
|
905
|
-
│ │ ├── agent.ts # ACP Agent implementation
|
|
906
|
-
│ │ ├── index.ts # Main entry point
|
|
907
|
-
│ │ ├── acp/ # ACP protocol layer
|
|
908
|
-
│ │ ├── mcp/ # MCP server integration
|
|
909
|
-
│ │ ├── mcp-proxy/ # MCP-to-ACP proxy logic
|
|
910
|
-
│ │ ├── session/ # Session management
|
|
911
|
-
│ │ ├── stdio/ # Session ID routing
|
|
912
|
-
│ │ └── test-utils/ # Testing utilities
|
|
913
|
-
│ └── tests/ # Test suites
|
|
914
|
-
├── registry-launcher/ # Registry Launcher (agent discovery + routing)
|
|
915
|
-
│ └── src/
|
|
916
|
-
│ ├── auth/ # OAuth 2.1 authentication
|
|
917
|
-
│ ├── config/ # Configuration management
|
|
918
|
-
│ ├── registry/ # ACP Registry resolution
|
|
919
|
-
│ ├── router/ # Message routing
|
|
920
|
-
│ ├── runtime/ # Agent runtime management
|
|
921
|
-
│ ├── stream/ # NDJSON stream handling
|
|
922
|
-
│ └── test-utils/ # Testing utilities
|
|
923
|
-
├── openai-agent/ # OpenAI Chat Completions API agent
|
|
924
|
-
│ └── src/
|
|
925
|
-
│ ├── agent.ts # ACP Agent bridging to OpenAI API
|
|
926
|
-
│ ├── client.ts # Chat Completions HTTP + SSE client
|
|
927
|
-
│ ├── sse-parser.ts # SSE line parser
|
|
928
|
-
│ ├── session.ts # Session state management
|
|
929
|
-
│ └── config.ts # Environment-based configuration
|
|
930
|
-
├── acp-registry/ # ACP Registry worker entrypoint + configs
|
|
931
|
-
├── echo-worker/ # Simple echo worker example
|
|
932
|
-
├── mcp-echo-server/ # MCP server example
|
|
933
|
-
└── mcp-to-acp-proxy/ # MCP-to-ACP protocol bridge
|
|
308
|
+
npx @stdiobus/workers-registry acp-registry --login openai
|
|
309
|
+
npx @stdiobus/workers-registry acp-registry --auth-status
|
|
310
|
+
npx @stdiobus/workers-registry acp-registry --logout
|
|
934
311
|
```
|
|
935
312
|
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
## API Reference
|
|
939
|
-
|
|
940
|
-
### Package Exports
|
|
313
|
+
Supported providers: OpenAI, Anthropic, GitHub, Google, Azure AD, AWS Cognito.
|
|
941
314
|
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
```javascript
|
|
945
|
-
// Default export - ACP Worker
|
|
946
|
-
import worker from '@stdiobus/workers-registry';
|
|
947
|
-
|
|
948
|
-
// Named exports for specific workers
|
|
949
|
-
import {
|
|
950
|
-
acpWorker,
|
|
951
|
-
echoWorker,
|
|
952
|
-
mcpEchoServer,
|
|
953
|
-
mcpToAcpProxy,
|
|
954
|
-
workers // Metadata object
|
|
955
|
-
} from '@stdiobus/workers-registry/workers';
|
|
956
|
-
```
|
|
315
|
+
OAuth takes precedence when available, with automatic fallback to API keys. For headless/CI environments, use API keys or environment variables.
|
|
957
316
|
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
**MCP-to-ACP Proxy:**
|
|
961
|
-
- `ACP_HOST` - stdio Bus host (default: `localhost`)
|
|
962
|
-
- `ACP_PORT` - stdio Bus port (default: `9000`)
|
|
963
|
-
- `AGENT_ID` - Target agent ID (e.g., `claude-acp`)
|
|
317
|
+
See [OAuth documentation](docs/oauth/user-guide.md) for details.
|
|
964
318
|
|
|
965
319
|
---
|
|
966
320
|
|
|
967
|
-
##
|
|
968
|
-
|
|
969
|
-
This package follows [Semantic Versioning](https://semver.org/):
|
|
321
|
+
## Deployment Modes
|
|
970
322
|
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
323
|
+
| Mode | Package | Infrastructure | Use case |
|
|
324
|
+
|------|---------|---------------|----------|
|
|
325
|
+
| **Embedded** | `@stdiobus/node` + this package | None | Applications, scripts, testing |
|
|
326
|
+
| **Docker** | This package (mounted) | `stdiobus/stdiobus` container | Production, multi-worker setups |
|
|
327
|
+
| **Binary** | This package (on disk) | `stdio_bus` binary | Custom deployments |
|
|
974
328
|
|
|
975
|
-
|
|
329
|
+
All modes use the same worker configs and the same `npx @stdiobus/workers-registry <worker>` command.
|
|
976
330
|
|
|
977
331
|
---
|
|
978
332
|
|
|
979
333
|
## Troubleshooting
|
|
980
334
|
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
**Permission errors:**
|
|
990
|
-
```bash
|
|
991
|
-
npm install -g @stdiobus/workers-registry # Global install (may need sudo)
|
|
992
|
-
# Or use npx
|
|
993
|
-
npx @stdiobus/workers-registry acp-worker
|
|
994
|
-
```
|
|
995
|
-
|
|
996
|
-
### Runtime Issues
|
|
997
|
-
|
|
998
|
-
**Command not found:**
|
|
999
|
-
```bash
|
|
1000
|
-
# Verify installation
|
|
1001
|
-
npm list @stdiobus/workers-registry
|
|
1002
|
-
|
|
1003
|
-
```
|
|
1004
|
-
|
|
1005
|
-
**Worker crashes:**
|
|
1006
|
-
```bash
|
|
1007
|
-
# Check stdio Bus logs
|
|
1008
|
-
docker logs <container-name>
|
|
335
|
+
| Problem | Solution |
|
|
336
|
+
|---------|----------|
|
|
337
|
+
| `node: command not found` or version < 20 | Install Node.js ≥ 20 (`nvm install 20`) |
|
|
338
|
+
| Worker crashes on start | Check stderr output; verify config JSON is valid |
|
|
339
|
+
| `acp-registry` fails to route | Ensure `api-keys.json` exists with valid keys |
|
|
340
|
+
| Connection refused on port 9000 | Verify stdio Bus kernel is running (`docker ps`) |
|
|
341
|
+
| MCP proxy can't reach agent | Check `ACP_HOST`/`ACP_PORT` env vars point to running kernel |
|
|
1009
342
|
|
|
1010
|
-
|
|
1011
|
-
{
|
|
1012
|
-
"limits": {
|
|
1013
|
-
"max_restarts": 10,
|
|
1014
|
-
"restart_window_sec": 120
|
|
1015
|
-
}
|
|
1016
|
-
}
|
|
1017
|
-
```
|
|
343
|
+
---
|
|
1018
344
|
|
|
1019
|
-
|
|
1020
|
-
```bash
|
|
1021
|
-
# Verify stdio Bus is running
|
|
1022
|
-
netstat -an | grep 9000
|
|
345
|
+
## Documentation
|
|
1023
346
|
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
347
|
+
- [stdio Bus kernel](https://github.com/stdiobus/stdiobus) — Core daemon (source code)
|
|
348
|
+
- [`@stdiobus/node`](https://www.npmjs.com/package/@stdiobus/node) — Embedded Node.js binding
|
|
349
|
+
- [stdio Bus on Docker Hub](https://hub.docker.com/r/stdiobus/stdiobus) — Docker images
|
|
350
|
+
- [Full documentation](https://stdiobus.com) — Protocol reference, guides, examples
|
|
351
|
+
- [OAuth User Guide](docs/oauth/user-guide.md) — Authentication setup
|
|
352
|
+
- [OAuth CLI Reference](docs/oauth/cli-reference.md) — CLI commands
|
|
353
|
+
- [FAQ](docs/FAQ.md) — Frequently asked questions
|
|
1027
354
|
|
|
1028
355
|
---
|
|
1029
356
|
|
|
1030
357
|
## Contributing
|
|
1031
358
|
|
|
1032
|
-
Contributions are welcome! Please:
|
|
1033
|
-
|
|
1034
|
-
1. Fork the repository
|
|
1035
|
-
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
1036
|
-
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
1037
|
-
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
1038
|
-
5. Open a Pull Request
|
|
1039
|
-
|
|
1040
|
-
**Development setup:**
|
|
1041
359
|
```bash
|
|
1042
360
|
git clone https://github.com/stdiobus/workers-registry
|
|
1043
361
|
cd workers-registry
|
|
@@ -1046,120 +364,12 @@ npm run build
|
|
|
1046
364
|
npm test
|
|
1047
365
|
```
|
|
1048
366
|
|
|
1049
|
-
|
|
1050
|
-
- All tests pass (`npm test`)
|
|
1051
|
-
- Code follows existing style
|
|
1052
|
-
- Documentation is updated
|
|
1053
|
-
- Workers handle SIGTERM gracefully
|
|
1054
|
-
- No output to stdout except NDJSON protocol messages
|
|
1055
|
-
|
|
1056
|
-
---
|
|
1057
|
-
|
|
1058
|
-
## OAuth 2.1 Authentication
|
|
1059
|
-
|
|
1060
|
-
Registry Launcher supports OAuth 2.1 with PKCE for secure browser-based authentication with AI providers.
|
|
1061
|
-
|
|
1062
|
-
### Supported Providers
|
|
1063
|
-
|
|
1064
|
-
| Provider | OAuth 2.1 | API Key | Status |
|
|
1065
|
-
|----------|-----------|---------|--------|
|
|
1066
|
-
| OpenAI | ✓ | ✓ | Production |
|
|
1067
|
-
| Anthropic | ✓ | ✓ | Production |
|
|
1068
|
-
| GitHub | ✓ | ✓ | Production |
|
|
1069
|
-
| Google | ✓ | ✓ | Production |
|
|
1070
|
-
| Azure AD | ✓ | ✓ | Production |
|
|
1071
|
-
| AWS Cognito | ✓ | ✓ | Production |
|
|
1072
|
-
|
|
1073
|
-
### Quick Start
|
|
1074
|
-
|
|
1075
|
-
```bash
|
|
1076
|
-
# Check current authentication status
|
|
1077
|
-
npx @stdiobus/workers-registry acp-registry --auth-status
|
|
1078
|
-
|
|
1079
|
-
# Login with browser OAuth (opens browser)
|
|
1080
|
-
npx @stdiobus/workers-registry acp-registry --login openai
|
|
1081
|
-
|
|
1082
|
-
# Interactive setup wizard
|
|
1083
|
-
npx @stdiobus/workers-registry acp-registry --setup
|
|
1084
|
-
|
|
1085
|
-
# Logout from all providers
|
|
1086
|
-
npx @stdiobus/workers-registry acp-registry --logout
|
|
1087
|
-
```
|
|
1088
|
-
|
|
1089
|
-
### Backward Compatibility
|
|
1090
|
-
|
|
1091
|
-
Existing `api-keys.json` configuration continues to work. OAuth credentials take precedence when available, with automatic fallback to API keys.
|
|
1092
|
-
|
|
1093
|
-
**Feature Flag:** `AUTH_AUTO_OAUTH`
|
|
1094
|
-
- `false` (default): Only use OAuth if explicitly logged in via `--login`
|
|
1095
|
-
- `true`: Auto-trigger browser OAuth when agent requires it
|
|
1096
|
-
|
|
1097
|
-
### Headless/CI Environments
|
|
1098
|
-
|
|
1099
|
-
Browser OAuth is not available in headless environments (CI, SSH, Docker). Use one of these alternatives:
|
|
1100
|
-
|
|
1101
|
-
```bash
|
|
1102
|
-
# Option 1: Use api-keys.json
|
|
1103
|
-
echo '{"claude-acp":{"apiKey":"sk-..."}}' > api-keys.json
|
|
1104
|
-
|
|
1105
|
-
# Option 2: Use environment variables
|
|
1106
|
-
export ANTHROPIC_API_KEY=sk-...
|
|
1107
|
-
|
|
1108
|
-
# Option 3: Interactive setup (if TTY available)
|
|
1109
|
-
npx @stdiobus/workers-registry acp-registry --setup
|
|
1110
|
-
```
|
|
1111
|
-
|
|
1112
|
-
### Documentation
|
|
1113
|
-
|
|
1114
|
-
- [User Guide](docs/oauth/user-guide.md) - How to use OAuth authentication
|
|
1115
|
-
- [CLI Reference](docs/oauth/cli-reference.md) - Complete CLI command reference
|
|
1116
|
-
- [Configuration](docs/oauth/configuration.md) - Environment variables and settings
|
|
1117
|
-
- [Security](docs/oauth/security.md) - Security considerations and best practices
|
|
1118
|
-
- [Technical Reference](docs/oauth/technical-reference.md) - Architecture and internals
|
|
1119
|
-
- [Troubleshooting](docs/oauth/troubleshooting.md) - Common issues and solutions
|
|
1120
|
-
|
|
1121
|
-
---
|
|
1122
|
-
|
|
1123
|
-
## Resources
|
|
1124
|
-
|
|
1125
|
-
- [stdio Bus kernel](https://github.com/stdiobus/stdiobus) - Core protocol and daemon (source code)
|
|
1126
|
-
- [`@stdiobus/node`](https://www.npmjs.com/package/@stdiobus/node) - Embedded Node.js binding (no Docker/binary needed)
|
|
1127
|
-
- [stdio Bus on Docker Hub](https://hub.docker.com/r/stdiobus/stdiobus) - Docker images for easy deployment
|
|
1128
|
-
- [stdio Bus Full Documentation](https://stdiobus.com) – Core protocol documentation
|
|
1129
|
-
- [ACP Registry](https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json) - Available ACP agents
|
|
1130
|
-
- [Agent Client Protocol SDK](https://www.npmjs.com/package/@agentclientprotocol/sdk) - Official ACP SDK
|
|
1131
|
-
- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - Official MCP SDK
|
|
1132
|
-
- [npm package](https://www.npmjs.com/package/@stdiobus/workers-registry) - Package on npm registry
|
|
1133
|
-
|
|
1134
|
-
## Worker Documentation
|
|
1135
|
-
|
|
1136
|
-
- [ACP Worker](https://github.com/stdiobus/workers-registry/tree/main/workers-registry/acp-worker) - Full ACP protocol implementation
|
|
1137
|
-
- [ACP Registry Worker (acp-registry)](https://github.com/stdiobus/workers-registry/tree/main/workers-registry/acp-registry) - ACP Registry integration
|
|
1138
|
-
- [Echo Worker](https://github.com/stdiobus/workers-registry/tree/main/workers-registry/echo-worker) - Reference implementation
|
|
1139
|
-
- [MCP Echo Server](https://github.com/stdiobus/workers-registry/tree/main/workers-registry/mcp-echo-server) - MCP server example
|
|
1140
|
-
- [MCP-to-ACP Proxy](https://github.com/stdiobus/workers-registry/tree/main/workers-registry/mcp-to-acp-proxy) - Protocol bridge
|
|
1141
|
-
- [FAQ](https://github.com/stdiobus/workers-registry/blob/main/docs/FAQ.md) - Frequently asked questions
|
|
1142
|
-
|
|
1143
|
-
---
|
|
1144
|
-
|
|
1145
|
-
## Support
|
|
1146
|
-
|
|
1147
|
-
- **Issues:** [GitHub Issues](https://github.com/stdiobus/workers-registry/issues)
|
|
1148
|
-
- **Discussions:** [GitHub Discussions](https://github.com/stdiobus/workers-registry/discussions)
|
|
1149
|
-
- **Repository:** [github.com/stdiobus/workers-registry](https://github.com/stdiobus/workers-registry)
|
|
367
|
+
See [CONTRIBUTING.md](sandbox/CONTRIBUTING.md) for guidelines.
|
|
1150
368
|
|
|
1151
369
|
---
|
|
1152
370
|
|
|
1153
371
|
## License
|
|
1154
372
|
|
|
1155
|
-
Apache License 2.0
|
|
1156
|
-
|
|
1157
|
-
Copyright (c) 2025–present Raman Marozau, Target Insight Function.
|
|
1158
|
-
|
|
1159
|
-
See [LICENSE](https://github.com/stdiobus/workers-registry/blob/main/LICENSE) file for details.
|
|
1160
|
-
|
|
1161
|
-
---
|
|
1162
|
-
|
|
1163
|
-
## Changelog
|
|
373
|
+
Apache License 2.0 — Copyright (c) 2025–present Raman Marozau, [Target Insight Function](https://worktif.com).
|
|
1164
374
|
|
|
1165
|
-
See [
|
|
375
|
+
See [LICENSE](LICENSE) for details.
|
package/package.json
CHANGED