Network-AI CLAUDE.md

CLAUDE.md — Project Instructions for Claude Code

This file is read automatically by Claude Code when working in this repository.

Project Overview

Network-AI is a TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination. Version 5.15.1.

Build & Test Commands

npm install                   # Install dependencies
npx tsc --noEmit              # Type-check (zero errors expected)
npm run test:all              # Run all 3,638 tests across 41 suites
npm test                      # Core orchestrator tests only
npm run test:security         # Security module tests
npm run test:adapters         # All 32 adapter tests
npm run test:priority         # Priority & preemption tests
npm run test:cli              # CLI layer tests

All tests must pass before any commit. No test should be skipped or marked .only.

Project Structure

• index.ts — Core engine: SwarmOrchestrator, AuthGuardian, FederatedBudget, QualityGateAgent, all exports
• security.ts — Security module: SecureTokenManager, InputSanitizer, RateLimiter, DataEncryptor, SecureAuditLogger
• lib/locked-blackboard.ts — LockedBlackboard with atomic propose → validate → commit and file-system mutex
• lib/fsm-journey.ts — JourneyFSM behavioral control plane
• lib/compliance-monitor.ts — Real-time agent behavior surveillance
• lib/adapter-hooks.ts — AdapterHookManager: beforeExecute/afterExecute/onError lifecycle hooks + matcher-based filtering
• lib/skill-composer.ts — SkillComposer: chain/batch/loop/verify meta-operations
• lib/semantic-search.ts — SemanticMemory: BYOE vector store with cosine similarity
• lib/phase-pipeline.ts — PhasePipeline: multi-phase workflows with approval gates
• lib/confidence-filter.ts — ConfidenceFilter: multi-agent result scoring and filtering
• lib/fan-out.ts — FanOutFanIn: parallel agent spawning with pluggable aggregation
• lib/agent-runtime.ts — AgentRuntime: sandboxed execution with SandboxPolicy, ShellExecutor, FileAccessor, ApprovalGate
• lib/console-ui.ts — ConsoleUI: interactive terminal dashboard with ANSI TUI
• lib/strategy-agent.ts — StrategyAgent: meta-orchestrator with AgentPool, WorkloadPartitioner, adaptive scaling
• lib/goal-decomposer.ts — GoalDecomposer, TeamRunner, runTeam: LLM-powered goal → task DAG → parallel execution
• lib/env-manager.ts — EnvironmentManager: promotion chain dev→st→sit→qa→preprod→prod, backup/restore, env diff, NETWORK_AI_ENV routing
• lib/circuit-breaker.ts — CircuitBreaker CLOSED/OPEN/HALF_OPEN state machine; CircuitOpenError; per-adapter in AdapterRegistry with fallbackChain
• lib/telemetry-provider.ts — ITelemetryProvider BYOT interface; NullTelemetryProvider, CapturingTelemetryProvider; createOtelHooks() factory for AdapterHookManager
• lib/claude-hooks.ts — ClaudeHookBridge: AuthGuardian-gated coding-agent tool calls (Claude Code PreToolUse/PostToolUse hooks), observe/enforce modes, network-ai hook CLI
• lib/mcp-elicitation.ts — StdioElicitationChannel + createElicitationApprovalCallback: native in-client approval prompts over MCP elicitation (fail closed)
• lib/a2a-server.ts — A2AServer: expose the orchestrator as a Google A2A agent (agent card + tasks/send, Bearer-gated)
• lib/context-composer.ts — ContextComposer: token-budgeted, relevance-ranked context assembly (semantic/lexical × recency half-life × scope affinity, position-aware layout); estimateTokens()
• lib/mcp-tools-context.ts — ContextMcpTools: context_pack + blackboard_search MCP tools (signal-over-noise retrieval)
• adapters/ — 32 framework adapters (LangChain, AutoGen, CrewAI, MCP, Codex, Gemini, OpenAI Responses, Claude Agent SDK, MiniMax, NemoClaw, APS, Hermes, Orchestrator, etc.)
• bin/cli.ts — CLI entry point (npx network-ai)
• bin/mcp-server.ts — MCP server (SSE + stdio transport)
• bin/console.ts — Interactive console with pipe mode (npx network-ai-console)
• scripts/ — Python helper scripts (blackboard, permissions, token management)
• types/ — TypeScript declaration files
• data/ — Runtime data (gitignored): audit log, pending changes