Add OpenAI Agent Worker (#4)

<h2>OpenAI Agent Worker</h2>
<h3>Summary</h3>
<p>Introduces a new ACP agent (<code>openai-agent</code>) that bridges
the Agent Client Protocol to any OpenAI Chat Completions API-compatible
endpoint. This enables stdio Bus users to interact with OpenAI, AWS
Bedrock, Azure OpenAI, Ollama, vLLM, LiteLLM, and other compatible
providers through a unified ACP interface.</p>
<h3>Motivation</h3>
<p>The stdio Bus Workers Registry currently supports agents from the ACP
Registry, but lacks a built-in way to connect to OpenAI-compatible APIs.
This PR fills that gap by providing a universal agent that works with
any <code>/chat/completions</code> endpoint.</p>
<h3>Changes</h3>
<p><strong>New Worker:
<code>workers-registry/openai-agent/</code></strong></p>
<ul>
<li>Full ACP protocol implementation (<code>initialize</code>,
<code>newSession</code>, <code>prompt</code>, <code>cancel</code>)</li>
<li>SSE streaming support for real-time token delivery</li>
<li>Per-session conversation history for multi-turn dialogues</li>
<li>Native <code>fetch()</code> for HTTP requests (zero external HTTP
dependencies)</li>
<li>Graceful shutdown with <code>AbortController</code> for in-flight
requests</li>
</ul>
<p><strong>Registry Launcher Enhancement</strong></p>
<ul>
<li>Added <code>--custom-agents</code> CLI argument and
<code>ACP_CUSTOM_AGENTS_PATH</code> env var support</li>
<li>Enables loading custom agent definitions from external JSON
files</li>
</ul>
<p><strong>Infrastructure</strong></p>
<ul>
<li>Registered <code>openai-agent</code> in <code>launch/index.ts</code>
for <code>npx @stdiobus/workers-registry openai-agent</code></li>
<li>Added exports to root <code>package.json</code></li>
</ul>
<h3>Configuration</h3>
<p>Environment variables:</p>

Variable | Default | Description
-- | -- | --
OPENAI_BASE_URL | https://api.openai.com/v1 | API endpoint
OPENAI_API_KEY | — | Authentication key
OPENAI_MODEL | gpt-4o | Model identifier
OPENAI_SYSTEM_PROMPT | — | Optional system prompt
OPENAI_MAX_TOKENS | — | Optional token limit
OPENAI_TEMPERATURE | — | Optional temperature


<h3>Testing</h3>
<ul>
<li>5 unit test suites covering config, session, SSE parsing, agent, and
client</li>
<li>6 property-based test suites (100+ iterations each) for protocol
invariants</li>
<li>All existing tests pass</li>
</ul>
<pre><code class="language-bash">cd workers-registry/openai-agent
&amp;&amp; npm test
</code></pre>
<h3>How to Verify</h3>
<ol>
<li><p>Build the worker:</p>
<pre><code class="language-bash">cd workers-registry/openai-agent
npm install &amp;&amp; npm run build
</code></pre>
</li>
<li><p>Test with a raw NDJSON message:</p>
<pre><code class="language-bash">export OPENAI_API_KEY="sk-..."
echo
'{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}'
| node dist/index.js
</code></pre>
</li>
</ol>
<h3>Breaking Changes</h3>
<p>None. This is an additive feature.</p>
<h3>Checklist</h3>
<ul>
<li><input checked="" disabled="" type="checkbox"> Code compiles
(<code>npm run build</code>)</li>
<li><input checked="" disabled="" type="checkbox"> Tests pass (<code>npm
test</code>)</li>
<li><input checked="" disabled="" type="checkbox"> Protocol compliance
(stdout = NDJSON only, stderr = logs)</li>
<li><input checked="" disabled="" type="checkbox"> Documentation added
(<code>README.md</code>)</li>
<li><input checked="" disabled="" type="checkbox"> No secrets in
code</li>
</ul>
</body></html>

Author: morozow

.gitignore

@@ -777,3 +777,4 @@ cython_debug/
 .idea/
 sandbox
 /launch/
+.ai

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@stdiobus/workers-registry",
-  "version": "1.4.6",
+  "version": "1.4.12",
   "description": "Worker implementations for stdio Bus kernel - ACP, MCP, and protocol bridges",
   "type": "module",
   "main": "./out/dist/workers-registry/acp-registry/index.js",
@@ -44,6 +44,10 @@
       "types": "./out/tsc/workers-registry/mcp-echo-server/index.d.ts"
     },
     "./workers/mcp-to-acp-proxy": "./out/dist/workers-registry/mcp-to-acp-proxy/proxy.js",
