network-ai 4.1.0 → 4.3.0

package/README.md

@@ -4,22 +4,23 @@
 
 [![CI](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v4.1.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v4.3.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
-[![Tests](https://img.shields.io/badge/tests-1283%20passing-brightgreen.svg)](#testing)
-[![Adapters](https://img.shields.io/badge/frameworks-13%20supported-blueviolet.svg)](#adapter-system)
+[![Tests](https://img.shields.io/badge/tests-1399%20passing-brightgreen.svg)](#testing)
+[![Adapters](https://img.shields.io/badge/frameworks-14%20supported-blueviolet.svg)](#adapter-system)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Socket](https://socket.dev/api/badge/npm/package/network-ai)](https://socket.dev/npm/package/network-ai/overview)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://typescriptlang.org)
 [![ClawHub](https://img.shields.io/badge/ClawHub-network--ai-orange.svg)](https://clawhub.ai/skills/network-ai)
 [![Integration Guide](https://img.shields.io/badge/docs-integration%20guide-informational.svg)](INTEGRATION_GUIDE.md)
+[![Glama](https://img.shields.io/badge/Glama-listed-8A2BE2.svg)](https://glama.ai/mcp/servers/@jovanSAPFIONEER/network-ai)
 
 Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.
 
 - **Shared blackboard with locking** — atomic `propose → validate → commit` prevents race conditions and split-brain failures across parallel agents
 - **Guardrails and budgets** — FSM governance, per-agent token ceilings, HMAC audit trails, and permission gating
-- **13 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, and A2A — no glue code, no lock-in
+- **14 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, and Codex — no glue code, no lock-in
 
 > **The silent failure mode in multi-agent systems:** parallel agents writing to the same key
 > use last-write-wins by default — one agent's result silently overwrites another's mid-flight.
@@ -52,7 +53,7 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordinati
 | Race conditions in parallel agents | Atomic blackboard: `propose → validate → commit` with file-system mutex |
 | Agent overspend / runaway costs | `FederatedBudget` — hard per-agent token ceilings with live spend tracking |
 | No visibility into what agents did | HMAC-signed audit log on every write, permission grant, and FSM transition |
-| Locked into one AI framework | 13 adapters — mix LangChain + AutoGen + CrewAI + A2A + custom in one swarm |
+| Locked into one AI framework | 14 adapters — mix LangChain + AutoGen + CrewAI + Codex + custom in one swarm |
 | Agents escalating beyond their scope | `AuthGuardian` — scoped permission tokens required before sensitive operations |
 
 ---
@@ -230,7 +231,7 @@ npm run demo -- --07
 
 ## Adapter System
 
-13 adapters, zero adapter dependencies. You bring your own SDK objects.
+14 adapters, zero adapter dependencies. You bring your own SDK objects.
 
 | Adapter | Framework / Protocol | Register method |
 |---|---|---|
@@ -247,6 +248,7 @@ npm run demo -- --07
 | `AgnoAdapter` | Agno (formerly Phidata) | `registerAgent()`, `registerTeam()` |
 | `OpenClawAdapter` | OpenClaw | `registerSkill(name, skillRef)` |
 | `A2AAdapter` | Google A2A Protocol | `registerRemoteAgent(name, url)` |
+| `CodexAdapter` | OpenAI Codex / gpt-4o / Codex CLI | `registerCodexAgent(name, config)` |
 
 **Streaming variants** (drop-in replacements with `.stream()` support):
 
@@ -265,7 +267,7 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 
 | Capability | Network-AI | LangGraph | CrewAI | AutoGen |
 |---|---|---|---|---|
-| Cross-framework agents in one swarm | ✅ 13 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
+| Cross-framework agents in one swarm | ✅ 14 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
 | Atomic shared state (conflict-safe) | ✅ `propose → validate → commit` mutex | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution |
 | Hard token ceiling per agent | ✅ `FederatedBudget` (first-class API) | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling |
 | Permission gating before sensitive ops | ✅ `AuthGuardian` (built-in) | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware |
@@ -281,13 +283,14 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 npm run test:all          # All suites in sequence
 npm test                  # Core orchestrator
 npm run test:security     # Security module
-npm run test:adapters     # All 13 adapters
+npm run test:adapters     # All 14 adapters
 npm run test:streaming    # Streaming adapters
 npm run test:a2a          # A2A protocol adapter
+npm run test:codex        # Codex adapter
 npm run test:priority     # Priority & preemption
 ```
 
-**1,283 passing assertions across 15 test suites** (`npm run test:all`):
+**1,334 passing assertions across 16 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
@@ -295,14 +298,15 @@ npm run test:priority     # Priority & preemption
 | `test-phase5f.ts` | 127 | SSE transport, `McpCombinedBridge`, extended MCP tools |
 | `test-phase5g.ts` | 121 | CRDT backend, vector clocks, bidirectional sync |
 | `test-phase6.ts` | 121 | MCP server, control-plane tools, audit tools |
+| `test-adapters.ts` | 140 | All 14 adapters, registry routing, integration, edge cases |
 | `test-phase5d.ts` | 117 | Pluggable backend (Redis, CRDT, Memory) |
-| `test-adapters.ts` | 139 | All 13 adapters, registry routing, integration, edge cases |
 | `test-standalone.ts` | 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
 | `test-phase5e.ts` | 87 | Federated budget tracking |
 | `test-phase5c.ts` | 73 | Named multi-blackboard, isolation, backend options |
+| `test-codex.ts` | 51 | Codex adapter: chat, completion, CLI, BYOC client, error paths |
 | `test-priority.ts` | 64 | Priority preemption, conflict resolution, backward compat |
-| `test-a2a.ts` | 34 | A2A protocol: register, execute, mock fetch, error paths |
-| `test-streaming.ts` | 31 | Streaming adapters, chunk shapes, fallback, collectStream |
+| `test-a2a.ts` | 35 | A2A protocol: register, execute, mock fetch, error paths |
+| `test-streaming.ts` | 32 | Streaming adapters, chunk shapes, fallback, collectStream |
 | `test-phase5b.ts` | 55 | Pluggable backend part 2, consistency levels |
 | `test-phase5.ts` | 42 | Named multi-blackboard base |
 | `test-security.ts` | 34 | Tokens, sanitization, rate limiting, encryption, audit |

package/bin/cli.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * network-ai CLI — full in-process control over blackboard, auth, budget, and audit.
+ * Imports core classes directly (Option B: no server required).
+ *
+ * Usage:
+ *   npx network-ai <command> [options]
+ *   network-ai <command> [options]      (after npm install -g network-ai)
+ */
+
+import { Command, Option } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+
+import { LockedBlackboard } from '../lib/locked-blackboard';
+import { AuthGuardian } from '../index';
+import { FederatedBudget } from '../lib/federated-budget';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require('../package.json') as { version: string; name: string };
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function resolveData(opts: { data?: string }): string {
+  return path.resolve(opts.data ?? path.join(process.cwd(), 'data'));
+}
+
+function print(obj: unknown, asJson: boolean): void {
+  if (asJson) {
+    console.log(JSON.stringify(obj, null, 2));
+  } else if (typeof obj === 'string') {
+    console.log(obj);
+  } else {
+    console.log(JSON.stringify(obj, null, 2));
+  }
+}
+
+function die(msg: string): never {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function tryParseJson(v: string): unknown {
+  try { return JSON.parse(v); } catch { return v; }
+}
+
+// ── root program ──────────────────────────────────────────────────────────────
+
+const program = new Command();
+
+program
+  .name('network-ai')
+  .description('Network-AI CLI — full control over blackboard, auth, budget, and audit')
+  .version(pkg.version, '-v, --version')
+  .enablePositionalOptions()
+  .addOption(new Option('--data <path>', 'path to data directory').default('./data'))
+  .addOption(new Option('--json', 'output raw JSON (useful for piping)'));
+
+// ── bb (blackboard) ───────────────────────────────────────────────────────────
+
+const bb = program.command('bb').description('Blackboard operations');
+
+bb.command('get <key>')
+  .description('Read a value from the blackboard')
+  .action((key: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const entry = board.read(key);
+    if (!entry) die(`key not found: ${key}`);
+    print(g.json ? entry : entry.value, g.json);
+  });
+
+bb.command('set <key> <value>')
+  .description('Write a value to the blackboard')
+  .option('--agent <id>', 'source agent id', 'cli')
+  .option('--ttl <seconds>', 'TTL in seconds', (v) => parseInt(v, 10))
+  .action((key: string, value: string, opts: { agent: string; ttl?: number }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const entry = board.write(key, tryParseJson(value), opts.agent, opts.ttl);
+    print(g.json ? entry : `✓ set ${key}`, g.json);
+  });
+
+bb.command('delete <key>')
+  .description('Delete a key from the blackboard')
+  .action((key: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const ok = board.delete(key);
+    if (!ok) die(`key not found: ${key}`);
+    print(g.json ? { deleted: key } : `✓ deleted ${key}`, g.json);
+  });
+
+bb.command('list')
+  .description('List all keys on the blackboard')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const keys = board.listKeys();
+    print(g.json ? keys : keys.length ? keys.join('\n') : '(empty)', g.json);
+  });
+
+bb.command('snapshot')
+  .description('Dump full blackboard state as JSON')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const snap: Record<string, unknown> = {};
+    for (const key of board.listKeys()) snap[key] = board.read(key);
+    console.log(JSON.stringify(snap, null, 2));
+  });
+
+bb.command('propose <key> <value>')
+  .description('Propose a change and get back a change-id')
+  .option('--agent <id>', 'source agent id', 'cli')
+  .option('--ttl <seconds>', 'TTL in seconds', (v) => parseInt(v, 10))
+  .option('--priority <0-3>', 'priority: 0=low 1=normal 2=high 3=critical', (v) => parseInt(v, 10) as 0 | 1 | 2 | 3)
+  .action((key: string, value: string, opts: { agent: string; ttl?: number; priority?: 0 | 1 | 2 | 3 }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const changeId = board.propose(key, tryParseJson(value), opts.agent, opts.ttl, opts.priority);
+    print(g.json ? { changeId } : `change-id: ${changeId}`, g.json);
+  });
+
+bb.command('commit <changeId>')
+  .description('Validate and commit a proposed change')
+  .option('--agent <id>', 'validator agent id', 'cli')
+  .action((changeId: string, opts: { agent: string }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const valid = board.validate(changeId, opts.agent);
+    if (!valid) die(`change ${changeId} has conflicts — run 'bb abort' to cancel`);
+    const result = board.commit(changeId);
+    if (!result.success) die(`commit failed: ${result.message}`);
+    print(g.json ? result : `✓ committed ${changeId}: ${result.message}`, g.json);
+  });
+
+bb.command('abort <changeId>')
+  .description('Abort a pending proposed change')
+  .action((changeId: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const board = new LockedBlackboard(resolveData(g));
+    const ok = board.abort(changeId);
+    if (!ok) die(`change not found: ${changeId}`);
+    print(g.json ? { aborted: changeId } : `✓ aborted ${changeId}`, g.json);
+  });
+
+// ── auth ──────────────────────────────────────────────────────────────────────
+
+const auth = program.command('auth').description('Permission and token operations');
+
+auth.command('token <agentId>')
+  .description('Issue a permission token for an agent')
+  .option('--resource <type>', 'resource type to grant', 'blackboard')
+  .option('--justification <text>', 'justification text', 'CLI-issued token')
+  .option('--scope <scope>', 'permission scope')
+  .action(async (agentId: string, opts: { resource: string; justification: string; scope?: string }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const auditPath = path.join(resolveData(g), 'audit_log.jsonl');
+    const guardian = new AuthGuardian({ auditLogPath: auditPath });
+    guardian.registerAgentTrust({ agentId, trustLevel: 1, allowedResources: [opts.resource] });
+    const grant = await guardian.requestPermission(agentId, opts.resource, opts.justification, opts.scope);
+    if (g.json) {
+      print(grant, true);
+    } else {
+      console.log(`token:    ${grant.grantToken ?? '(none)'}`);
+      console.log(`granted:  ${grant.granted}`);
+      console.log(`expires:  ${grant.expiresAt ?? 'never'}`);
+      if (!grant.granted && grant.reason) console.log(`reason:   ${grant.reason}`);
+    }
+  });
+
+auth.command('revoke <token>')
+  .description('Revoke a permission token')
+  .action((token: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const auditPath = path.join(resolveData(g), 'audit_log.jsonl');
+    const guardian = new AuthGuardian({ auditLogPath: auditPath });
+    guardian.revokeToken(token);
+    print(g.json ? { revoked: token } : `✓ revoked`, g.json);
+  });
+
+auth.command('check <token> <permission>')
+  .description('Check if a token grants a permission (exits 0=yes, 1=no)')
+  .action((token: string, permission: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const auditPath = path.join(resolveData(g), 'audit_log.jsonl');
+    const guardian = new AuthGuardian({ auditLogPath: auditPath });
+    const valid = guardian.validateToken(token);
+    const violation = valid ? guardian.enforceRestrictions(token, { type: permission }) : 'invalid or expired token';
+    const allowed = valid && violation === null;
+    print(
+      g.json ? { allowed, permission, reason: violation ?? null } : (allowed ? `✓ allowed` : `✗ denied: ${violation}`),
+      g.json,
+    );
+    process.exit(allowed ? 0 : 1);
+  });
+
+// ── budget ────────────────────────────────────────────────────────────────────
+
+const budgetCmd = program.command('budget').description('Token budget operations');
+
+budgetCmd.command('status [agentId]')
+  .description('Show token budget status')
+  .option('--ceiling <n>', 'total token ceiling', (v) => parseInt(v, 10))
+  .action((agentId: string | undefined, opts: { ceiling?: number }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const ceiling = opts.ceiling ?? 100_000;
+    const fed = new FederatedBudget({ ceiling });
+    if (agentId) {
+      const spent = fed.getAgentSpent(agentId);
+      const snap = { agentId, spent, remaining: fed.remaining(), ceiling: fed.getCeiling() };
+      print(g.json ? snap : `agent:     ${agentId}\nspent:     ${snap.spent}\nremaining: ${snap.remaining}\nceiling:   ${snap.ceiling}`, g.json);
+    } else {
+      const snap = { totalSpent: fed.getTotalSpent(), remaining: fed.remaining(), ceiling: fed.getCeiling(), byAgent: fed.getSpendLog() };
+      print(g.json ? snap : `total-spent: ${snap.totalSpent}\nremaining:   ${snap.remaining}\nceiling:     ${snap.ceiling}`, g.json);
+    }
+  });
+
+budgetCmd.command('set-ceiling <amount>')
+  .description('Update the token ceiling')
+  .action((amount: string, _opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const n = parseInt(amount, 10);
+    if (isNaN(n) || n <= 0) die('amount must be a positive integer');
+    const fed = new FederatedBudget({ ceiling: n });
+    fed.setCeiling(n);
+    print(g.json ? { ceiling: n } : `✓ ceiling set to ${n}`, g.json);
+  });
+
+// ── audit ─────────────────────────────────────────────────────────────────────
+
+const auditCmd = program.command('audit').description('Audit log operations');
+
+function getAuditLogPath(dataDir: string): string {
+  return path.join(dataDir, 'audit_log.jsonl');
+}
+
+auditCmd.command('log')
+  .description('Print audit log entries')
+  .option('--limit <n>', 'show last N entries', (v) => parseInt(v, 10))
+  .action((opts: { limit?: number }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const logFile = getAuditLogPath(resolveData(g));
+    if (!fs.existsSync(logFile)) die(`audit log not found: ${logFile}`);
+    const lines = fs.readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean);
+    const slice = opts.limit ? lines.slice(-opts.limit) : lines;
+    if (g.json) {
+      console.log(JSON.stringify(slice.map(l => { try { return JSON.parse(l); } catch { return l; } }), null, 2));
+    } else {
+      if (slice.length === 0) { console.log('(no entries)'); return; }
+      slice.forEach(l => console.log(l));
+    }
+  });
+
+auditCmd.command('tail')
+  .description('Live-stream new audit log entries (Ctrl+C to stop)')
+  .action((_opts: Record<string, unknown>, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const logFile = getAuditLogPath(resolveData(g));
+    if (!fs.existsSync(logFile)) die(`audit log not found: ${logFile}`);
+    let size = fs.statSync(logFile).size;
+    console.log(`tailing ${logFile} — Ctrl+C to stop`);
+    const interval = setInterval(() => {
+      try {
+        const newSize = fs.statSync(logFile).size;
+        if (newSize > size) {
+          const fd = fs.openSync(logFile, 'r');
+          const buf = Buffer.alloc(newSize - size);
+          fs.readSync(fd, buf, 0, buf.length, size);
+          fs.closeSync(fd);
+          buf.toString('utf-8').trim().split('\n').filter(Boolean).forEach(l => console.log(l));
+          size = newSize;
+        }
+      } catch { /* file may be briefly locked */ }
+    }, 500);
+    process.on('SIGINT', () => { clearInterval(interval); process.exit(0); });
+  });
+
+auditCmd.command('clear')
+  .description('Clear the audit log (prompts for confirmation)')
+  .option('--yes', 'skip confirmation prompt')
+  .action(async (opts: { yes?: boolean }, cmd: Command) => {
+    const g = cmd.optsWithGlobals<{ data: string; json: boolean }>();
+    const logFile = getAuditLogPath(resolveData(g));
+    if (!opts.yes) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise<string>(r => rl.question(`Clear ${logFile}? [y/N] `, r));
+      rl.close();
+      if (answer.toLowerCase() !== 'y') { console.log('Aborted.'); return; }
+    }
+    fs.writeFileSync(logFile, '');
+    print(g.json ? { cleared: logFile } : `✓ cleared ${logFile}`, g.json);
+  });
+
+// ── parse ─────────────────────────────────────────────────────────────────────
+
+program.parse(process.argv);

package/dist/adapters/codex-adapter.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Codex Adapter
+ *
+ * Integrates OpenAI Codex (code-davinci-002, gpt-4o, o4-mini, or any
+ * completions/chat-completions endpoint) with the SwarmOrchestrator.
+ *
+ * Supports three modes:
+ *  - `completion`  — legacy /v1/completions (code-davinci-002 style)
+ *  - `chat`        — /v1/chat/completions (gpt-4o, o4-mini, etc.)
+ *  - `cli`         — wraps an OpenAI Codex CLI process via a user-supplied
+ *                    executor function (for the codex CLI tool)
+ *
+ * Usage — chat mode:
+ *   const adapter = new CodexAdapter();
+ *   adapter.registerCodexAgent('refactor', {
+ *     mode: 'chat',
+ *     model: 'gpt-4o',
+ *     systemPrompt: 'You are a refactoring assistant.',
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *   });
+ *
+ * Usage — CLI mode (Codex CLI tool):
+ *   adapter.registerCodexAgent('codex-cli', {
+ *     mode: 'cli',
+ *     executor: async (prompt) => myCodexCLIWrapper(prompt),
+ *   });
+ *
+ * Usage — custom client (bring-your-own OpenAI SDK):
+ *   adapter.registerCodexAgent('analyst', {
+ *     mode: 'chat',
+ *     model: 'gpt-4o',
+ *     client: openaiInstance,   // any object with .chat.completions.create()
+ *   });
+ *
+ * @module CodexAdapter
+ * @version 1.0.0
+ */
+import { BaseAdapter } from './base-adapter';
+import type { AdapterCapabilities, AgentPayload, AgentContext, AgentResult } from '../types/agent-adapter';
+/** Execution mode for a Codex agent */
+export type CodexMode = 'completion' | 'chat' | 'cli';
+/**
+ * Minimal interface for the OpenAI SDK's chat completions —
+ * compatible with `new OpenAI().chat.completions`.
+ * Users supply their own SDK instance; no hard dependency.
+ */
+export interface CodexChatClient {
+    create(params: {
+        model: string;
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        max_tokens?: number;
+        temperature?: number;
+        stop?: string[];
+    }): Promise<{
+        choices: Array<{
+            message?: {
+                content?: string | null;
+            };
+            text?: string;
+        }>;
+        usage?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+    }>;
+}
+/**
+ * Minimal interface for the OpenAI SDK's legacy completions —
+ * compatible with `new OpenAI().completions`.
+ */
+export interface CodexCompletionClient {
+    create(params: {
+        model: string;
+        prompt: string;
+        max_tokens?: number;
+        temperature?: number;
+        stop?: string[];
+    }): Promise<{
+        choices: Array<{
+            text?: string;
+        }>;
+        usage?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+    }>;
+}
+/**
+ * A user-supplied executor for Codex CLI mode.
+ * Receives the assembled prompt, returns the CLI output string.
+ */
+export type CodexCLIExecutor = (prompt: string, options?: Record<string, unknown>) => Promise<string>;
+/** Configuration for a registered Codex agent */
+export interface CodexAgentConfig {
+    /** Execution mode (default: 'chat') */
+    mode?: CodexMode;
+    /** Model name — e.g. 'gpt-4o', 'o4-mini', 'code-davinci-002' */
+    model?: string;
+    /** OpenAI API key — falls back to OPENAI_API_KEY env var */
+    apiKey?: string;
+    /** Base URL override for Azure OpenAI, proxies, or self-hosted endpoints */
+    baseUrl?: string;
+    /** System-level prompt prepended to every request (chat mode only) */
+    systemPrompt?: string;
+    /** Maximum tokens in the completion */
+    maxTokens?: number;
+    /** Temperature (0–2). Default: 0 for code tasks */
+    temperature?: number;
+    /** Stop sequences */
+    stop?: string[];
+    /**
+     * Bring-your-own OpenAI SDK chat completions instance.
+     * If supplied, apiKey / baseUrl are ignored and this client is used directly.
+     * Typically `new OpenAI().chat.completions` or `openai.chat.completions`.
+     */
+    client?: CodexChatClient | CodexCompletionClient;
+    /**
+     * Executor function for CLI mode.
+     * Required when mode === 'cli'.
+     */
+    executor?: CodexCLIExecutor;
+    /** Additional headers to send with fetch-based requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Adapter that connects OpenAI Codex / code-focused models to the
+ * SwarmOrchestrator. Supports chat completions, legacy completions,
+ * and the Codex CLI executor interface.
+ */
+export declare class CodexAdapter extends BaseAdapter {
+    readonly name = "codex";
+    readonly version = "1.0.0";
+    private agents;
+    get capabilities(): AdapterCapabilities;
+    /**
+     * Register a Codex-powered agent.
+     *
+     * @param agentId   Unique identifier used in `delegateTask` calls.
+     * @param config    Codex agent configuration.
+     */
+    registerCodexAgent(agentId: string, config?: CodexAgentConfig): void;
+    executeAgent(agentId: string, payload: AgentPayload, context: AgentContext): Promise<AgentResult>;
+    private _executeChat;
+    private _executeCompletion;
+    private _executeCLI;
+}
+//# sourceMappingURL=codex-adapter.d.ts.map

package/dist/adapters/codex-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-adapter.d.ts","sourceRoot":"","sources":["../../adapters/codex-adapter.ts"],"names":[],"mappings":"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"}