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