+    "./workers/openai-agent": {
+      "import": "./out/dist/workers-registry/openai-agent/index.js",
+      "types": "./out/tsc/workers-registry/openai-agent/src/index.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "bin": {

package.json

@@ -38,13 +38,14 @@ const __dirname = dirname(__filename);
 const DEFAULT_CONFIG_FILE = 'acp-registry-config.json';
 
 function ensureDefaultConfigArg() {
-  const hasExplicitConfig = process.argv.length > 2 && process.argv[2] && !process.argv[2].startsWith('-');
-  if (hasExplicitConfig) {
-    return;
-  }
+  const userArgs = process.argv.slice(2);
 
-  const defaultConfigPath = join(__dirname, DEFAULT_CONFIG_FILE);
-  process.argv.splice(2, 0, defaultConfigPath);
+  // Check if a positional config path was provided (first non-flag argument)
+  const hasExplicitConfig = userArgs.length > 0 && userArgs[0] && !userArgs[0].startsWith('-');
+  if (!hasExplicitConfig) {
+    const defaultConfigPath = join(__dirname, DEFAULT_CONFIG_FILE);
+    process.argv.splice(2, 0, defaultConfigPath);
+  }
 }
 
 ensureDefaultConfigArg();

workers-registry/acp-registry/index.js

@@ -21,7 +21,11 @@
     "agent",
     "protocol"
   ],
