|
| 1 | +# CODEX.md — Project Instructions for OpenAI Codex |
| 2 | + |
| 3 | +This file is read automatically by OpenAI Codex CLI when working in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 4.10.0. |
| 8 | + |
| 9 | +## Build & Test Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install # Install dependencies |
| 13 | +npx tsc --noEmit # Type-check (zero errors expected) |
| 14 | +npm run test:all # Run all 1,617 tests across 20 suites |
| 15 | +npm test # Core orchestrator tests only |
| 16 | +npm run test:security # Security module tests |
| 17 | +npm run test:adapters # All 17 adapter tests |
| 18 | +npm run test:priority # Priority & preemption tests |
| 19 | +npm run test:cli # CLI layer tests |
| 20 | +``` |
| 21 | + |
| 22 | +All tests must pass before any commit. No test should be skipped or marked `.only`. |
| 23 | + |
| 24 | +## Project Structure |
| 25 | + |
| 26 | +- `index.ts` — Core engine: SwarmOrchestrator, AuthGuardian, FederatedBudget, QualityGateAgent, all exports |
| 27 | +- `security.ts` — Security module: SecureTokenManager, InputSanitizer, RateLimiter, DataEncryptor, SecureAuditLogger |
| 28 | +- `lib/locked-blackboard.ts` — LockedBlackboard with atomic propose → validate → commit and file-system mutex |
| 29 | +- `lib/fsm-journey.ts` — JourneyFSM behavioral control plane |
| 30 | +- `lib/compliance-monitor.ts` — Real-time agent behavior surveillance |
| 31 | +- `adapters/` — 17 framework adapters (LangChain, AutoGen, CrewAI, MCP, Codex, MiniMax, NemoClaw, APS, etc.) |
| 32 | +- `bin/cli.ts` — CLI entry point (`npx network-ai`) |
| 33 | +- `bin/mcp-server.ts` — MCP server (SSE + stdio transport) |
| 34 | +- `scripts/` — Python helper scripts (blackboard, permissions, token management) |
| 35 | +- `types/` — TypeScript declaration files |
| 36 | +- `data/` — Runtime data (gitignored): audit log, pending changes |
| 37 | + |
| 38 | +## Key Architecture Patterns |
| 39 | + |
| 40 | +- **Blackboard pattern**: All agent coordination goes through `LockedBlackboard` — `propose()` → `validate()` → `commit()` with file-system mutex. Never write directly. |
| 41 | +- **Permission gating**: `AuthGuardian` uses weighted scoring (justification 40%, trust 30%, risk 30%). Always require permission before sensitive resource access. |
| 42 | +- **Adapter system**: All adapters extend `BaseAdapter`. Each is dependency-free (BYOC — bring your own client). Do not add runtime dependencies to adapters. |
| 43 | +- **Audit trail**: Every write, permission grant, and state transition is logged to `data/audit_log.jsonl` via `SecureAuditLogger`. |
| 44 | + |
| 45 | +## Code Conventions |
| 46 | + |
| 47 | +- TypeScript strict mode, target ES2022 |
| 48 | +- No `any` types — use proper generics or `unknown` |
| 49 | +- JSDoc on all exported functions and classes |
| 50 | +- No new runtime dependencies without explicit approval |
| 51 | +- Input validation required on all public API entry points |
| 52 | +- Keep adapter files self-contained — no cross-adapter imports |
| 53 | + |
| 54 | +## Security Requirements |
| 55 | + |
| 56 | +- AES-256-GCM encryption for data at rest |
| 57 | +- HMAC-SHA256 / Ed25519 signed tokens with TTL |
| 58 | +- No hardcoded secrets, keys, or credentials anywhere |
| 59 | +- Path traversal and injection protections on all file operations |
| 60 | +- Rate limiting on all public-facing endpoints |
| 61 | + |
| 62 | +## Common Workflows |
| 63 | + |
| 64 | +**Adding a new adapter:** |
| 65 | +1. Create `adapters/<name>-adapter.ts` extending `BaseAdapter` |
| 66 | +2. Implement `executeAgent()`, `getCapabilities()`, lifecycle methods |
| 67 | +3. Register in `adapters/adapter-registry.ts` and `adapters/index.ts` |
| 68 | +4. Add tests in `test-adapters.ts` |
| 69 | +5. Update README adapter table |
| 70 | + |
| 71 | +**Bumping a version:** |
| 72 | +See `RELEASING.md` for the full checklist. Key files: `package.json`, `skill.json`, `openapi.yaml`, `README.md` badge, `CHANGELOG.md`, `SECURITY.md`, `.github/SECURITY.md`. |
0 commit comments