Network-AI — Enterprise Evaluation Guide

This document exists so an engineer or architect can evaluate Network-AI in under 30 minutes without a sales call.

Quick Evaluation Checklist

What It Does (One Paragraph)

Network-AI is a TypeScript/Node.js orchestration layer that sits between your agents and your shared state. It enforces: atomic blackboard writes (no race conditions when two agents write simultaneously), permission gating (agents must request access to sensitive resources and provide a scored justification), budget ceilings (per-agent token limits; rogue agents get cut off mid-task), FSM-based workflow governance (agents are blocked from skipping pipeline stages), and real-time compliance monitoring (tool abuse, turn-taking violations, response timeouts). v5.0 adds: approval inbox (web-accessible approval queue), job queue (persistent priority FIFO with crash recovery), transport layer (JSON-RPC 2.0 with HMAC auth), agent VCR (record/replay for testing), comparison runner (side-by-side adapter evaluation), and 9 new adapters. v5.1.4 adds: RLMAdapter (recursive language model / any RLM-compatible HTTP endpoint), FederatedBudget child spending, blackboard metadata API, PhasePipeline compaction, semaphore-based fan-out, HookContext depth, and sub-goal recursion. v5.3.x adds: Context Throttler (prune blackboard keys per-agent scope), Route Classifier (goal routing + FACTUAL_LOOKUP short-circuit), Partition Planner (non-overlapping agent focus areas), Coverage Gate (recursive completeness refinement), advisory token enforcement in the permission system, and context injection validation in the project context manager. v5.4.0 adds: EnvironmentManager (full promotion chain with backup/rollback), LockedBlackboard env routing (NETWORK_AI_ENV), source protection (FileAccessor scope enforcement), Python NETWORK_AI_ENV support across all five scripts, and 29 CLI env subcommands. v5.4.1 adds: TOCTOU race condition fixes in _touchJson/_touchFile (CWE-367, CodeQL #149–#150) via openSync(O_CREAT|O_EXCL); unused imports and dead function removed (CodeQL #151–#153). v5.4.2 adds: improved MCP tool descriptions across all 22 tools (behavior on error, return shapes, usage guidelines); ClawHub ASI01/ASI03/ASI06/ASI07 Notes documented as by-design mitigated patterns in SECURITY.md. v5.4.3 adds: ClawHub ASI01/03/06/07 Notes security-findings table added to SKILL.md; README documentation table updated with SKILL.md entry and Code of Conduct/Security Policy footer links; UTF-8 BOM stripped from package.json/skill.json/openapi.yaml (fixed CI ts-node parse failure). v5.4.4 adds: fixed missing import os in scripts/swarm_guard.py (ClawHub ASI08). v5.5.0 adds: SAP Basis-inspired TransportAgent/LandscapeAgent transport tier; AgentPool.setDispatchPause; ENVIRONMENT_PROMOTE AuthGuardian resource profile; 117 new transport tests. v5.5.1 adds: revoke_token.py env-scoped path fix — _resolve_data_dir() + --env CLI arg ensure token revocation and TTL cleanup target the correct data/<env>/ directory (ClawScan ASI03). v5.5.2 adds: HMAC-SHA256 grant-token integrity — check_permission.py signs each grant with _sig; validate_token.py rejects tampered records; signing key auto-generated at data/.signing_key (stdlib only, zero new deps, ClawScan ASI03). v5.5.3 adds: CodeQL alerts #154–#159 resolved — useless-assignment-to-local dead stores in transport-agent.ts, unused origGet in test-transport.ts, empty-except comment in check_permission.py. v5.5.4 adds: SKILL.md scan findings table updated to v5.5.3 scan state — ASI03/ASI06 severity reduced from High to Medium; two new Low findings (local grant state, audit log free text) documented with mitigations. v5.5.5 adds: MAESTRO/OWASP AST framework assessment section added to SKILL.md documenting Network-AI’s architectural mitigations for AST03 (over-privileged skills), AST06 (weak isolation), and AST07 (update drift). v5.5.6 adds: socket.json false-positive suppression for ContextThrottler networkAccess (transitive import-graph false positive from Socket.dev scan). v5.5.7 adds: socket.json shellAccess ignore entries for AgentRuntime and McpToolConsumer (child_process import flagged by Socket.dev shellAccess alert; already covered by shellExec entries — added shellAccess key to close the remaining false positive). v5.5.8 adds: operational hardening — approvalTimeoutMs fail-closed timeout for PhasePipeline approval gates (default 5 min); enforcePromotionChain opt-in for EnvironmentManager enforcing the full dev→st→sit→qa→preprod→prod sequence; onCompact callback now receives archived phase results; adapter discovery failures now logged via console.warn; FederatedBudget persist errors now surface via console.warn; CLI --json mode now emits structured error JSON; advisory token clarification in AuthGuardian JSDoc; FileAccessor never-throw contract; LockedBlackboard dirty-read and tie-break semantics documented; streaming auth once-at-start documented. v5.5.9 adds: LockedBlackboard TTL background sweep — purgeExpired() on-demand eviction, startSweep(intervalMs) / stopSweep() background timer (unref’d; default 60 s). v5.6.0 adds: LockedBlackboard WAL crash recovery — Write-Ahead Log (.wal.jsonl) records ops before writes and checkpoints after; replayWAL() on startup recovers uncommitted ops from process crashes; compactWAL() for manual truncation. v5.6.1 adds: Circuit Breaker on AdapterRegistry — CircuitBreaker class (CLOSED/OPEN/HALF_OPEN), CircuitOpenError, per-adapter breakers, fallbackChain, getCircuitState(), resetCircuit(); circuit:open/half-open/close events on AdapterEventType; zero new runtime dependencies. v5.7.0 adds: ITelemetryProvider BYOT abstraction — NullTelemetryProvider (default no-op), CapturingTelemetryProvider (in-memory for tests), createOtelHooks(provider) factory wires beforeExecute / afterExecute / onError spans into AdapterHookManager; plug in any OTel SDK without modifying adapters; zero new runtime dependencies. v5.7.1 adds: CodeQL fixes — compactWAL() TOCTOU race condition (CWE-367) resolved; unused imports and useless assignment removed from test-phase11.ts. v5.7.2 adds: Security fix GHSA-r78r-rwrf-rjwp — McpSseServer._isAuthorized() fail-closed on empty secret (CWE-306/CWE-862 incomplete fix); listen() rejects if secret is absent; McpSseTransport accepts secret param for automatic bearer auth. v5.8.5 adds: justification strings in check_permission.py are now truncated to 200 characters before audit log writes; --audit-summary --json strips justification text from returned entries to prevent re-exposure of previously logged sensitive content (SkillSpector Ssd3 findings). v5.8.6 adds: LockedBlackboard correctness fixes — stale-lock compare-and-delete race (forceReleaseStale()), ownership-verified release(), atomic snapshot via tmp+rename, WAL/pending reconciliation (zombie entry cleanup), priority-aware pending eviction, and disableWal production warning; 3 new test suites (55 total assertions in phase11); NFS and power-loss durability limits documented in ARCHITECTURE.md. v5.11.0 adds: CodeQL #165–#168 fixes in test-phase11.ts (CWE-367 TOCTOU — fd-based writes replace path-based writeFileSync in test helpers; unused variable removed); SkillSpector Intent-Code Divergence finding resolved — blackboard.py header comment now accurately describes --path scope (blackboard file only; lock files and pending-change files always use global data/).

Architecture Summary

Your agents
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  Network-AI Orchestration Layer                     │
│                                                     │
│  LockedBlackboard  ──── atomic propose/commit       │
│  AuthGuardian      ──── permission scoring          │
│  FederatedBudget   ──── per-agent token ceilings    │
│  JourneyFSM        ──── FSM state governance        │
│  ComplianceMonitor ──── real-time violation policy  │
│  BlackboardValidator─── content quality gate        │
│  QAOrchestratorAgent── scenario replay & regression │
│  ProjectContextManager─ Layer-3 persistent memory   │
└─────────────────────────────────────────────────────┘
    │
    ▼
data/ (local filesystem — you own it)
  ├── audit_log.jsonl
  ├── active_grants.json
  ├── project-context.json
  └── blackboard state files

Full architecture: ARCHITECTURE.md

Security & Supply Chain

Stability & Support Expectations

Versioning

Network-AI follows Semantic Versioning:

• Patch (4.0.x): bug fixes and security patches — safe to auto-update
• Minor (4.x.0): additive features, backward-compatible — upgrade at your pace
• Major (x.0.0): breaking API changes — migration guide provided in CHANGELOG

Security Fix Policy

Response Times (GitHub Issues)

Stability Signals

• 3,269 passing assertions across 33 suites
• Deterministic scoring — no random outcomes in permission evaluation or budget enforcement
• CI runs on every push and every PR
• All examples ship with the repo and run without mocking

Integration Entry Points

Known Adopters

See ADOPTERS.md.

License

MIT — LICENSE. No CLA required for contributions.