-  "author": "",
+  "author": {
+    "name": "Raman Marozau",
+    "email": "raman@worktif.com",
+    "url": "https://worktif.com"
+  },
   "license": "Apache-2.0",
   "engines": {
     "node": ">=18.0.0"

workers-registry/acp-worker/package.json

@@ -204,9 +204,11 @@ describe('Config Parsing Property Tests', () => {
       /**
        * Arbitrary for generating extra fields that should be ignored.
        */
+      const knownConfigKeys = ['registryUrl', 'apiKeysPath', 'shutdownTimeoutSec', 'customAgentsPath'];
+
       const extraFieldsArb = fc.dictionary(
         fc.string({ minLength: 1, maxLength: 20 }).filter(
-          (s) => s !== 'registryUrl' && s !== 'shutdownTimeoutSec',
+          (s) => !knownConfigKeys.includes(s),
         ),
         fc.jsonValue(),
       );
@@ -229,10 +231,7 @@ describe('Config Parsing Property Tests', () => {
 
             // Verify extra fields are not present in result
             const resultKeys = Object.keys(result);
-            const onlyKnownFields =
-              resultKeys.length === 2 &&
-              resultKeys.includes('registryUrl') &&
-              resultKeys.includes('shutdownTimeoutSec');
+            const onlyKnownFields = resultKeys.every((key) => knownConfigKeys.includes(key));
 
             return knownFieldsCorrect && onlyKnownFields;
           },

workers-registry/acp-worker/src/registry-launcher/config/config.property.test.ts

@@ -45,6 +45,11 @@ const ENV_REGISTRY_URL = 'ACP_REGISTRY_URL';
  */
 const ENV_API_KEYS_PATH = 'ACP_API_KEYS_PATH';
 
+/**
+ * Environment variable name for custom agents file path override.
+ */
+const ENV_CUSTOM_AGENTS_PATH = 'ACP_CUSTOM_AGENTS_PATH';
+
 /**
  * Log a warning message to stderr with ISO 8601 timestamp.
  * @param message - Warning message to log
@@ -116,6 +121,15 @@ function parseConfigObject(obj: unknown): LauncherConfig {
     }
   }
 
+  // Parse customAgentsPath
+  if ('customAgentsPath' in rawConfig) {
+    if (isNonEmptyString(rawConfig.customAgentsPath)) {
+      config.customAgentsPath = rawConfig.customAgentsPath;
+    } else {
+      logWarning('Config field "customAgentsPath" is not a valid string, ignoring');
+    }
+  }
+
   return config;
 }
 
@@ -129,6 +143,7 @@ function parseConfigObject(obj: unknown): LauncherConfig {
 function applyEnvironmentOverrides(config: LauncherConfig): LauncherConfig {
   const envRegistryUrl = process.env[ENV_REGISTRY_URL];
   const envApiKeysPath = process.env[ENV_API_KEYS_PATH];
+  const envCustomAgentsPath = process.env[ENV_CUSTOM_AGENTS_PATH];
 
   const overrides: Partial<LauncherConfig> = {};
 
@@ -140,6 +155,10 @@ function applyEnvironmentOverrides(config: LauncherConfig): LauncherConfig {
     overrides.apiKeysPath = envApiKeysPath;
   }
 
+  if (isNonEmptyString(envCustomAgentsPath)) {
+    overrides.customAgentsPath = envCustomAgentsPath;
+  }
+
   return {
     ...config,
     ...overrides,

workers-registry/acp-worker/src/registry-launcher/config/config.ts

@@ -31,6 +31,8 @@ export interface LauncherConfig {
   apiKeysPath: string;
   /** Agent shutdown timeout in seconds (default: 5) */
   shutdownTimeoutSec: number;
+  /** Path to custom agents JSON file (optional, loaded via --custom-agents CLI arg) */
+  customAgentsPath?: string;
 }
 
 /**

workers-registry/acp-worker/src/registry-launcher/config/types.ts

@@ -37,11 +37,11 @@
 
 import { loadConfig } from './config/config.js';
 import { loadApiKeys } from './config/api-keys.js';
-import { RegistryFetchError, RegistryIndex, RegistryParseError } from './registry/index.js';
+import { RegistryFetchError, RegistryIndex, RegistryParseError, CustomAgentsLoadError, loadCustomAgents } from './registry/index.js';
 import { NDJSONHandler } from './stream/ndjson-handler.js';
 import { AgentRuntimeManager } from './runtime/manager.js';
 import { MessageRouter } from './router/message-router.js';
-import { logError, logExit, logInfo } from './log.js';
+import { logError, logExit, logInfo, logWarn } from './log.js';
 
 /**
  * Exit codes for the Registry Launcher.
@@ -59,22 +59,53 @@ const ExitCodes = {
 let isShuttingDown = false;
 
 /**
- * Parse command-line arguments to get the config file path.
+ * Parsed command-line arguments.
+ */
+interface ParsedArgs {
+  /** Path to the config file (positional argument) */
+  configPath?: string;
+  /** Path to the custom agents JSON file (--custom-agents <path>) */
+  customAgentsPath?: string;
+}
+
+/**
+ * Parse command-line arguments.
  *
- * Usage: node index.js [config-path]
+ * Usage: node index.js [config-path] [--custom-agents <path>]
  *
- * @returns The config file path or undefined if not provided
+ * @returns Parsed arguments
  */
-function parseArgs(): string | undefined {
+function parseArgs(): ParsedArgs {
   // argv[0] is node, argv[1] is the script path
-  // argv[2] is the first argument (config path)
   const args = process.argv.slice(2);
+  const result: ParsedArgs = {};
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--custom-agents') {
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('-')) {
+        result.customAgentsPath = nextArg;
+        i += 2;
+        continue;
+      }
+      // --custom-agents without value: log warning and skip
+      logWarn('--custom-agents requires a file path argument, ignoring');
+      i += 1;
+      continue;
+    }
+
+    // First non-flag argument is the config path
+    if (!arg.startsWith('-') && !result.configPath) {
+      result.configPath = arg;
+    }
 
-  if (args.length > 0 && args[0] && !args[0].startsWith('-')) {
-    return args[0];
+    i += 1;
   }
 
-  return undefined;
+  return result;
 }
 
 /**
@@ -240,13 +271,19 @@ async function main(): Promise<void> {
   logInfo('Registry Launcher starting');
 
   // Parse command-line arguments
-  const configPath = parseArgs();
-  if (configPath) {
-    logInfo(`Loading configuration from: ${configPath}`);
+  const parsedArgs = parseArgs();
+  if (parsedArgs.configPath) {
+    logInfo(`Loading configuration from: ${parsedArgs.configPath}`);
   }
 
   // Load configuration
-  const config = loadConfig(configPath);
+  const config = loadConfig(parsedArgs.configPath);
+
+  // CLI --custom-agents takes precedence over config file and env
+  if (parsedArgs.customAgentsPath) {
+    config.customAgentsPath = parsedArgs.customAgentsPath;
+  }
+
   logInfo(`Configuration loaded: registryUrl=${config.registryUrl}, apiKeysPath=${config.apiKeysPath}, shutdownTimeoutSec=${config.shutdownTimeoutSec}`);
 
   // Load API keys
@@ -271,6 +308,26 @@ async function main(): Promise<void> {
     process.exit(ExitCodes.FATAL_ERROR);
   }
 
+  // Load and merge custom agents if --custom-agents was provided
+  if (config.customAgentsPath) {
+    try {
+      logInfo(`Loading custom agents from: ${config.customAgentsPath}`);
+      const customAgents = loadCustomAgents(config.customAgentsPath);
+      registry.mergeCustomAgents(customAgents);
+    } catch (error) {
+      if (error instanceof CustomAgentsLoadError) {
+        logError(`Failed to load custom agents: ${error.message}`);
+        process.exit(ExitCodes.FATAL_ERROR);
+      }
+      if (error instanceof RegistryParseError) {
+        logError(`Invalid custom agents file: ${error.message}`);
+        process.exit(ExitCodes.FATAL_ERROR);
+      }
+      logError(`Unexpected error loading custom agents: ${(error as Error).message}`);
+      process.exit(ExitCodes.FATAL_ERROR);
+    }
+  }
+
   // Create runtime manager
   const runtimeManager = new AgentRuntimeManager();
 

workers-registry/acp-worker/src/registry-launcher/index.ts

@@ -127,33 +127,6 @@ const distributionArb: fc.Arbitrary<Distribution> = fc.oneof(
   uvxDistributionArb.map((uvx) => ({ uvx })),
 );
 
-/**
- * Arbitrary for generating valid environment variable keys.
- * Excludes __proto__, constructor, and other prototype-related keys that have
- * special behavior in JavaScript and are not valid environment variable names.
- */
-const envKeyArb = fc
-  .string({ minLength: 1, maxLength: 20 })
-  .filter((s) => /^[A-Z_][A-Z0-9_]*$/i.test(s))
-  .filter((s) => !['__proto__', 'constructor', 'prototype', 'hasOwnProperty', 'toString'].includes(s));
-
-/**
- * Arbitrary for generating valid environment variable records.
- */
-const envRecordArb: fc.Arbitrary<Record<string, string>> = fc.dictionary(
-  envKeyArb,
-  fc.string({ maxLength: 100 }),
-  { minKeys: 0, maxKeys: 5 },
-);
-
-/**
- * Arbitrary for generating valid command-line arguments.
- */
-const argsArrayArb: fc.Arbitrary<string[]> = fc.array(
-  fc.string({ maxLength: 50 }),
-  { minLength: 0, maxLength: 5 },
-);
-
 /**
  * Arbitrary for generating valid RegistryAgent objects.
  */