{"id":"15a2bfff-790f-440f-99e9-b2eb9835b516","entityType":"agent","slug":"clawhub-jovansapfioneer-network-ai","name":"Network-AI","canonicalUrl":"https://www.xpersona.co/agent/clawhub-jovansapfioneer-network-ai","canonicalPath":"/agent/clawhub-jovansapfioneer-network-ai","generatedAt":"2026-10-09T23:54:06.532Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e... Skill: Network-AI Owner: jovanSAPFIONEER Summary: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e... Tags: audit:4.0.4, autogen:4.0.4, blackboard:4.0.4, crewai:4.0.4, langchain:4.0.4, latest:4.0.14, mcp:4.0.4, multi-agent:4.0.4, orchestration:4.0.4, permissions:4.0.4, security:4.0.4, swarm:4.0.4 Version histo","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 788 downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn75j1xcebk74re38bv714kh1h81804p:network-ai","sourceUrl":"https://clawhub.ai/jovanSAPFIONEER/network-ai","homepage":"https://clawhub.ai/jovanSAPFIONEER/network-ai","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/jovanSAPFIONEER/network-ai","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":58,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":788,"packageName":null,"latestVersion":"4.0.14","tractionLabel":"788 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-03-01T02:23:03.090Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-03-01T02:23:03.090Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-02T02:23:03.090Z","lastVerifiedAt":null,"highlights":[{"version":"4.0.14","createdAt":"2026-02-28T18:59:58.541Z","changelog":"**Clarifies configuration for Python vs Node.js features and removes obsolete environment variables.** - Updated documentation to state that HMAC signing and AES-256 encryption are only available in the Node.js MCP server, not the Python scripts. - Revised environment variable descriptions to clarify they have no effect in core Python scripts. - Notes that permission tokens use UUIDs and are stored locally in plaintext (not HMAC-signed). - Specifies OpenAI API keys are not required or used by Python scripts. - General documentation cleanup to more accurately reflect behavior and separation of Python and Node.js components.","fileCount":13,"zipByteSize":56363},{"version":"4.0.13","createdAt":"2026-02-28T18:48:35.783Z","changelog":"Version 4.0.13 - Added detailed system architecture overview (ARCHITECTURE.md) - Added performance and benchmarking documentation (BENCHMARKS.md)","fileCount":13,"zipByteSize":56286},{"version":"4.0.12","createdAt":"2026-02-28T17:34:33.499Z","changelog":"- Clarified that Node.js (node) is now optional; only Python 3 is required for this skill's functionality. - Updated metadata to include \"optional_bins\" for Node, and explanatory notes. - Added explicit notice that all instructions apply to local Python scripts only; Node.js MCP server is separate and not required. - No behavioral or architectural changes to orchestration, workflows, or agent protocols.","fileCount":null,"zipByteSize":null},{"version":"4.0.11","createdAt":"2026-02-28T17:23:30.321Z","changelog":"Add install spec to skill.json (npm package + Python scripts declared with source repo link). Resolves OpenClaw scanner: no install spec, missing server artifacts, undeclared npx fetch.","fileCount":null,"zipByteSize":null},{"version":"4.0.10","createdAt":"2026-02-28T17:12:09.694Z","changelog":"Declare env vars (SWARM_TOKEN_SECRET, SWARM_ENCRYPTION_KEY, OPENAI_API_KEY) and audit_log privacy scope in skill.json + SKILL.md; add --no-audit flag to disable local audit writes. Resolves OpenClaw scanner undeclared-env and local-logging warnings.","fileCount":null,"zipByteSize":null},{"version":"4.0.9","createdAt":"2026-02-28T15:21:02.527Z","changelog":"Fix: republish with compiled dist/bin/mcp-server.js — resolves OpenClaw scanner false positive (MCP server source present but binary was missing from zip in 4.0.8)","fileCount":null,"zipByteSize":null},{"version":"4.0.8","createdAt":"2026-02-28T14:36:29.590Z","changelog":"Fix metadata drift: skill.json maxParallelAgents corrected to Infinity default, MCP handshake handlers added, CORS headers for Cursor/Claude Desktop, version consistency fixes","fileCount":null,"zipByteSize":null},{"version":"4.0.7","createdAt":"2026-02-28T10:48:49.754Z","changelog":"Add INTEGRATION_GUIDE.md — enterprise implementation playbook (discovery, framework mapping, phased rollout, IAM, audit, air-gap, multi-tenant, validation checklist); include in npm package; bump version strings to 4.0.7","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn75j1xcebk74re38bv714kh1h81804p:network-ai","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T23:54:06.529Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: Network-AI\n\nOwner: jovanSAPFIONEER\n\nSummary: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e...\n\nTags: audit:4.0.4, autogen:4.0.4, blackboard:4.0.4, crewai:4.0.4, langchain:4.0.4, latest:4.0.14, mcp:4.0.4, multi-agent:4.0.4, orchestration:4.0.4, permissions:4.0.4, security:4.0.4, swarm:4.0.4\n\nVersion history:\n\nv4.0.14 | 2026-02-28T18:59:58.541Z | auto\n\n**Clarifies configuration for Python vs Node.js features and removes obsolete environment variables.**\n\n- Updated documentation to state that HMAC signing and AES-256 encryption are only available in the Node.js MCP server, not the Python scripts.\n- Revised environment variable descriptions to clarify they have no effect in core Python scripts.\n- Notes that permission tokens use UUIDs and are stored locally in plaintext (not HMAC-signed).\n- Specifies OpenAI API keys are not required or used by Python scripts.\n- General documentation cleanup to more accurately reflect behavior and separation of Python and Node.js components.\n\nv4.0.13 | 2026-02-28T18:48:35.783Z | auto\n\nVersion 4.0.13\n\n- Added detailed system architecture overview (ARCHITECTURE.md)\n- Added performance and benchmarking documentation (BENCHMARKS.md)\n\nv4.0.12 | 2026-02-28T17:34:33.499Z | auto\n\n- Clarified that Node.js (node) is now optional; only Python 3 is required for this skill's functionality.\n- Updated metadata to include \"optional_bins\" for Node, and explanatory notes.\n- Added explicit notice that all instructions apply to local Python scripts only; Node.js MCP server is separate and not required.\n- No behavioral or architectural changes to orchestration, workflows, or agent protocols.\n\nv4.0.11 | 2026-02-28T17:23:30.321Z | user\n\nAdd install spec to skill.json (npm package + Python scripts declared with source repo link). Resolves OpenClaw scanner: no install spec, missing server artifacts, undeclared npx fetch.\n\nv4.0.10 | 2026-02-28T17:12:09.694Z | user\n\nDeclare env vars (SWARM_TOKEN_SECRET, SWARM_ENCRYPTION_KEY, OPENAI_API_KEY) and audit_log privacy scope in skill.json + SKILL.md; add --no-audit flag to disable local audit writes. Resolves OpenClaw scanner undeclared-env and local-logging warnings.\n\nv4.0.9 | 2026-02-28T15:21:02.527Z | user\n\nFix: republish with compiled dist/bin/mcp-server.js — resolves OpenClaw scanner false positive (MCP server source present but binary was missing from zip in 4.0.8)\n\nv4.0.8 | 2026-02-28T14:36:29.590Z | user\n\nFix metadata drift: skill.json maxParallelAgents corrected to Infinity default, MCP handshake handlers added, CORS headers for Cursor/Claude Desktop, version consistency fixes\n\nv4.0.7 | 2026-02-28T10:48:49.754Z | user\n\nAdd INTEGRATION_GUIDE.md — enterprise implementation playbook (discovery, framework mapping, phased rollout, IAM, audit, air-gap, multi-tenant, validation checklist); include in npm package; bump version strings to 4.0.7\n\nv4.0.6 | 2026-02-27T21:46:42.601Z | user\n\nFix socket.json packaging — include in npm files array so Socket.dev ignore entries are respected; whitelist mcp-transport-sse and mcp-server network access; update mcp-server version strings to 4.0.6\n\nv4.0.5 | 2026-02-26T22:43:00.967Z | user\n\nAdd demos 07 & 08, unified npm run demo launcher, deterministic 10/10 scoring, debugger_agent two-pass hardening, --silent-summary mode\n\nv4.0.4 | 2026-02-26T15:09:06.548Z | user\n\nv4.0.4: guard adapter-registry regex against ReDoS; align skill.json resource names; all 1216 tests passing\n\nv4.0.3 | 2026-02-26T14:50:23.342Z | auto\n\n- Updated permission wall resource types: replaced SAP_API, FINANCIAL_API, and DATA_EXPORT with abstract local resources (DATABASE, PAYMENTS, EMAIL, FILE_EXPORT).\n- Clarified that no external credentials are required for permission walls; all access checks are local.\n- Revised example permission check usage to reflect new resource types.\n- Documentation remains focused on agent orchestration, budget and handoff protocols, and blackboard coordination.\n\nv4.0.2 | 2026-02-26T14:35:44.451Z | auto\n\nNo changes detected in this version.\n\n- No file or documentation changes were made for version 4.0.2.\n\nv4.0.1 | 2026-02-26T14:13:34.430Z | auto\n\nNo user-facing changes in this release.\n\n- Version updated to 4.0.1 with no modifications detected in code or documentation.\n\nv4.0.0 | 2026-02-26T12:40:54.960Z | auto\n\nNetwork-AI 4.0.0\n\n- SKILL.md significantly streamlined: redundant sections and partial/duplicate handoff protocol instructions removed.\n- Core orchestration steps and agent delegation instructions clarified and made more concise.\n- All quick start, handoff, and agent coordination sections retained, but duplicate or incomplete text removed for clarity.\n- No code or file changes detected; documentation update only.\n\nv3.9.0 | 2026-02-25T17:45:29.777Z | auto\n\nNo user-visible changes; SKILL.md remains effectively unchanged.\n- No file changes detected in this version.\n- Functionality and documentation are the same as previous release.\n\nv3.8.0 | 2026-02-25T17:16:11.450Z | auto\n\nNo user-facing changes in this release.\n\n- Version update with no detected file or documentation changes.\n- All features and workflows remain the same as the previous version.\n\nv3.7.1 | 2026-02-25T16:21:48.162Z | auto\n\nNo code or documentation changes were detected in this version.\n\n- Version 3.7.1 is functionally identical to the previous release.\n- No file changes were made.\n\nv3.7.0 | 2026-02-25T15:43:36.499Z | auto\n\nNo user-visible changes in this release; no file changes detected.\n\nv3.6.2 | 2026-02-24T16:59:04.253Z | auto\n\nNo user-facing changes in this release.\n\n- Version bump to 3.6.2 with no modifications to files or documentation.\n\nv3.6.0 | 2026-02-24T15:31:21.013Z | auto\n\nNo user-visible changes in this release (no file changes detected).\n\nv3.5.1 | 2026-02-23T16:40:19.873Z | auto\n\nNo user-facing changes in this version.\n\n- No file changes detected between this version and the previous release.\n\nv3.5.0 | 2026-02-23T16:14:51.100Z | auto\n\nVersion 3.5.0 of Network-AI\n\n- No file changes detected in this release.\n- No user-facing updates or modifications to core features. \n- Behavioral, workflow, and protocol remain identical to the previous version.\n\nv3.4.1 | 2026-02-23T15:30:26.094Z | auto\n\nNo file changes detected for version 3.4.1\n\n- No updates or changes were made to the skill in this version.\n- Documentation, source code, and functionality all remain unchanged from the previous release.\n\nv3.4.0 | 2026-02-23T14:34:24.271Z | auto\n\n- No code or documentation changes detected in this version.\n- Skill behavior, protocols, and usage remain unchanged from the previous release.\n\nv3.3.11 | 2026-02-22T13:10:27.067Z | auto\n\nNo user-facing or functional changes detected in this release.\n\n- No modifications were made to the skill files.\n- Documentation and protocols remain unchanged.\n- All agent orchestration, budget, and verification procedures are consistent with the previous version.\n\nv3.3.10 | 2026-02-22T13:02:17.848Z | auto\n\n- No code or content changes; documentation was re-saved without modification.\n- All features, instructions, and protocols remain the same as in the previous version.\n\nv3.3.9 | 2026-02-22T12:42:06.077Z | auto\n\n- Documentation refreshed with improved formatting and clarity; content remains functionally the same.\n- No code or file changes detected for this release.\n- Existing protocol and workflow descriptions are unchanged.\n\nv3.3.8 | 2026-02-22T12:20:20.333Z | auto\n\nNo changes detected in version 3.3.8 (no file changes). \n- The skill documentation and functionality remain unchanged. \n- No updates or additions in this release.\n\nv3.3.7 | 2026-02-21T22:23:23.258Z | auto\n\n- No file changes detected for this release.\n- Documentation was cleaned up by removing unfinished or extraneous content at the end of the SKILL.md file.\n- There are no functional or behavioral changes in this version.\n\nv3.3.6 | 2026-02-21T21:22:33.048Z | auto\n\n- Removed the file: swarm-blackboard.md, simplifying the repository structure.\n- No changes to configuration or orchestrator protocols documented in SKILL.md.\n- All existing instructions and usage workflows remain unchanged.\n- Update reduces redundancy in documentation regarding the blackboard system.\n\nv3.3.3 | 2026-02-20T17:38:13.843Z | user\n\nFix serialization crash in parallel waves, adapter failure propagation, cache abort fix + 3 working examples\n\nv3.3.2 | 2026-02-20T09:46:48.084Z | auto\n\n- No file changes detected in this version.\n- No updates or modifications to the code or documentation.\n- Behavior and instructions remain unchanged from the previous release.\n\nv3.3.1 | 2026-02-19T20:40:32.183Z | auto\n\nnetwork-ai 3.3.1\n\n- Documentation updated: SKILL.md removed duplicate or truncated instruction block from the Agent-to-Agent Handoff Protocol section.\n- No changes to features, APIs, or command protocols; this is a documentation cleanup release only.\n\nv3.3.0 | 2026-02-19T20:24:42.290Z | auto\n\nnetwork-ai 3.3.0\n\n- Documentation updated in swarm-blackboard.md for improved clarity and usability.\n- No changes to code or functionality; update is documentation-only.\n- Streamlines orchestrator protocols and usage instructions.\n\nv3.2.11 | 2026-02-19T15:47:30.792Z | auto\n\nnetwork-ai 3.2.11\n\n- Documentation updates in swarm-blackboard.md to clarify task orchestration protocols.\n- No changes to code or functionality.\n\nv3.2.10 | 2026-02-19T14:37:34.407Z | user\n\nFix: resolve all remaining CodeQL unused-variable alerts; add word boundaries to TODO/FIXME detection pattern; dismiss false-positive alerts; clean unused imports\n\nv3.2.9 | 2026-02-19T14:19:12.486Z | user\n\nFix: resolve all remaining CodeQL alerts SHA-pin all GitHub Actions; fix final TOCTOU race in locked-blackboard; remove unused imports; fix Python redundant-comparison and empty-except patterns\n\nv3.2.8 | 2026-02-18T22:33:35.354Z | user\n\nFix: resolve all CodeQL HIGH alerts TOCTOU race conditions in security.ts/locked-blackboard.ts/swarm-utils.ts; bad HTML regex in XSS filter; missing word boundary in blackboard-validator; Token-Permissions in ci.yml\n\nv3.2.7 | 2026-02-18T21:49:44.082Z | user\n\nFix: remove eval() from distributed code blackboard-validator detection regex refactored to avoid literal eval( in dist; MCP example updated to use String() instead of eval(); resolves Socket supply chain Uses eval flag (score 75->79+)\n\nv3.2.6 | 2026-02-18T20:04:41.440Z | user\n\nFix: skill.json homepage/source metadata added (was missing, caused 'source unknown' scanner flag); version frozen at 3.0.0 corrected; pycache excluded from npm tarball\n\nv3.2.5 | 2026-02-18T17:18:22.987Z | user\n\nRe-publish: unstick ClawHub scanner from v3.2.4 pending state\n\nv3.2.4 | 2026-02-18T16:27:12.783Z | user\n\nPhase 4 partial: observability commands, governance vocabulary, competitive comparison, Pylance fixes\n\nv3.2.2 | 2026-02-17T15:46:46.004Z | user\n\nRe-release of v3.2.1 security patch to resolve stuck VirusTotal scan. Hardened justification scoring against prompt injection, keyword stuffing, and padding attacks.\n\nv3.2.1 | 2026-02-17T13:45:15.429Z | user\n\nSecurity patch: hardened justification scoring against prompt injection, keyword stuffing, and padding attacks. Fixed audit log integrity test isolation.\n\nv3.2.0 | 2026-02-17T13:20:46.285Z | user\n\nPhase 3: Priority-based conflict resolution with preemption\n\nv3.1.3 | 2026-02-16T15:35:31.292Z | user\n\nFix scanner mismatches: remove node from requires.bins (bundle is Python-only), document validate_token.py in SKILL.md, sanitize capability terms\n\nv3.1.2 | 2026-02-16T15:25:04.323Z | user\n\nSecurity fix: path traversal vulnerability in blackboard.py change_id handling - blocks Unix and Windows traversal attacks\n\nv3.1.1 | 2026-02-16T15:12:51.896Z | user\n\nClean bundle: .clawhubignore added, description clarified for security scan\n\nv3.1.0 | 2026-02-16T13:46:38.498Z | user\n\nPhase 2: Trust - structured logging, typed errors, input validation, JSDoc, audit integration\n\nArchive index:\n\nArchive v4.0.14: 13 files, 56363 bytes\n\nFiles: ARCHITECTURE.md (11156b), AWESOME_LISTS.md (4778b), BENCHMARKS.md (6877b), INTEGRATION_GUIDE.md (20369b), requirements.txt (483b), scripts/blackboard.py (32078b), scripts/check_permission.py (24434b), scripts/revoke_token.py (7757b), scripts/swarm_guard.py (46680b), scripts/validate_token.py (2755b), SHOW_HN.md (3993b), SKILL.md (20558b), _meta.json (130b)\n\nFile v4.0.14:SKILL.md\n\n---\r\nname: Network-AI\r\ndescription: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and enforces permission walls before sensitive operations. All execution is local and sandboxed.\r\nmetadata:\r\n openclaw:\r\n emoji: \"\\U0001F41D\"\r\n homepage: https://github.com/jovanSAPFIONEER/Network-AI\r\n requires:\r\n bins:\r\n - python3\r\n optional_bins:\r\n - node # Only needed if you separately install and run the Node.js MCP server (network-ai-server via npm). Not required for this skill's Python instructions.\r\n env:\r\n SWARM_TOKEN_SECRET:\r\n required: false\r\n description: \"Node.js MCP server only — not used by these Python scripts. The Python permission layer uses UUID-based tokens stored in data/active_grants.json.\"\r\n SWARM_ENCRYPTION_KEY:\r\n required: false\r\n description: \"Node.js MCP server only — not used by these Python scripts. The Python blackboard does not encrypt data at rest.\"\r\n OPENAI_API_KEY:\r\n required: false\r\n description: \"Not used by these Python scripts. Only used by the optional Node.js demo examples when running the companion npm package.\"\r\n privacy:\r\n audit_log:\r\n path: data/audit_log.jsonl\r\n scope: local-only\r\n description: \"Local append-only JSONL file recording operation metadata (agentId, action, timestamp, outcome). No data leaves the machine. Disable with --no-audit flag on network-ai-server, or pass auditLogPath: undefined in createSwarmOrchestrator config.\"\r\n---\r\n\r\n# Swarm Orchestrator Skill\r\n\r\n> **Scope of this skill bundle:** All instructions below run local Python scripts (`scripts/*.py`). No network calls are made by this skill. Tokens are UUID-based (`grant_{uuid4().hex}`) stored in `data/active_grants.json`. Audit logging is plain JSONL (`data/audit_log.jsonl`) — no HMAC signing in the Python layer. HMAC-signed tokens, AES-256 encryption, and the standalone MCP server are all features of the **companion Node.js package** (`npm install -g network-ai`) — they are **not** implemented in these Python scripts and do **not** run automatically.\r\n\r\nMulti-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.\r\n\r\n## 🎯 Orchestrator System Instructions\r\n\r\n**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:\r\n\r\n### Core Responsibilities\r\n\r\n1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks\r\n2. **DELEGATE** using the budget-aware handoff protocol\r\n3. **VERIFY** results on the blackboard before committing\r\n4. **SYNTHESIZE** final output only after all validations pass\r\n\r\n### Task Decomposition Protocol\r\n\r\nWhen you receive a complex request, decompose it into exactly **3 sub-tasks**:\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────────┐\r\n│ COMPLEX USER REQUEST │\r\n└─────────────────────────────────────────────────────────────────┘\r\n │\r\n ▼\r\n ┌─────────────────────┼─────────────────────┐\r\n │ │ │\r\n ▼ ▼ ▼\r\n┌───────────────┐ ┌───────────────┐ ┌───────────────┐\r\n│ SUB-TASK 1 │ │ SUB-TASK 2 │ │ SUB-TASK 3 │\r\n│ data_analyst │ │ risk_assessor │ │strategy_advisor│\r\n│ (DATA) │ │ (VERIFY) │ │ (RECOMMEND) │\r\n└───────────────┘ └───────────────┘ └───────────────┘\r\n │ │ │\r\n └─────────────────────┼─────────────────────┘\r\n ▼\r\n ┌───────────────┐\r\n │ SYNTHESIZE │\r\n │ orchestrator │\r\n └───────────────┘\r\n```\r\n\r\n**Decomposition Template:**\r\n```\r\nTASK DECOMPOSITION for: \"{user_request}\"\r\n\r\nSub-Task 1 (DATA): [data_analyst]\r\n - Objective: Extract/process raw data\r\n - Output: Structured JSON with metrics\r\n\r\nSub-Task 2 (VERIFY): [risk_assessor] \r\n - Objective: Validate data quality & compliance\r\n - Output: Validation report with confidence score\r\n\r\nSub-Task 3 (RECOMMEND): [strategy_advisor]\r\n - Objective: Generate actionable insights\r\n - Output: Recommendations with rationale\r\n```\r\n\r\n### Budget-Aware Handoff Protocol\r\n\r\n**CRITICAL:** Before EVERY `sessions_send`, call the handoff interceptor:\r\n\r\n```bash\r\n# ALWAYS run this BEFORE sessions_send\r\npython {baseDir}/scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 revenue data\"\r\n```\r\n\r\n**Decision Logic:**\r\n```\r\nIF result.allowed == true:\r\n → Proceed with sessions_send\r\n → Note tokens_spent and remaining_budget\r\nELSE:\r\n → STOP - Do NOT call sessions_send\r\n → Report blocked reason to user\r\n → Consider: reduce scope or abort task\r\n```\r\n\r\n### Pre-Commit Verification Workflow\r\n\r\nBefore returning final results to the user:\r\n\r\n```bash\r\n# Step 1: Check all sub-task results on blackboard\r\npython {baseDir}/scripts/blackboard.py read \"task:001:data_analyst\"\r\npython {baseDir}/scripts/blackboard.py read \"task:001:risk_assessor\"\r\npython {baseDir}/scripts/blackboard.py read \"task:001:strategy_advisor\"\r\n\r\n# Step 2: Validate each result\r\npython {baseDir}/scripts/swarm_guard.py validate-result \\\r\n --task-id \"task_001\" \\\r\n --agent data_analyst \\\r\n --result '{\"status\":\"success\",\"output\":{...},\"confidence\":0.85}'\r\n\r\n# Step 3: Supervisor review (checks all issues)\r\npython {baseDir}/scripts/swarm_guard.py supervisor-review --task-id \"task_001\"\r\n\r\n# Step 4: Only if APPROVED, commit final state\r\npython {baseDir}/scripts/blackboard.py write \"task:001:final\" \\\r\n '{\"status\":\"SUCCESS\",\"output\":{...}}'\r\n```\r\n\r\n**Verdict Handling:**\r\n| Verdict | Action |\r\n|---------|--------|\r\n| `APPROVED` | Commit and return results to user |\r\n| `WARNING` | Review issues, fix if possible, then commit |\r\n| `BLOCKED` | Do NOT return results. Report failure. |\r\n\r\n---\r\n\r\n## When to Use This Skill\r\n\r\n- **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)\r\n- **Parallel Execution**: Run multiple agents simultaneously and synthesize results\r\n- **Permission Wall**: Gate access to DATABASE, PAYMENTS, EMAIL, or FILE_EXPORT operations (abstract local resource types — no external credentials required)\r\n- **Shared Blackboard**: Coordinate agent state via persistent markdown file\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize Budget (FIRST!)\r\n\r\n**Always initialize a budget before any multi-agent task:**\r\n\r\n```bash\r\npython {baseDir}/scripts/swarm_guard.py budget-init \\\r\n --task-id \"task_001\" \\\r\n --budget 10000 \\\r\n --description \"Q4 Financial Analysis\"\r\n```\r\n\r\n### 2. Delegate a Task to Another Session\r\n\r\nUse OpenClaw's built-in session tools to delegate work:\r\n\r\n```\r\nsessions_list # See available sessions/agents\r\nsessions_send # Send task to another session\r\nsessions_history # Check results from delegated work\r\n```\r\n\r\n**Example delegation prompt:**\r\n```\r\nUse sessions_send to ask the data_analyst session to:\r\n\"Analyze Q4 revenue trends from the SAP export data and summarize key insights\"\r\n```\r\n\r\n### 3. Check Permission Before API Access\r\n\r\nBefore accessing SAP or Financial APIs, evaluate the request:\r\n\r\n```bash\r\n# Run the permission checker script\r\npython {baseDir}/scripts/check_permission.py \\\r\n --agent \"data_analyst\" \\\r\n --resource \"DATABASE\" \\\r\n --justification \"Need Q4 invoice data for quarterly report\" \\\r\n --scope \"read:invoices\"\r\n```\r\n\r\nThe script will output a grant token if approved, or denial reason if rejected.\r\n\r\n### 4. Use the Shared Blackboard\r\n\r\nRead/write coordination state:\r\n\r\n```bash\r\n# Write to blackboard\r\npython {baseDir}/scripts/blackboard.py write \"task:q4_analysis\" '{\"status\": \"in_progress\", \"agent\": \"data_analyst\"}'\r\n\r\n# Read from blackboard \r\npython {baseDir}/scripts/blackboard.py read \"task:q4_analysis\"\r\n\r\n# List all entries\r\npython {baseDir}/scripts/blackboard.py list\r\n```\r\n\r\n## Agent-to-Agent Handoff Protocol\r\n\r\nWhen delegating tasks between agents/sessions:\r\n\r\n### Step 1: Initialize Budget & Check Capacity\r\n```bash\r\n# Initialize budget (if not already done)\r\npython {baseDir}/scripts/swarm_guard.py budget-init --task-id \"task_001\" --budget 10000\r\n\r\n# Check current status\r\npython {baseDir}/scripts/swarm_guard.py budget-check --task-id \"task_001\"\r\n```\r\n\r\n### Step 2: Identify Target Agent\r\n```\r\nsessions_list # Find available agents\r\n```\r\n\r\nCommon agent types:\r\n| Agent | Specialty |\r\n|-------|-----------|\r\n| `data_analyst` | Data processing, SQL, analytics |\r\n| `strategy_advisor` | Business strategy, recommendations |\r\n| `risk_assessor` | Risk analysis, compliance checks |\r\n| `orchestrator` | Coordination, task decomposition |\r\n\r\n### Step 3: Intercept Before Handoff (REQUIRED)\r\n\r\n```bash\r\n# This checks budget AND handoff limits before allowing the call\r\npython {baseDir}/scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 data\" \\\r\n --artifact # Include if expecting output\r\n```\r\n\r\n**If ALLOWED:** Proceed to Step 4\r\n**If BLOCKED:** Stop - do not call sessions_send\r\n\r\n### Step 4: Construct Handoff Message\r\n\r\nInclude these fields in your delegation:\r\n- **instruction**: Clear task description\r\n- **context**: Relevant background information\r\n- **constraints**: Any limitations or requirements\r\n- **expectedOutput**: What format/content you need back\r\n\r\n### Step 5: Send via sessions_send\r\n\r\n```\r\nsessions_send to data_analyst:\r\n\"[HANDOFF]\r\nInstruction: Analyze Q4 revenue by product category\r\nContext: Using SAP export from ./data/q4_export.csv\r\nConstraints: Focus on top 5 categories only\r\nExpected Output: JSON summary with category, revenue, growth_pct\r\n[/HANDOFF]\"\r\n```\r\n\r\n### Step 4: Check Results\r\n\r\n```\r\nsessions_history data_analyst # Get the response\r\n```\r\n\r\n## Permission Wall (AuthGuardian)\r\n\r\n**CRITICAL**: Always check permissions before accessing:\r\n- `DATABASE` - Internal database / data store access\r\n- `PAYMENTS` - Financial/payment data services\r\n- `EMAIL` - Email sending capability\r\n- `FILE_EXPORT` - Exporting data to local files\r\n\r\n> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all permission evaluation runs locally.\r\n\r\n### Permission Evaluation Criteria\r\n\r\n| Factor | Weight | Criteria |\r\n|--------|--------|----------|\r\n| Justification | 40% | Must explain specific task need |\r\n| Trust Level | 30% | Agent's established trust score |\r\n| Risk Assessment | 30% | Resource sensitivity + scope breadth |\r\n\r\n### Using the Permission Script\r\n\r\n```bash\r\n# Request permission\r\npython {baseDir}/scripts/check_permission.py \\\r\n --agent \"your_agent_id\" \\\r\n --resource \"PAYMENTS\" \\\r\n --justification \"Generating quarterly financial summary for board presentation\" \\\r\n --scope \"read:revenue,read:expenses\"\r\n\r\n# Output if approved:\r\n# ✅ GRANTED\r\n# Token: grant_a1b2c3d4e5f6\r\n# Expires: 2026-02-04T15:30:00Z\r\n# Restrictions: read_only, no_pii_fields, audit_required\r\n\r\n# Output if denied:\r\n# ❌ DENIED\r\n# Reason: Justification is insufficient. Please provide specific task context.\r\n```\r\n\r\n### Restriction Types\r\n\r\n| Resource | Default Restrictions |\r\n|----------|---------------------|\r\n| DATABASE | `read_only`, `max_records:100` |\r\n| PAYMENTS | `read_only`, `no_pii_fields`, `audit_required` |\r\n| EMAIL | `rate_limit:10_per_minute` |\r\n| FILE_EXPORT | `anonymize_pii`, `local_only` |\r\n\r\n## Shared Blackboard Pattern\r\n\r\nThe blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:\r\n\r\n```markdown\r\n# Swarm Blackboard\r\nLast Updated: 2026-02-04T10:30:00Z\r\n\r\n## Knowledge Cache\r\n### task:q4_analysis\r\n{\"status\": \"completed\", \"result\": {...}, \"agent\": \"data_analyst\"}\r\n\r\n### cache:revenue_summary \r\n{\"q4_total\": 1250000, \"growth\": 0.15}\r\n```\r\n\r\n### Blackboard Operations\r\n\r\n```bash\r\n# Write with TTL (expires after 1 hour)\r\npython {baseDir}/scripts/blackboard.py write \"cache:temp_data\" '{\"value\": 123}' --ttl 3600\r\n\r\n# Read (returns null if expired)\r\npython {baseDir}/scripts/blackboard.py read \"cache:temp_data\"\r\n\r\n# Delete\r\npython {baseDir}/scripts/blackboard.py delete \"cache:temp_data\"\r\n\r\n# Get full snapshot\r\npython {baseDir}/scripts/blackboard.py snapshot\r\n```\r\n\r\n## Parallel Execution\r\n\r\nFor tasks requiring multiple agent perspectives:\r\n\r\n### Strategy 1: Merge (Default)\r\nCombine all agent outputs into unified result.\r\n```\r\nAsk data_analyst AND strategy_advisor to both analyze the dataset.\r\nMerge their insights into a comprehensive report.\r\n```\r\n\r\n### Strategy 2: Vote\r\nUse when you need consensus - pick the result with highest confidence.\r\n\r\n### Strategy 3: First-Success\r\nUse for redundancy - take first successful result.\r\n\r\n### Strategy 4: Chain\r\nSequential processing - output of one feeds into next.\r\n\r\n### Example Parallel Workflow\r\n\r\n```\r\n1. sessions_send to data_analyst: \"Extract key metrics from Q4 data\"\r\n2. sessions_send to risk_assessor: \"Identify compliance risks in Q4 data\" \r\n3. sessions_send to strategy_advisor: \"Recommend actions based on Q4 trends\"\r\n4. Wait for all responses via sessions_history\r\n5. Synthesize: Combine metrics + risks + recommendations into executive summary\r\n```\r\n\r\n## Security Considerations\r\n\r\n1. **Never bypass the permission wall** for gated resources\r\n2. **Always include justification** explaining the business need\r\n3. **Use minimal scope** - request only what you need\r\n4. **Check token expiry** - tokens are valid for 5 minutes\r\n5. **Validate tokens** - use `python {baseDir}/scripts/validate_token.py TOKEN` to verify grant tokens before use\r\n6. **Audit trail** - all permission requests are logged\r\n\r\n## 📝 Audit Trail Requirements (MANDATORY)\r\n\r\n**Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.\r\n\r\n### What Gets Logged Automatically\r\n\r\nThe scripts automatically log these events:\r\n- `permission_granted` - When access is approved\r\n- `permission_denied` - When access is rejected\r\n- `permission_revoked` - When a token is manually revoked\r\n- `ttl_cleanup` - When expired tokens are purged\r\n- `result_validated` / `result_rejected` - Swarm Guard validations\r\n\r\n### Log Entry Format\r\n\r\n```json\r\n{\r\n \"timestamp\": \"2026-02-04T10:30:00+00:00\",\r\n \"action\": \"permission_granted\",\r\n \"details\": {\r\n \"agent_id\": \"data_analyst\",\r\n \"resource_type\": \"DATABASE\",\r\n \"justification\": \"Q4 revenue analysis\",\r\n \"token\": \"grant_abc123...\",\r\n \"restrictions\": [\"read_only\", \"max_records:100\"]\r\n }\r\n}\r\n```\r\n\r\n### Reading the Audit Log\r\n\r\n```bash\r\n# View recent entries (last 10)\r\ntail -10 {baseDir}/data/audit_log.jsonl\r\n\r\n# Search for specific agent\r\ngrep \"data_analyst\" {baseDir}/data/audit_log.jsonl\r\n\r\n# Count actions by type\r\ncat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c\r\n```\r\n\r\n### Custom Audit Entries\r\n\r\nIf you perform a sensitive action manually, log it:\r\n\r\n```python\r\nimport json\r\nfrom datetime import datetime, timezone\r\nfrom pathlib import Path\r\n\r\naudit_file = Path(\"{baseDir}/data/audit_log.jsonl\")\r\nentry = {\r\n \"timestamp\": datetime.now(timezone.utc).isoformat(),\r\n \"action\": \"manual_data_access\",\r\n \"details\": {\r\n \"agent\": \"orchestrator\",\r\n \"description\": \"Direct database query for debugging\",\r\n \"justification\": \"Investigating data sync issue #1234\"\r\n }\r\n}\r\nwith open(audit_file, \"a\") as f:\r\n f.write(json.dumps(entry) + \"\\n\")\r\n```\r\n\r\n## 🧹 TTL Enforcement (Token Lifecycle)\r\n\r\nExpired permission tokens are automatically tracked. Run periodic cleanup:\r\n\r\n```bash\r\n# Validate a grant token\r\npython {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6\r\n\r\n# List expired tokens (without removing)\r\npython {baseDir}/scripts/revoke_token.py --list-expired\r\n\r\n# Remove all expired tokens\r\npython {baseDir}/scripts/revoke_token.py --cleanup\r\n\r\n# Output:\r\n# 🧹 TTL Cleanup Complete\r\n# Removed: 3 expired token(s)\r\n# Remaining active grants: 2\r\n```\r\n\r\n**Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.\r\n\r\n## ⚠️ Swarm Guard: Preventing Common Failures\r\n\r\nTwo critical issues can derail multi-agent swarms:\r\n\r\n### 1. The Handoff Tax 💸\r\n\r\n**Problem**: Agents waste tokens \"talking about\" work instead of doing it.\r\n\r\n**Prevention**:\r\n```bash\r\n# Before each handoff, check your budget:\r\npython {baseDir}/scripts/swarm_guard.py check-handoff --task-id \"task_001\"\r\n\r\n# Output:\r\n# 🟢 Task: task_001\r\n# Handoffs: 1/3\r\n# Remaining: 2\r\n# Action Ratio: 100%\r\n```\r\n\r\n**Rules enforced**:\r\n- **Max 3 handoffs per task** - After 3, produce output or abort\r\n- **Max 500 chars per message** - Be concise: instruction + constraints + expected output\r\n- **60% action ratio** - At least 60% of handoffs must produce artifacts\r\n- **2-minute planning limit** - No output after 2min = timeout\r\n\r\n```bash\r\n# Record a handoff (with tax checking):\r\npython {baseDir}/scripts/swarm_guard.py record-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze sales data, output JSON summary\" \\\r\n --artifact # Include if this handoff produces output\r\n```\r\n\r\n### 2. Silent Failure Detection 👻\r\n\r\n**Problem**: One agent fails silently, others keep working on bad data.\r\n\r\n**Prevention - Heartbeats**:\r\n```bash\r\n# Agents must send heartbeats while working:\r\npython {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id \"task_001\"\r\n\r\n# Check if an agent is healthy:\r\npython {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst\r\n\r\n# Output if healthy:\r\n# 💚 Agent 'data_analyst' is HEALTHY\r\n# Last seen: 15s ago\r\n\r\n# Output if failed:\r\n# 💔 Agent 'data_analyst' is UNHEALTHY\r\n# Reason: STALE_HEARTBEAT\r\n# → Do NOT use any pending results from this agent.\r\n```\r\n\r\n**Prevention - Result Validation**:\r\n```bash\r\n# Before using another agent's result, validate it:\r\npython {baseDir}/scripts/swarm_guard.py validate-result \\\r\n --task-id \"task_001\" \\\r\n --agent data_analyst \\\r\n --result '{\"status\": \"success\", \"output\": {\"revenue\": 125000}, \"confidence\": 0.85}'\r\n\r\n# Output:\r\n# ✅ RESULT VALID\r\n# → APPROVED - Result can be used by other agents\r\n```\r\n\r\n**Required result fields**: `status`, `output`, `confidence`\r\n\r\n### Supervisor Review\r\n\r\nBefore finalizing any task, run supervisor review:\r\n```bash\r\npython {baseDir}/scripts/swarm_guard.py supervisor-review --task-id \"task_001\"\r\n\r\n# Output:\r\n# ✅ SUPERVISOR VERDICT: APPROVED\r\n# Task: task_001\r\n# Age: 1.5 minutes\r\n# Handoffs: 2\r\n# Artifacts: 2\r\n```\r\n\r\n**Verdicts**:\r\n- `APPROVED` - Task healthy, results usable\r\n- `WARNING` - Issues detected, review recommended\r\n- `BLOCKED` - Critical failures, do NOT use results\r\n\r\n## Troubleshooting\r\n\r\n### Permission Denied\r\n- Provide more specific justification (mention task, purpose, expected outcome)\r\n- Narrow the requested scope\r\n- Check agent trust level\r\n\r\n### Blackboard Read Returns Null\r\n- Entry may have expired (check TTL)\r\n- Key may be misspelled\r\n- Entry was never written\r\n\r\n### Session Not Found\r\n- Run `sessions_list` to see available sessions\r\n- Session may need to be started first\r\n\r\n## References\r\n\r\n- [AuthGuardian Details](references/auth-guardian.md) - Full permission system documentation\r\n- [Blackboard Schema](references/blackboard-schema.md) - Data structure specifications\r\n- [Agent Trust Levels](references/trust-levels.md) - How trust is calculated\n\nFile v4.0.14:_meta.json\n\n{\n \"ownerId\": \"kn75j1xcebk74re38bv714kh1h81804p\",\n \"slug\": \"network-ai\",\n \"version\": \"4.0.14\",\n \"publishedAt\": 1772305198541\n}\n\nFile v4.0.14:ARCHITECTURE.md\n\n# Architecture\r\n\r\n## The Multi-Agent Race Condition Problem\r\n\r\nMost agent frameworks let you run multiple AI agents in parallel. None of them protect you when those agents write to the same resource at the same time.\r\n\r\n**The \"Bank Run\" scenario:**\r\n\r\n```\r\nAgent A reads balance: $10,000\r\nAgent B reads balance: $10,000 (same moment)\r\nAgent A writes balance: $10,000 - $7,000 = $3,000\r\nAgent B writes balance: $10,000 - $6,000 = $4,000 ← Agent A's write is gone\r\n```\r\n\r\nBoth agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.\r\n\r\nWithout concurrency control, parallel agents will:\r\n- **Corrupt shared state** — two agents overwrite each other's blackboard entries\r\n- **Double-spend budgets** — token costs exceed limits because agents don't see each other's spending\r\n- **Produce contradictory outputs** — Agent A says \"approved\", Agent B says \"denied\", both write to the same key\r\n\r\n**How Network-AI prevents this:**\r\n\r\n```typescript\r\n// Atomic commit — no other agent can read/write \"account:balance\" during this operation\r\nconst changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');\r\nblackboard.validateChange(changeId); // checks for conflicts\r\nblackboard.commitChange(changeId); // atomic write with file-system mutex\r\n```\r\n\r\n---\r\n\r\n## Component Overview\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────┐\r\n│ Your Application │\r\n└──────────────────────────┬──────────────────────────────────┘\r\n │ createSwarmOrchestrator()\r\n┌──────────────────────────▼──────────────────────────────────┐\r\n│ SwarmOrchestrator │\r\n│ │\r\n│ ┌──────────────┐ ┌───────────────┐ ┌─────────────────┐ │\r\n│ │ AdapterRegistry│ │ AuthGuardian │ │ FederatedBudget │ │\r\n│ │ (route tasks) │ │ (permissions) │ │ (token ceilings)│ │\r\n│ └──────┬───────┘ └───────────────┘ └─────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼──────────────────────────────────────────────┐ │\r\n│ │ LockedBlackboard (shared state) │ │\r\n│ │ propose → validate → commit (file-system mutex) │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼───────────────────────────────────────────────┐ │\r\n│ │ Adapters (plug any framework in, swap out freely) │ │\r\n│ │ LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │… │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n└─────────────────────────────────────────────────────────────┘\r\n │\r\n HMAC-signed audit log (data/audit_log.jsonl)\r\n```\r\n\r\n### LockedBlackboard\r\n\r\nThe coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss.\r\n\r\n- `propose(key, value, agentId, ttl?, priority?)` — stages a change, detects conflicts\r\n- `validate(changeId, validatorId)` — confirms no race occurred since propose\r\n- `commit(changeId)` — atomic write\r\n- Conflict strategies: `first-commit-wins`, `priority-wins`, `last-write-wins`\r\n\r\n### AuthGuardian\r\n\r\nPermission gating before sensitive operations. Agents must request a token with a business justification — the guardian evaluates trust level, resource risk, and justification quality before granting.\r\n\r\n```typescript\r\nconst grant = auth.requestPermission('data_analyst', 'DATABASE', 'read',\r\n 'Need customer order history for sales report');\r\n// grant.token is scoped HMAC-signed token with TTL\r\n```\r\n\r\nResource types: `DATABASE` (risk 0.5), `PAYMENTS` (0.7), `EMAIL` (0.4), `FILE_EXPORT` (0.6)\r\n\r\nPermission scoring: justification quality 40%, agent trust level 30%, resource risk 30%. Threshold: 0.5.\r\n\r\n### FederatedBudget\r\n\r\nHard token ceilings per agent and per task. Even if 5 agents run in parallel, total spend cannot exceed the budget.\r\n\r\n```bash\r\npython scripts/swarm_guard.py budget-init --task-id \"task_001\" --budget 10000\r\npython scripts/swarm_guard.py budget-check --task-id \"task_001\"\r\npython scripts/swarm_guard.py budget-report --task-id \"task_001\"\r\n```\r\n\r\n### AdapterRegistry\r\n\r\nRoutes tasks to the right agent/framework automatically. Register multiple adapters and the registry dispatches by agent ID.\r\n\r\n```typescript\r\nconst registry = new AdapterRegistry();\r\nregistry.register('my-langchain-agent', langchainAdapter);\r\nregistry.register('my-autogen-agent', autogenAdapter);\r\n```\r\n\r\n---\r\n\r\n## FSM Journey (JourneyFSM)\r\n\r\nThe FSM governs agent phase transitions for long-running pipelines. Each phase transition is:\r\n- Gated by AuthGuardian tokens\r\n- Logged to the audit trail\r\n- Subject to timeout enforcement\r\n\r\n```\r\nIDLE → PLANNING → EXECUTING → REVIEWING → COMMITTING → COMPLETE\r\n ↓\r\n BLOCKED (on violation)\r\n```\r\n\r\nComplianceMonitor captures violations in real-time:\r\n- `TOOL_ABUSE` — too many rapid writes\r\n- `TURN_TAKING` — consecutive actions without yield\r\n- `RESPONSE_TIMEOUT` — agent exceeds time budget\r\n- `JOURNEY_TIMEOUT` — overall pipeline exceeds wall-clock limit\r\n\r\n---\r\n\r\n## Handoff Protocol\r\n\r\nFormat messages for delegation between agents:\r\n\r\n```\r\n[HANDOFF]\r\nInstruction: Analyze monthly sales by product category\r\nContext: Using database export from ./data/sales_export.csv\r\nConstraints: Focus on top 5 categories only\r\nExpected Output: JSON summary with category, revenue, growth_pct\r\n[/HANDOFF]\r\n```\r\n\r\nBudget-aware handoff (wraps `sessions_send` with budget checks):\r\n\r\n```bash\r\npython scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 revenue data\"\r\n```\r\n\r\nOutput:\r\n```\r\nHANDOFF ALLOWED: orchestrator -> data_analyst\r\n Tokens spent: 156\r\n Budget remaining: 9,844\r\n Handoff #1 (remaining: 2)\r\n -> Proceed with sessions_send\r\n```\r\n\r\n---\r\n\r\n## Content Quality Gate\r\n\r\nTwo-layer validation before blackboard writes:\r\n\r\n**Layer 1 — BlackboardValidator (rule-based, zero LLM calls)**\r\n- Hallucination detection (vague, unsupported, fabricated content)\r\n- Dangerous code detection (`eval()`, `exec()`, `rm -rf`)\r\n- Placeholder rejection (TODO/FIXME/stub content)\r\n- Throughput: ~500,000 ops/sec on 1 KB inputs\r\n\r\n**Layer 2 — QualityGateAgent (AI-assisted)**\r\n- Async, intended for high-value writes only\r\n- Quarantine system for suspicious content\r\n- Adds LLM latency — use selectively\r\n\r\n---\r\n\r\n## Agent Trust Levels\r\n\r\n| Agent | Trust | Role |\r\n|---|---|---|\r\n| `orchestrator` | 0.9 | Primary coordinator |\r\n| `risk_assessor` | 0.85 | Compliance specialist |\r\n| `data_analyst` | 0.8 | Data processing |\r\n| `strategy_advisor` | 0.7 | Business strategy |\r\n| Unknown | 0.5 | Default |\r\n\r\nConfigure in `scripts/check_permission.py`:\r\n\r\n```python\r\nDEFAULT_TRUST_LEVELS = {\r\n \"orchestrator\": 0.9,\r\n \"my_new_agent\": 0.75,\r\n}\r\nGRANT_TOKEN_TTL_MINUTES = 5\r\n```\r\n\r\n---\r\n\r\n## Project Structure\r\n\r\n```\r\nNetwork-AI/\r\n├── index.ts # Core orchestrator (SwarmOrchestrator, AuthGuardian, TaskDecomposer)\r\n├── security.ts # Security module (tokens, encryption, rate limiting, audit)\r\n├── setup.ts # Developer setup & installation checker\r\n├── adapters/ # 12 plug-and-play agent framework adapters\r\n│ ├── adapter-registry.ts # Multi-adapter routing & discovery\r\n│ ├── base-adapter.ts # Abstract base class\r\n│ ├── custom-adapter.ts # Custom function/HTTP agent adapter\r\n│ ├── langchain-adapter.ts\r\n│ ├── autogen-adapter.ts\r\n│ ├── crewai-adapter.ts\r\n│ ├── mcp-adapter.ts\r\n│ ├── llamaindex-adapter.ts\r\n│ ├── semantic-kernel-adapter.ts\r\n│ ├── openai-assistants-adapter.ts\r\n│ ├── haystack-adapter.ts\r\n│ ├── dspy-adapter.ts\r\n│ ├── agno-adapter.ts\r\n│ └── openclaw-adapter.ts\r\n├── lib/\r\n│ ├── locked-blackboard.ts # Atomic commits with file-system mutexes\r\n│ ├── blackboard-validator.ts # Content quality gate (Layer 1 + Layer 2)\r\n│ ├── fsm-journey.ts # FSM state machine and compliance monitor\r\n│ └── swarm-utils.ts # Helper utilities\r\n├── scripts/ # Python helper scripts (local orchestration only)\r\n│ ├── blackboard.py # Shared state management with atomic commits\r\n│ ├── swarm_guard.py # Handoff tax prevention, budget tracking\r\n│ ├── check_permission.py # AuthGuardian permission checker + active grants\r\n│ ├── validate_token.py # Token validation\r\n│ └── revoke_token.py # Token revocation + TTL cleanup\r\n├── types/\r\n│ ├── agent-adapter.d.ts # Universal adapter interfaces\r\n│ └── openclaw-core.d.ts # OpenClaw type stubs\r\n├── references/ # Deep-dive documentation\r\n│ ├── adapter-system.md\r\n│ ├── auth-guardian.md\r\n│ ├── blackboard-schema.md\r\n│ ├── trust-levels.md\r\n│ └── mcp-roadmap.md\r\n├── examples/ # Runnable examples (01–06)\r\n│ ├── 01-hello-swarm.ts\r\n│ ├── 02-fsm-pipeline.ts\r\n│ ├── 03-parallel-agents.ts\r\n│ ├── 04-live-swarm.ts\r\n│ └── 05-code-review-swarm.ts\r\n└── data/\r\n ├── audit_log.jsonl # HMAC-signed audit trail (local only)\r\n └── pending_changes/ # In-flight atomic change records\r\n```\n\nFile v4.0.14:AWESOME_LISTS.md\n\n# Awesome List PR Submissions\r\n\r\nReady-to-use PR titles, one-liners, and context for each list.\r\nSubmit these as pull requests to the respective repositories.\r\n\r\n---\r\n\r\n## 1. awesome-mcp-servers\r\n**Repo:** https://github.com/punkpeye/awesome-mcp-servers\r\n\r\n**PR title:**\r\n> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration MCP server. 20+ MCP tools: blackboard read/write, agent spawn/stop, FSM transitions, budget tracking, token management, audit log query. `npx network-ai-server --port 3001`. TypeScript/Node.js.\r\n```\r\n\r\n**Where to add it:** Under the orchestration or multi-agent section.\r\n\r\n**PR body:**\r\n> network-ai ships a production-ready MCP server (`network-ai-server` binary) that exposes the full orchestration control plane over HTTP/SSE + JSON-RPC 2.0. It includes 20+ tools across 4 groups: blackboard coordination (read/write/lock), agent control (spawn/stop/list), FSM governance (transition/state), and observability (budget status, audit trail, token lifecycle). Zero config — `npx network-ai-server` starts immediately.\r\n\r\n---\r\n\r\n## 2. awesome-ai-agents\r\n**Repo:** https://github.com/e2b-dev/awesome-ai-agents\r\n\r\n**PR title:**\r\n> Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Plug-and-play multi-agent orchestration for TypeScript/Node.js. Connects 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, MCP, and more) with atomic shared state, FSM governance, per-agent budget enforcement, and cryptographic audit trails. Solves race conditions and split-brain writes in concurrent agent systems.\r\n```\r\n\r\n**PR body:**\r\n> network-ai fills a gap that most agent frameworks leave open: safe coordination when agents share state. It wraps any agent framework via adapters (12 supported) and adds atomic blackboard writes, FSM state gating, per-agent token budget ceilings, and a ComplianceMonitor for behavioral governance. MIT licensed, 1,200+ tests, CodeQL + OpenSSF Scorecard.\r\n\r\n---\r\n\r\n## 3. awesome-langchain\r\n**Repo:** https://github.com/kyrolabs/awesome-langchain\r\n\r\n**PR title:**\r\n> Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration framework with a first-class LangChain adapter. Wraps LangChain Runnables, chains, and agents with atomic shared state, permission gating, budget enforcement, and FSM governance. Prevents race conditions when multiple LangChain agents write to shared resources concurrently.\r\n```\r\n\r\n**Where to add it:** Under Tools / Agent frameworks / Orchestration.\r\n\r\n---\r\n\r\n## 4. awesome-llamaindex\r\n**Repo:** https://github.com/emptycrown/awesome-llamaindex (or the official one)\r\n\r\n**PR title:**\r\n> Add network-ai — orchestration layer with LlamaIndex adapter\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Orchestration framework with a LlamaIndex adapter supporting query engines, chat engines, and agent runners. Adds atomic shared state, FSM governance, and per-agent budget ceilings to LlamaIndex-based pipelines.\r\n```\r\n\r\n---\r\n\r\n## 5. awesome-mcp (or MCP-related lists)\r\n**Search:** github.com/topics/model-context-protocol\r\n\r\n**PR title:**\r\n> Add network-ai — MCP server + client transport for multi-agent orchestration\r\n\r\n**One-liner:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - MCP server (`network-ai-server`) and transport (`McpSseTransport`) for multi-agent orchestration. Exposes blackboard, FSM, budget, token, and audit tools over SSE/JSON-RPC 2.0. Also includes an MCP adapter so MCP tool handlers can be registered as governed agents.\r\n```\r\n\r\n---\r\n\r\n## Submission checklist\r\n\r\nBefore each PR:\r\n- [ ] Fork the target repo\r\n- [ ] Add the one-liner in alphabetical order by tool name within its section\r\n- [ ] PR title follows the repo's existing convention (check other recent PRs)\r\n- [ ] Verify the repo's README or CONTRIBUTING.md for any format requirements\r\n- [ ] Star the repo before submitting (improves PR acceptance rate)\r\n\r\n## Other lists to check\r\n\r\n- https://github.com/jim-schwoebel/awesome-ai-frameworks\r\n- https://github.com/AgentOps-AI/agentops (list of frameworks)\r\n- https://github.com/topics/ai-agents (GitHub topic — add `ai-agents` to repo if not there)\r\n- Product Hunt — \"AI Developer Tools\" category launch\n\nFile v4.0.14:BENCHMARKS.md\n\n# Benchmarks & Performance\r\n\r\n> Performance data for Network-AI deployments. Your swarm is only as fast as the backend it calls — this page helps you choose the right setup.\r\n\r\n## BlackboardValidator Throughput\r\n\r\nLayer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:\r\n\r\n| Input size | Ops/sec | Latency |\r\n|---|---|---|\r\n| Small entry (~100 chars) | ~1,000,000 | < 1 µs |\r\n| Medium entry (~1 KB) | ~500,000 | ~2 µs |\r\n| Large entry (~10 KB) | ~159,000 | ~6 µs |\r\n\r\nLayer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.\r\n\r\n---\r\n\r\n## Cloud Provider Performance\r\n\r\nNot all cloud APIs perform the same. Model size, inference infrastructure, and tier all affect how fast each agent gets a response — and that directly multiplies across every agent in your swarm.\r\n\r\n| Provider / Model | Avg response (5-agent swarm) | RPM limit (free/tier-1) | Notes |\r\n|---|---|---|---|\r\n| **OpenAI gpt-5.2** | 6–10s per call | 3–6 RPM | Flagship model, high latency, strict RPM |\r\n| **OpenAI gpt-4o-mini** | 2–4s per call | 500 RPM | Fast, cheap, good for reviewer agents |\r\n| **OpenAI gpt-4o** | 4–7s per call | 60–500 RPM | Balanced quality/speed |\r\n| **Anthropic Claude 3.5 Haiku** | 2–3s per call | 50 RPM | Fastest Claude, great for parallel agents |\r\n| **Anthropic Claude 3.7 Sonnet** | 4–8s per call | 50 RPM | Stronger reasoning, higher latency |\r\n| **Google Gemini 2.0 Flash** | 1–3s per call | 15 RPM (free) | Very fast inference, low RPM on free tier |\r\n| **Groq (Llama 3.3 70B)** | 0.5–2s per call | 30 RPM | Fastest cloud inference available |\r\n| **Together AI / Fireworks** | 1–3s per call | Varies by plan | Good for parallel workloads |\r\n\r\n**Key insight:** A 5-agent swarm using `gpt-4o-mini` at 500 RPM can fire all 5 agents truly in parallel and finish in ~4s total. The same swarm on `gpt-5.2` at 6 RPM must go sequential and takes 60s. **The model tier matters more than the orchestration framework.**\r\n\r\n### Choosing a Model for Swarm Agents\r\n\r\n- **Speed over depth** (many agents, real-time) → `gpt-4o-mini`, `claude-3.5-haiku`, `gemini-2.0-flash`, `groq/llama-3.3-70b`\r\n- **Depth over speed** (few agents, high-stakes) → `gpt-4o`, `claude-3.7-sonnet`\r\n- **Free / no-cost testing** → Groq free tier, Gemini free tier, or Ollama locally\r\n- **Production with budget** → multiple keys across providers, route agents to different models\r\n\r\n---\r\n\r\n## Rate Limit Patterns\r\n\r\nWhen you run a 5-agent swarm sharing one API key and hit the RPM ceiling, the API silently returns empty responses — not a 429 error, just blank content. Network-AI's swarm demos handle this automatically with **sequential dispatch** and **adaptive header-based pacing** (reads `x-ratelimit-reset-requests` to wait exactly as long as needed).\r\n\r\n| You have | What to expect |\r\n|---|---|\r\n| One cloud API key | Sequential dispatch, 40–70s per 5-agent swarm — handled automatically |\r\n| Multiple cloud keys | Near-parallel, 10–15s — one key per adapter instance |\r\n| Local GPU (Ollama, vLLM) | True parallel, 5–20s depending on hardware |\r\n| Home GPU + cloud mix | Local agents never block — cloud agents rate-paced independently |\r\n\r\n### Multiple Keys = True Parallel\r\n\r\n```typescript\r\nimport { CustomAdapter, AdapterRegistry } from 'network-ai';\r\n\r\nconst registry = new AdapterRegistry();\r\n\r\nfor (const reviewer of REVIEWERS) {\r\n const adapter = new CustomAdapter();\r\n const client = new OpenAI({ apiKey: process.env[`OPENAI_KEY_${reviewer.id.toUpperCase()}`] });\r\n\r\n adapter.registerHandler(reviewer.id, async (payload) => {\r\n const resp = await client.chat.completions.create({ /* ... */ });\r\n return { findings: extractContent(resp) };\r\n });\r\n\r\n registry.register(reviewer.id, adapter);\r\n}\r\n\r\n// All 5 dispatch in parallel via Promise.all — ~8–12s instead of ~60s\r\n```\r\n\r\n### Local GPU = Zero Rate Limits\r\n\r\n```typescript\r\nconst localClient = new OpenAI({\r\n apiKey : 'not-needed',\r\n baseURL: 'http://localhost:11434/v1', // Ollama, vLLM, llama.cpp\r\n});\r\n\r\nadapter.registerHandler('reviewer', async (payload) => {\r\n const resp = await localClient.chat.completions.create({\r\n model : 'llama3.2',\r\n messages: [/* ... */],\r\n });\r\n return { findings: extractContent(resp) };\r\n});\r\n```\r\n\r\n---\r\n\r\n## Cloud GPU Instances (Self-Hosted)\r\n\r\nRunning your own model on AWS / GCP / Azure sits between managed APIs and local hardware:\r\n\r\n| Setup | Speed vs managed API | RPM |\r\n|---|---|---|\r\n| A100 (80GB) + vLLM, Llama 3.3 70B | Faster — 0.5–2s/call | None |\r\n| H100 + vLLM, Mixtral 8x7B | Faster — 0.3–1s/call | None |\r\n| T4 / V100 + Ollama, Llama 3.2 8B | Comparable | None |\r\n\r\nCost: $1–5/hr for GPU VMs. For high-volume production swarms or teams that want no external API dependency, it is the fastest architecture available. The connection is identical to local Ollama — just point `baseURL` at your VM's IP.\r\n\r\n---\r\n\r\n## `max_completion_tokens` — The Silent Truncation Trap\r\n\r\nOne of the most common failure modes in agentic output tasks. When a model hits the `max_completion_tokens` ceiling it stops mid-output and returns whatever it has — no error, no warning. The API call succeeds with `finish_reason: \"length\"` instead of `\"stop\"`.\r\n\r\n**This is especially dangerous for code-rewrite agents** where the output is a full file.\r\n\r\n```\r\n# Real numbers (gpt-5-mini, order-service.ts rewrite):\r\n Blockers section: ~120 tokens\r\n Fixed code: ~2,800 tokens (213 lines with // FIX: comments)\r\n Total needed: ~3,000 tokens ← hits the cap exactly → empty output\r\n Fix: set to 16,000 → full rewrite delivered in one shot\r\n```\r\n\r\n### Rule of Thumb by Task\r\n\r\n| Task | Recommended cap |\r\n|---|---|\r\n| Short classification / sentiment | 200–500 |\r\n| Code review findings (one reviewer) | 400–800 |\r\n| Blocker summary (coordinator) | 500–1,000 |\r\n| Full file rewrite (≤300 lines) | 12,000–16,000 |\r\n| Full file rewrite (≤1,000 lines) | 32,000–64,000 |\r\n| Document / design revision | 16,000–32,000 |\r\n\r\nAll GPT-5 variants support **128,000 max output tokens** — the ceiling is never the model, it is always the cap you set.\r\n\r\n### Lessons from Building the Code-Review Swarm\r\n\r\n| Issue | Root cause | Fix |\r\n|---|---|---|\r\n| Fixed code output was empty | `max_completion_tokens: 3000` too low | Raise to `16000`+ for any code-output agent |\r\n| `finish_reason: \"length\"` silently discards | Model hits cap, partial response, no error | Always check `choices[0].finish_reason` and alert on `\"length\"` |\r\n| Flagship model slow + expensive for reviewers | High latency + $14/1M output tokens | Use `gpt-5-mini` ($2/1M, same RPM) for reviewer/fixer agents |\r\n| Coordinator + fixer as two calls | Second call hits rate limit window, +60s | Merge into one structured two-section call |\n\nFile v4.0.14:INTEGRATION_GUIDE.md\n\n# Network-AI Integration Guide\r\n\r\n**For technical leads, solutions architects, and engineering teams evaluating or deploying Network-AI in a production environment.**\r\n\r\nThis guide walks from \"we want this\" to \"it's running in production\" — covering discovery, framework mapping, phased rollout, enterprise concerns, and validation.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Before You Start — Discovery](#1-before-you-start--discovery)\r\n2. [Framework Mapping](#2-framework-mapping)\r\n3. [Primitive Mapping — What Solves What](#3-primitive-mapping--what-solves-what)\r\n4. [Phased Rollout](#4-phased-rollout)\r\n5. [Enterprise Concerns](#5-enterprise-concerns)\r\n6. [Architecture Patterns](#6-architecture-patterns)\r\n7. [Validation Checklist](#7-validation-checklist)\r\n8. [Common Integration Mistakes](#8-common-integration-mistakes)\r\n\r\n---\r\n\r\n## 1. Before You Start — Discovery\r\n\r\nBefore touching any code, answer these questions. They determine which adapters you need and which governance primitives are non-negotiable.\r\n\r\n### 1.1 Agent Inventory\r\n\r\nDocument every AI agent or automated process your team currently runs:\r\n\r\n| Agent / Process | Language | Framework | Shares State With | Writes To |\r\n|----------------|----------|-----------|-------------------|-----------|\r\n| e.g. \"invoice classifier\" | Python | LangChain | \"approvals bot\" | Postgres |\r\n| e.g. \"customer triage\" | Node | AutoGen | \"CRM writer\" | Salesforce API |\r\n\r\n> **Why this matters:** Each row maps to one or more Network-AI adapters. Agents that share state with others are your highest-risk race condition points.\r\n\r\n### 1.2 Race Condition Audit\r\n\r\nFor each pair of agents that write to the same resource, ask:\r\n\r\n- Can both agents run at the same time?\r\n- What happens if Agent A's write is overwritten by Agent B before Agent A reads it back?\r\n- Is there any locking or retry logic today?\r\n\r\nIf the answer to the first question is \"yes\" and the second is \"data loss / wrong decision / double spend\" — that's a `LockedBlackboard` candidate.\r\n\r\n### 1.3 Budget and Cost Exposure\r\n\r\n- Do you have per-agent token limits today?\r\n- Can a single runaway agent exhaust your OpenAI / Anthropic budget?\r\n- Do you have hard cut-offs or just alerts?\r\n\r\nNetwork-AI's `FederatedBudget` enforces hard ceilings. If you have no ceiling today, this is your first priority.\r\n\r\n### 1.4 Compliance and Audit Requirements\r\n\r\n- Does your industry require audit trails for automated decisions (GDPR, SOC 2, HIPAA, PCI-DSS)?\r\n- Do you need to prove *which agent* made *which decision* and *when*?\r\n- Are there regulatory rules about which systems an AI agent may access?\r\n\r\nAnswers drive `AuthGuardian` configuration and audit log retention policy.\r\n\r\n---\r\n\r\n## 2. Framework Mapping\r\n\r\nNetwork-AI ships 12 adapters. Map your existing agents to the right one:\r\n\r\n| Your Stack | Network-AI Adapter | Notes |\r\n|-----------|-------------------|-------|\r\n| LangChain (JS/TS) | `LangChainAdapter` | Supports Runnables, chains, agents |\r\n| AutoGen / AG2 | `AutoGenAdapter` | Supports `.run()` and `.generateReply()` |\r\n| CrewAI | `CrewAIAdapter` | Individual agents and full crew objects |\r\n| OpenAI Assistants | `OpenAIAssistantsAdapter` | Thread management included |\r\n| LlamaIndex | `LlamaIndexAdapter` | Query engines, chat engines, agent runners |\r\n| Semantic Kernel | `SemanticKernelAdapter` | Microsoft SK kernels, functions, planners |\r\n| Haystack | `HaystackAdapter` | Pipelines, agents, components |\r\n| DSPy | `DSPyAdapter` | Modules, programs, predictors |\r\n| Agno (ex-Phidata) | `AgnoAdapter` | Agents, teams, functions |\r\n| MCP tools | `McpAdapter` | Tool serving and discovery |\r\n| OpenClaw / Clawdbot / Moltbot | `OpenClawAdapter` | Native skill execution via `callSkill` |\r\n| **Anything else** | `CustomAdapter` | Wrap any async function or HTTP endpoint |\r\n\r\n### No matching framework?\r\n\r\nUse `CustomAdapter`. Any async function becomes a governed agent in three lines:\r\n\r\n```typescript\r\nimport { CustomAdapter } from 'network-ai';\r\n\r\nconst adapter = new CustomAdapter();\r\nadapter.registerHandler('my-agent', async (payload) => {\r\n // your existing logic here — unchanged\r\n return { result: '...' };\r\n});\r\n```\r\n\r\nThis is the recommended entry point for **legacy systems**, **internal microservices**, and **REST APIs** — you do not need to rewrite anything.\r\n\r\n---\r\n\r\n## 3. Primitive Mapping — What Solves What\r\n\r\nMatch your problem to the Network-AI primitive:\r\n\r\n| Problem | Primitive | How |\r\n|---------|-----------|-----|\r\n| Two agents overwriting each other's data | `LockedBlackboard` | Atomic `propose → validate → commit` with file-system mutex |\r\n| Agent overspending token budget | `FederatedBudget` | Per-agent ceiling; hard cut-off on overspend |\r\n| Agent accessing a resource it shouldn't | `AuthGuardian` + `SecureTokenManager` | HMAC-signed scoped tokens required at every sensitive operation |\r\n| No audit trail for automated decisions | Audit log (`data/audit_log.jsonl`) | Cryptographic HMAC-signed chain, every write recorded |\r\n| Agent running out of turn / taking too many actions | `ComplianceMonitor` | TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT detected in real time |\r\n| Workflow needs defined states (e.g. INTAKE → REVIEW → APPROVE) | `JourneyFSM` | State machine gates which agents may act in which states |\r\n| Content safety / hallucination in agent outputs | `QualityGateAgent` + `BlackboardValidator` | Two-layer validation before output enters the blackboard |\r\n| Race conditions in parallel agent writes | `LockedBlackboard` with `priority-wins` | Higher-priority agents preempt lower-priority writes on conflict |\r\n| Need to expose all tools to an AI via MCP | `McpSseServer` + `network-ai-server` | HTTP/SSE server at `GET /sse`, `POST /mcp`, `GET /tools` |\r\n| Runtime AI control of the orchestrator | `ControlMcpTools` | AI can read/set config, spawn/stop agents, drive FSM transitions |\r\n\r\n---\r\n\r\n## 4. Phased Rollout\r\n\r\nDo not try to enable everything at once. This is the recommended sequence for a zero-disruption integration:\r\n\r\n### Phase 1 — Wrap (Day 1–3)\r\n\r\n**Goal:** Get your existing agents running inside Network-AI without changing their behaviour.\r\n\r\n1. `npm install network-ai`\r\n2. Wrap each agent in the matching adapter (see §2)\r\n3. Register all adapters with `AdapterRegistry`\r\n4. Replace direct agent calls with `registry.executeAgent(...)` or `orchestrator.execute(...)`\r\n5. Run `npm run demo -- --08` to verify the framework itself is healthy in your environment\r\n\r\n**Nothing changes behaviourally yet.** This phase is purely structural.\r\n\r\n```typescript\r\nimport { createSwarmOrchestrator, CustomAdapter } from 'network-ai';\r\n\r\nconst orchestrator = createSwarmOrchestrator({ swarmName: 'acme-swarm' });\r\nconst adapter = new CustomAdapter();\r\n\r\n// Wrap your existing function — unchanged\r\nadapter.registerHandler('invoice-classifier', async (payload) => {\r\n return await yourExistingClassifier(payload.params);\r\n});\r\n\r\nawait orchestrator.addAdapter(adapter);\r\n```\r\n\r\n---\r\n\r\n### Phase 2 — Shared State (Day 3–7)\r\n\r\n**Goal:** Replace ad-hoc shared resources (databases, files, in-memory objects) with the blackboard.\r\n\r\n1. Identify all keys agents share (from your §1.1 audit)\r\n2. Introduce `SharedBlackboard` for low-contention data\r\n3. Introduce `LockedBlackboard` for any key that two or more agents write to concurrently\r\n\r\n```typescript\r\nimport { LockedBlackboard } from 'network-ai';\r\n\r\nconst board = new LockedBlackboard('.', { conflictResolution: 'priority-wins' });\r\n\r\n// Atomic write — no other agent can interfere during this operation\r\nconst changeId = board.proposeChange('account:balance', newBalance, 'payment-agent');\r\nboard.validateChange(changeId);\r\nboard.commitChange(changeId);\r\n```\r\n\r\n> **Migration tip:** Start by shadowing — write to both your existing DB and the blackboard simultaneously. Once you're confident they match, remove the DB writes.\r\n\r\n---\r\n\r\n### Phase 3 — Budget Enforcement (Day 7–10)\r\n\r\n**Goal:** Add hard token ceilings so no single agent can exhaust your LLM budget.\r\n\r\n```typescript\r\nimport { FederatedBudget } from 'network-ai/lib/federated-budget';\r\n\r\nconst budget = new FederatedBudget({\r\n pools: {\r\n 'classifier': { ceiling: 50_000 }, // tokens per run\r\n 'summarizer': { ceiling: 100_000 },\r\n 'orchestrator': { ceiling: 200_000 },\r\n }\r\n});\r\n\r\n// Check before each LLM call\r\nconst check = budget.canSpend('classifier', estimatedTokens);\r\nif (!check.allowed) throw new Error(`Budget ceiling reached: ${check.reason}`);\r\n\r\n// Record actual spend after\r\nbudget.recordSpend('classifier', actualTokens);\r\n```\r\n\r\nMap your cost centers to pool names. Budget state persists across agent runs.\r\n\r\n---\r\n\r\n### Phase 4 — Access Control (Day 10–14)\r\n\r\n**Goal:** Gate access to sensitive APIs and resources behind cryptographically signed tokens.\r\n\r\n1. Define your resources and risk levels (see `references/auth-guardian.md`)\r\n2. Map your agents to trust levels (see `references/trust-levels.md`)\r\n3. Replace direct API calls with `AuthGuardian`-gated calls\r\n\r\n```typescript\r\nimport { AuthGuardian, SecureTokenManager } from 'network-ai';\r\n\r\nconst guardian = new AuthGuardian();\r\nconst tokenManager = new SecureTokenManager(process.env.HMAC_SECRET!);\r\n\r\n// Agent requests access with a justification\r\nconst request = await guardian.requestPermission({\r\n agentId: 'payment-agent',\r\n resource: 'PAYMENTS',\r\n action: 'write',\r\n justification: 'Processing approved invoice #INV-2847 per workflow step 3',\r\n trustLevel: 0.8,\r\n});\r\n\r\nif (request.approved) {\r\n const token = tokenManager.createToken('payment-agent', ['PAYMENTS:write'], 300);\r\n // pass token to downstream call\r\n}\r\n```\r\n\r\n**IAM integration:** The token payload (agentId, permissions, expiry) can be forwarded as a JWT claim to your existing IAM layer. Network-AI does not replace your IAM — it sits in front of it as a pre-authorization layer.\r\n\r\n---\r\n\r\n### Phase 5 — Governance and FSM (Day 14–21)\r\n\r\n**Goal:** Define explicit workflow states so agents can only act when the system is in the right state.\r\n\r\n```typescript\r\nimport { JourneyFSM, WORKFLOW_STATES } from 'network-ai';\r\n\r\nconst fsm = new JourneyFSM({\r\n agentId: 'workflow',\r\n journeyId: 'invoice-processing',\r\n transitions: [\r\n { from: 'INTAKE', to: 'ANALYZE', allowedAgents: ['intake-agent'] },\r\n { from: 'ANALYZE', to: 'APPROVE', allowedAgents: ['analyst-agent'] },\r\n { from: 'APPROVE', to: 'EXECUTE', allowedAgents: ['approver-agent'] },\r\n { from: 'EXECUTE', to: 'DELIVER', allowedAgents: ['payment-agent'] },\r\n ]\r\n});\r\n\r\n// Before any agent acts, check the FSM\r\nconst canAct = fsm.canTransition(currentState, nextState, agentId);\r\n```\r\n\r\nAdd `ComplianceMonitor` to detect violations in real time without blocking the main thread:\r\n\r\n```typescript\r\nimport { ComplianceMonitor } from 'network-ai';\r\n\r\nconst monitor = new ComplianceMonitor(fsm, {\r\n maxActionsPerTurn: 5,\r\n responseTimeoutMs: 30_000,\r\n journeyTimeoutMs: 300_000,\r\n});\r\nmonitor.start(1_000); // poll every second\r\n```\r\n\r\n---\r\n\r\n### Phase 6 — Observability and MCP (Day 21+)\r\n\r\n**Goal:** Expose everything to your monitoring stack and optionally give your AI models control-plane access.\r\n\r\nStart the MCP server (exposes 20+ tools via SSE/JSON-RPC):\r\n\r\n```bash\r\nnpx network-ai-server --port 3001 --audit-log data/audit_log.jsonl --ceiling 500000\r\n```\r\n\r\nConnect your AI model to `http://localhost:3001/sse` — it can now:\r\n- Read and write live config (`config_get`, `config_set`)\r\n- Spawn and stop agents (`agent_spawn`, `agent_stop`)\r\n- Drive FSM transitions (`fsm_transition`)\r\n- Query the audit log (`audit_query`, `audit_tail`)\r\n- Check and top up budgets (`budget_status`, `budget_spend`)\r\n\r\n---\r\n\r\n## 5. Enterprise Concerns\r\n\r\n### Authentication & IAM\r\n\r\nNetwork-AI does **not** require or replace an external IAM system. `AuthGuardian` operates as a **pre-authorization layer**:\r\n\r\n```\r\nAI Agent → AuthGuardian (justification scoring) → your IAM (final auth) → resource\r\n```\r\n\r\nThe HMAC secret (`HMAC_SECRET` env var) should be rotated on the same schedule as your other API keys and stored in your secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).\r\n\r\n### Audit Log Retention\r\n\r\nThe audit log at `data/audit_log.jsonl` is a HMAC-signed append-only chain. Each entry contains: timestamp, agentId, eventType, resource, outcome, and a chain signature.\r\n\r\n- **GDPR / right to erasure:** Entries are immutable by design. If data subject erasure applies, store identifying data outside the log and reference only pseudonymized agent IDs inside it.\r\n- **Retention:** Rotate files using your standard log rotation tooling (logrotate, Fluentd, etc.). The chain continues across files — verification just needs the previous file's last hash.\r\n- **SIEM integration:** Stream `audit_log.jsonl` to Splunk, Datadog, or Elastic via the `audit_tail` MCP tool or a simple `tail -F` feed.\r\n\r\n### Air-Gapped / On-Prem Deployment\r\n\r\nNetwork-AI has **zero required external network calls**. All operations (blackboard, FSM, compliance, budget, tokens, audit) run entirely on-premises:\r\n\r\n- No telemetry, no call-home, no cloud dependency\r\n- LLM calls only happen if *you* add an adapter that calls an LLM — e.g. `OpenAIAssistantsAdapter` will call `api.openai.com`, but this is your explicit choice\r\n- The MCP server (`network-ai-server`) binds to localhost by default; deploy behind your internal API gateway to expose it to your agent fleet\r\n\r\n### Multi-Tenant Deployments\r\n\r\nIsolate tenants by:\r\n1. **Separate blackboard roots** — each tenant gets their own directory path passed to `LockedBlackboard(tenantPath)`\r\n2. **Separate budget pools** — prefix pool names with tenant ID: `tenant-abc:classifier`\r\n3. **Separate HMAC secrets** — one `SecureTokenManager` instance per tenant\r\n4. **Namespace scoping** — use consistent key prefixes in the blackboard (e.g. `tenant-abc:invoice:42`)\r\n\r\n### Scaling\r\n\r\nNetwork-AI is a **single-process orchestrator** by design — it does not require a broker, queue, or service mesh. For horizontal scaling:\r\n\r\n- **Shared `LockedBlackboard`:** Point multiple instances at the same directory on a shared volume (NFS, EFS, Azure Files). File-system mutexes work across processes on the same mount.\r\n- **Independent budget tracking:** Each instance tracks its own pool. Use a sidecar or the `audit_tail` MCP tool to aggregate spend across instances.\r\n- **FSM per workflow:** One `JourneyFSM` per workflow instance, not per process. FSM state persists to the blackboard, so any process can resume an interrupted journey.\r\n\r\n---\r\n\r\n## 6. Architecture Patterns\r\n\r\n### Pattern A — Sidecar (Minimal Disruption)\r\n\r\nKeep your existing agent orchestration. Add Network-AI only for coordination, safety, and audit on the shared state layer.\r\n\r\n```\r\n[Existing LangChain agent] ──writes──▶ [LockedBlackboard] ◀──reads── [Existing AutoGen agent]\r\n │\r\n [Audit log]\r\n [Budget tracking]\r\n```\r\n\r\nNo changes to your agent code. Network-AI wraps the shared resource only.\r\n\r\n---\r\n\r\n### Pattern B — Full Orchestrator\r\n\r\nNetwork-AI owns the entire agent lifecycle. All agents run through the adapter registry.\r\n\r\n```\r\nUser request\r\n │\r\n ▼\r\nSwarmOrchestrator\r\n │\r\n ├──▶ AuthGuardian (permission check)\r\n ├──▶ JourneyFSM (state gate)\r\n ├──▶ FederatedBudget (cost check)\r\n │\r\n ├──▶ LangChainAdapter ──▶ your LangChain agent\r\n ├──▶ AutoGenAdapter ──▶ your AutoGen agent\r\n └──▶ CustomAdapter ──▶ your existing functions\r\n```\r\n\r\n---\r\n\r\n### Pattern C — MCP Control Plane\r\n\r\nYour AI model connects to `network-ai-server` via SSE and drives the whole system through MCP tools — no hand-coded orchestration logic at all.\r\n\r\n```\r\nAI Model (Claude / GPT-4o)\r\n │ SSE/JSON-RPC\r\n ▼\r\nnetwork-ai-server (port 3001)\r\n │\r\n ├── ControlMcpTools (spawn agents, drive FSM, set config)\r\n ├── ExtendedMcpTools (budget, tokens, audit)\r\n └── BlackboardMCPTools (read/write blackboard)\r\n```\r\n\r\n---\r\n\r\n## 7. Validation Checklist\r\n\r\nRun these before declaring the integration production-ready:\r\n\r\n### Functional\r\n\r\n- [ ] All agents execute via the adapter registry without errors\r\n- [ ] `npx ts-node test-standalone.ts` — 79 core tests pass\r\n- [ ] `npx ts-node test-security.ts` — 33 security tests pass\r\n- [ ] `npx ts-node test-adapters.ts` — 139 adapter tests pass\r\n- [ ] `npx ts-node test-phase4.ts` — 147 behavioral tests pass\r\n- [ ] `npm run demo -- --08` runs to completion in < 10 seconds\r\n\r\n### Race Condition Safety\r\n\r\n- [ ] Two agents can write to the same blackboard key concurrently without data loss\r\n- [ ] `LockedBlackboard.validateChange()` rejects a stale change after a conflict\r\n- [ ] `priority-wins` correctly overwrites a lower-priority pending write\r\n\r\n### Budget Enforcement\r\n\r\n- [ ] Spending past the ceiling throws / returns `allowed: false`\r\n- [ ] Budget state persists across process restart\r\n- [ ] Per-agent pools are independent (overspending in pool A does not affect pool B)\r\n\r\n### Access Control\r\n\r\n- [ ] A token issued by `SecureTokenManager` validates correctly\r\n- [ ] An expired token is rejected\r\n- [ ] A token with insufficient scope is rejected at the `AuthGuardian` gate\r\n- [ ] `--active-grants` shows the correct active token set\r\n\r\n### Compliance\r\n\r\n- [ ] `ComplianceMonitor` fires `TOOL_ABUSE` after the configured action threshold\r\n- [ ] `RESPONSE_TIMEOUT` fires when an agent exceeds the timeout window\r\n- [ ] `JOURNEY_TIMEOUT` fires when the overall journey exceeds its ceiling\r\n- [ ] FSM blocks a transition attempted by an unauthorized agent\r\n\r\n### Audit\r\n\r\n- [ ] Every blackboard write produces a signed entry in `audit_log.jsonl`\r\n- [ ] `audit_query` returns filtered results correctly\r\n- [ ] The audit chain signature is intact after N entries (run the chain verifier)\r\n\r\n---\r\n\r\n## 8. Common Integration Mistakes\r\n\r\n| Mistake | Consequence | Fix |\r\n|---------|-------------|-----|\r\n| Using `SharedBlackboard` for concurrent writes | Race conditions / data loss | Use `LockedBlackboard` for any key two agents write to |\r\n| Not committing the lock file (`package-lock.json`) | CI `npm ci` fails on Node version mismatch | Always commit `package-lock.json` after version bumps |\r\n| Not including `socket.json` in `package.json` `files` | Socket.dev ignores aren't shipped; supply chain score drops | Add `socket.json` to the `files` array |\r\n| Hardcoded agent IDs in trust level config | Agent added later gets default 0.5 trust and is silently denied | Maintain a central trust registry; register new agents before deploying |\r\n| One `FederatedBudget` pool shared by all agents | One runaway agent exhausts budget for everyone | One pool per agent or per role |\r\n| FSM with no timeout | Stuck workflow holds locks indefinitely | Always set `timeoutMs` on states that involve external calls |\r\n| Storing PII as blackboard keys | Audit log contains PII in plain text | Use pseudonymised keys; store PII in a separate encrypted store |\r\n| Running `network-ai-server` on `0.0.0.0` in production | MCP control plane is publicly accessible | Bind to localhost and expose via authenticated internal API gateway only |\r\n\r\n---\r\n\r\n## Further Reading\r\n\r\n| Document | What It Covers |\r\n|----------|---------------|\r\n| [QUICKSTART.md](QUICKSTART.md) | Get running in 5 minutes |\r\n| [references/adapter-system.md](references/adapter-system.md) | All 12 adapters with code examples |\r\n| [references/trust-levels.md](references/trust-levels.md) | Trust scoring formula and agent roles |\r\n| [references/auth-guardian.md](references/auth-guardian.md) | Permission system, justification scoring, token lifecycle |\r\n| [references/blackboard-schema.md](references/blackboard-schema.md) | Blackboard key conventions and namespacing |\r\n| [references/mcp-roadmap.md](references/mcp-roadmap.md) | MCP server tools reference |\r\n| [examples/README.md](examples/README.md) | All runnable demos |\r\n| [CHANGELOG.md](CHANGELOG.md) | Full version history |\r\n\r\n---\r\n\r\n*Network-AI v4.0.6 · MIT License · https://github.com/jovanSAPFIONEER/Network-AI*\n\nFile v4.0.14:SHOW_HN.md\n\n# Show HN: Network-AI — Multi-Agent Race Condition Prevention for TypeScript\r\n\r\n**Post title:**\r\n> Show HN: Network-AI – plug-and-play orchestrator that prevents race conditions when AI agents share state\r\n\r\n---\r\n\r\n## Body\r\n\r\nI built Network-AI because I kept hitting the same problem: run two AI agents in parallel, they write to the same resource at the same time, and one of them silently overwrites the other. No error. No warning. Just wrong output.\r\n\r\nMost agent frameworks give you parallelism. None of them give you coordination safety.\r\n\r\n**The classic failure:**\r\n\r\n```\r\nAgent A reads balance: $10,000\r\nAgent B reads balance: $10,000 ← same moment\r\nAgent A writes balance: $3,000 ← deducts $7,000\r\nAgent B writes balance: $4,000 ← deducts $6,000, ignoring Agent A's write\r\n```\r\n\r\nBoth agents believed they had $10,000. Both spent from it. You now have a $3,000 error with no trace of what happened.\r\n\r\nThis is a split-brain problem, and it happens any time two LLM agents hit a shared database, file, or API concurrently. It's not theoretical — I've seen it in production pipelines.\r\n\r\n---\r\n\r\n**What Network-AI does:**\r\n\r\n- **Atomic blackboard** — `propose → validate → commit` with file-system mutex. No two agents can write to the same key simultaneously.\r\n- **Priority preemption** — if two agents conflict, the higher-priority write wins deterministically (not \"last write wins\" chaos)\r\n- **FSM governance** — agents can only act when the workflow is in the right state\r\n- **FederatedBudget** — per-agent token ceilings with hard cut-off. One runaway agent cannot exhaust your OpenAI bill.\r\n- **ComplianceMonitor** — detects TOOL_ABUSE, turn-taking violations, response timeouts, journey timeouts in real time\r\n- **12 framework adapters** — LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and a CustomAdapter for anything else\r\n\r\n---\r\n\r\n**You can see the whole thing in 2 seconds with no API key:**\r\n\r\n```bash\r\ngit clone https://github.com/jovanSAPFIONEER/Network-AI\r\ncd Network-AI\r\nnpm install\r\nnpm run demo -- --08\r\n```\r\n\r\nThis runs the control-plane stress demo: atomic commits, priority preemption, FSM timeout, and 17 live compliance violations — all in ~2 seconds, no LLM calls.\r\n\r\n---\r\n\r\n**Or the full AI showcase** (needs `OPENAI_API_KEY`):\r\n\r\n```bash\r\nnpm run demo -- --07\r\n```\r\n\r\n8-agent pipeline that builds a Payment Processing Service with FSM gating, scoped auth tokens, per-agent budget ceilings, AI quality gates, automated code fixing, and deterministic 10/10 scoring. Writes a cryptographically signed audit trail to disk on every run.\r\n\r\n---\r\n\r\n**Stack:** TypeScript, Node.js 18+. Zero required external services. Works on-prem, air-gapped, or cloud.\r\n\r\n**Repo:** https://github.com/jovanSAPFIONEER/Network-AI \r\n**npm:** `npm install network-ai` \r\n**MCP server:** `npx network-ai-server --port 3001`\r\n\r\nHappy to answer questions about the coordination model, the FSM design, or how the atomic commits work.\r\n\r\n---\r\n\r\n## Timing notes\r\n\r\n- Post on a **Tuesday or Wednesday between 9–11am ET** — peak HN traffic window\r\n- Tag: `Show HN`\r\n- Do not post the same week as a major AI framework release (it will get buried)\r\n- Have the demo commands ready to paste in the comments — someone will ask immediately\r\n\r\n## Expected comment threads to prepare for\r\n\r\n1. \"How is this different from LangGraph / LangChain?\" → answer: Network-AI is the coordination layer, not the agent logic. It works *with* LangChain (there's an adapter).\r\n2. \"Does this work with Python?\" → Python scripts are included (`scripts/`), TypeScript is the orchestration layer\r\n3. \"What's the performance overhead of the file-system mutex?\" → microseconds for local; designed for workloads where LLM latency (100ms–10s) dominates\r\n4. \"Is this production-ready?\" → MIT, 1,200+ tests, CodeQL + OpenSSF Scorecard on CI, 2,500+ weekly npm downloads at 24 days old\n\nFile v4.0.14:requirements.txt\n\n# Python dependencies for Swarm Orchestrator Skill\r\n# Install: pip install -r requirements.txt\r\n\r\n# Core dependencies (all optional - stdlib works on Unix)\r\n# filelock>=3.0.0 # Cross-platform file locking (recommended for Windows)\r\n\r\n# Note: The blackboard uses fcntl on Unix (built-in) with fallback for Windows.\r\n# For production Windows deployments, uncomment filelock above.\r\n\r\n# If you want to run type checking:\r\n# mypy>=1.0.0\r\n\r\n# If you want to run tests:\r\n# pytest>=7.0.0\n\nArchive v4.0.13: 13 files, 56286 bytes\n\nFiles: ARCHITECTURE.md (11156b), AWESOME_LISTS.md (4778b), BENCHMARKS.md (6877b), INTEGRATION_GUIDE.md (20369b), requirements.txt (483b), scripts/blackboard.py (32078b), scripts/check_permission.py (24434b), scripts/revoke_token.py (7757b), scripts/swarm_guard.py (46680b), scripts/validate_token.py (2755b), SHOW_HN.md (3993b), SKILL.md (20290b), _meta.json (130b)\n\nFile v4.0.13:SKILL.md\n\n---\r\nname: Network-AI\r\ndescription: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and enforces permission walls before sensitive operations. All execution is local and sandboxed.\r\nmetadata:\r\n openclaw:\r\n emoji: \"\\U0001F41D\"\r\n homepage: https://github.com/jovanSAPFIONEER/Network-AI\r\n requires:\r\n bins:\r\n - python3\r\n optional_bins:\r\n - node # Only needed if you separately install and run the Node.js MCP server (network-ai-server via npm). Not required for this skill's Python instructions.\r\n env:\r\n SWARM_TOKEN_SECRET:\r\n required: false\r\n description: \"HMAC secret for AuthGuardian tokens. Auto-generated per process if not set (ephemeral).\"\r\n SWARM_ENCRYPTION_KEY:\r\n required: false\r\n description: \"AES-256 key for blackboard encryption. Auto-generated per process if not set.\"\r\n OPENAI_API_KEY:\r\n required: false\r\n description: \"Only used by optional demo examples (07-full-showcase.ts) and the setup wizard. Not required for the core orchestrator or MCP server.\"\r\n privacy:\r\n audit_log:\r\n path: data/audit_log.jsonl\r\n scope: local-only\r\n description: \"Local append-only JSONL file recording operation metadata (agentId, action, timestamp, outcome). No data leaves the machine. Disable with --no-audit flag on network-ai-server, or pass auditLogPath: undefined in createSwarmOrchestrator config.\"\r\n---\r\n\r\n# Swarm Orchestrator Skill\r\n\r\n> **Scope of this skill bundle:** All instructions below run local Python scripts (`scripts/*.py`). No network calls are made by this skill. The Node.js MCP server (`network-ai-server`) is a **separate optional component** — install it with `npm install -g network-ai` only if you want MCP/IDE integration. It does **not** run automatically and is not part of this skill bundle.\r\n\r\nMulti-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.\r\n\r\n## 🎯 Orchestrator System Instructions\r\n\r\n**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:\r\n\r\n### Core Responsibilities\r\n\r\n1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks\r\n2. **DELEGATE** using the budget-aware handoff protocol\r\n3. **VERIFY** results on the blackboard before committing\r\n4. **SYNTHESIZE** final output only after all validations pass\r\n\r\n### Task Decomposition Protocol\r\n\r\nWhen you receive a complex request, decompose it into exactly **3 sub-tasks**:\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────────┐\r\n│ COMPLEX USER REQUEST │\r\n└─────────────────────────────────────────────────────────────────┘\r\n │\r\n ▼\r\n ┌─────────────────────┼─────────────────────┐\r\n │ │ │\r\n ▼ ▼ ▼\r\n┌───────────────┐ ┌───────────────┐ ┌───────────────┐\r\n│ SUB-TASK 1 │ │ SUB-TASK 2 │ │ SUB-TASK 3 │\r\n│ data_analyst │ │ risk_assessor │ │strategy_advisor│\r\n│ (DATA) │ │ (VERIFY) │ │ (RECOMMEND) │\r\n└───────────────┘ └───────────────┘ └───────────────┘\r\n │ │ │\r\n └─────────────────────┼─────────────────────┘\r\n ▼\r\n ┌───────────────┐\r\n │ SYNTHESIZE │\r\n │ orchestrator │\r\n └───────────────┘\r\n```\r\n\r\n**Decomposition Template:**\r\n```\r\nTASK DECOMPOSITION for: \"{user_request}\"\r\n\r\nSub-Task 1 (DATA): [data_analyst]\r\n - Objective: Extract/process raw data\r\n - Output: Structured JSON with metrics\r\n\r\nSub-Task 2 (VERIFY): [risk_assessor] \r\n - Objective: Validate data quality & compliance\r\n - Output: Validation report with confidence score\r\n\r\nSub-Task 3 (RECOMMEND): [strategy_advisor]\r\n - Objective: Generate actionable insights\r\n - Output: Recommendations with rationale\r\n```\r\n\r\n### Budget-Aware Handoff Protocol\r\n\r\n**CRITICAL:** Before EVERY `sessions_send`, call the handoff interceptor:\r\n\r\n```bash\r\n# ALWAYS run this BEFORE sessions_send\r\npython {baseDir}/scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 revenue data\"\r\n```\r\n\r\n**Decision Logic:**\r\n```\r\nIF result.allowed == true:\r\n → Proceed with sessions_send\r\n → Note tokens_spent and remaining_budget\r\nELSE:\r\n → STOP - Do NOT call sessions_send\r\n → Report blocked reason to user\r\n → Consider: reduce scope or abort task\r\n```\r\n\r\n### Pre-Commit Verification Workflow\r\n\r\nBefore returning final results to the user:\r\n\r\n```bash\r\n# Step 1: Check all sub-task results on blackboard\r\npython {baseDir}/scripts/blackboard.py read \"task:001:data_analyst\"\r\npython {baseDir}/scripts/blackboard.py read \"task:001:risk_assessor\"\r\npython {baseDir}/scripts/blackboard.py read \"task:001:strategy_advisor\"\r\n\r\n# Step 2: Validate each result\r\npython {baseDir}/scripts/swarm_guard.py validate-result \\\r\n --task-id \"task_001\" \\\r\n --agent data_analyst \\\r\n --result '{\"status\":\"success\",\"output\":{...},\"confidence\":0.85}'\r\n\r\n# Step 3: Supervisor review (checks all issues)\r\npython {baseDir}/scripts/swarm_guard.py supervisor-review --task-id \"task_001\"\r\n\r\n# Step 4: Only if APPROVED, commit final state\r\npython {baseDir}/scripts/blackboard.py write \"task:001:final\" \\\r\n '{\"status\":\"SUCCESS\",\"output\":{...}}'\r\n```\r\n\r\n**Verdict Handling:**\r\n| Verdict | Action |\r\n|---------|--------|\r\n| `APPROVED` | Commit and return results to user |\r\n| `WARNING` | Review issues, fix if possible, then commit |\r\n| `BLOCKED` | Do NOT return results. Report failure. |\r\n\r\n---\r\n\r\n## When to Use This Skill\r\n\r\n- **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)\r\n- **Parallel Execution**: Run multiple agents simultaneously and synthesize results\r\n- **Permission Wall**: Gate access to DATABASE, PAYMENTS, EMAIL, or FILE_EXPORT operations (abstract local resource types — no external credentials required)\r\n- **Shared Blackboard**: Coordinate agent state via persistent markdown file\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize Budget (FIRST!)\r\n\r\n**Always initialize a budget before any multi-agent task:**\r\n\r\n```bash\r\npython {baseDir}/scripts/swarm_guard.py budget-init \\\r\n --task-id \"task_001\" \\\r\n --budget 10000 \\\r\n --description \"Q4 Financial Analysis\"\r\n```\r\n\r\n### 2. Delegate a Task to Another Session\r\n\r\nUse OpenClaw's built-in session tools to delegate work:\r\n\r\n```\r\nsessions_list # See available sessions/agents\r\nsessions_send # Send task to another session\r\nsessions_history # Check results from delegated work\r\n```\r\n\r\n**Example delegation prompt:**\r\n```\r\nUse sessions_send to ask the data_analyst session to:\r\n\"Analyze Q4 revenue trends from the SAP export data and summarize key insights\"\r\n```\r\n\r\n### 3. Check Permission Before API Access\r\n\r\nBefore accessing SAP or Financial APIs, evaluate the request:\r\n\r\n```bash\r\n# Run the permission checker script\r\npython {baseDir}/scripts/check_permission.py \\\r\n --agent \"data_analyst\" \\\r\n --resource \"DATABASE\" \\\r\n --justification \"Need Q4 invoice data for quarterly report\" \\\r\n --scope \"read:invoices\"\r\n```\r\n\r\nThe script will output a grant token if approved, or denial reason if rejected.\r\n\r\n### 4. Use the Shared Blackboard\r\n\r\nRead/write coordination state:\r\n\r\n```bash\r\n# Write to blackboard\r\npython {baseDir}/scripts/blackboard.py write \"task:q4_analysis\" '{\"status\": \"in_progress\", \"agent\": \"data_analyst\"}'\r\n\r\n# Read from blackboard \r\npython {baseDir}/scripts/blackboard.py read \"task:q4_analysis\"\r\n\r\n# List all entries\r\npython {baseDir}/scripts/blackboard.py list\r\n```\r\n\r\n## Agent-to-Agent Handoff Protocol\r\n\r\nWhen delegating tasks between agents/sessions:\r\n\r\n### Step 1: Initialize Budget & Check Capacity\r\n```bash\r\n# Initialize budget (if not already done)\r\npython {baseDir}/scripts/swarm_guard.py budget-init --task-id \"task_001\" --budget 10000\r\n\r\n# Check current status\r\npython {baseDir}/scripts/swarm_guard.py budget-check --task-id \"task_001\"\r\n```\r\n\r\n### Step 2: Identify Target Agent\r\n```\r\nsessions_list # Find available agents\r\n```\r\n\r\nCommon agent types:\r\n| Agent | Specialty |\r\n|-------|-----------|\r\n| `data_analyst` | Data processing, SQL, analytics |\r\n| `strategy_advisor` | Business strategy, recommendations |\r\n| `risk_assessor` | Risk analysis, compliance checks |\r\n| `orchestrator` | Coordination, task decomposition |\r\n\r\n### Step 3: Intercept Before Handoff (REQUIRED)\r\n\r\n```bash\r\n# This checks budget AND handoff limits before allowing the call\r\npython {baseDir}/scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 data\" \\\r\n --artifact # Include if expecting output\r\n```\r\n\r\n**If ALLOWED:** Proceed to Step 4\r\n**If BLOCKED:** Stop - do not call sessions_send\r\n\r\n### Step 4: Construct Handoff Message\r\n\r\nInclude these fields in your delegation:\r\n- **instruction**: Clear task description\r\n- **context**: Relevant background information\r\n- **constraints**: Any limitations or requirements\r\n- **expectedOutput**: What format/content you need back\r\n\r\n### Step 5: Send via sessions_send\r\n\r\n```\r\nsessions_send to data_analyst:\r\n\"[HANDOFF]\r\nInstruction: Analyze Q4 revenue by product category\r\nContext: Using SAP export from ./data/q4_export.csv\r\nConstraints: Focus on top 5 categories only\r\nExpected Output: JSON summary with category, revenue, growth_pct\r\n[/HANDOFF]\"\r\n```\r\n\r\n### Step 4: Check Results\r\n\r\n```\r\nsessions_history data_analyst # Get the response\r\n```\r\n\r\n## Permission Wall (AuthGuardian)\r\n\r\n**CRITICAL**: Always check permissions before accessing:\r\n- `DATABASE` - Internal database / data store access\r\n- `PAYMENTS` - Financial/payment data services\r\n- `EMAIL` - Email sending capability\r\n- `FILE_EXPORT` - Exporting data to local files\r\n\r\n> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all permission evaluation runs locally.\r\n\r\n### Permission Evaluation Criteria\r\n\r\n| Factor | Weight | Criteria |\r\n|--------|--------|----------|\r\n| Justification | 40% | Must explain specific task need |\r\n| Trust Level | 30% | Agent's established trust score |\r\n| Risk Assessment | 30% | Resource sensitivity + scope breadth |\r\n\r\n### Using the Permission Script\r\n\r\n```bash\r\n# Request permission\r\npython {baseDir}/scripts/check_permission.py \\\r\n --agent \"your_agent_id\" \\\r\n --resource \"PAYMENTS\" \\\r\n --justification \"Generating quarterly financial summary for board presentation\" \\\r\n --scope \"read:revenue,read:expenses\"\r\n\r\n# Output if approved:\r\n# ✅ GRANTED\r\n# Token: grant_a1b2c3d4e5f6\r\n# Expires: 2026-02-04T15:30:00Z\r\n# Restrictions: read_only, no_pii_fields, audit_required\r\n\r\n# Output if denied:\r\n# ❌ DENIED\r\n# Reason: Justification is insufficient. Please provide specific task context.\r\n```\r\n\r\n### Restriction Types\r\n\r\n| Resource | Default Restrictions |\r\n|----------|---------------------|\r\n| DATABASE | `read_only`, `max_records:100` |\r\n| PAYMENTS | `read_only`, `no_pii_fields`, `audit_required` |\r\n| EMAIL | `rate_limit:10_per_minute` |\r\n| FILE_EXPORT | `anonymize_pii`, `local_only` |\r\n\r\n## Shared Blackboard Pattern\r\n\r\nThe blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:\r\n\r\n```markdown\r\n# Swarm Blackboard\r\nLast Updated: 2026-02-04T10:30:00Z\r\n\r\n## Knowledge Cache\r\n### task:q4_analysis\r\n{\"status\": \"completed\", \"result\": {...}, \"agent\": \"data_analyst\"}\r\n\r\n### cache:revenue_summary \r\n{\"q4_total\": 1250000, \"growth\": 0.15}\r\n```\r\n\r\n### Blackboard Operations\r\n\r\n```bash\r\n# Write with TTL (expires after 1 hour)\r\npython {baseDir}/scripts/blackboard.py write \"cache:temp_data\" '{\"value\": 123}' --ttl 3600\r\n\r\n# Read (returns null if expired)\r\npython {baseDir}/scripts/blackboard.py read \"cache:temp_data\"\r\n\r\n# Delete\r\npython {baseDir}/scripts/blackboard.py delete \"cache:temp_data\"\r\n\r\n# Get full snapshot\r\npython {baseDir}/scripts/blackboard.py snapshot\r\n```\r\n\r\n## Parallel Execution\r\n\r\nFor tasks requiring multiple agent perspectives:\r\n\r\n### Strategy 1: Merge (Default)\r\nCombine all agent outputs into unified result.\r\n```\r\nAsk data_analyst AND strategy_advisor to both analyze the dataset.\r\nMerge their insights into a comprehensive report.\r\n```\r\n\r\n### Strategy 2: Vote\r\nUse when you need consensus - pick the result with highest confidence.\r\n\r\n### Strategy 3: First-Success\r\nUse for redundancy - take first successful result.\r\n\r\n### Strategy 4: Chain\r\nSequential processing - output of one feeds into next.\r\n\r\n### Example Parallel Workflow\r\n\r\n```\r\n1. sessions_send to data_analyst: \"Extract key metrics from Q4 data\"\r\n2. sessions_send to risk_assessor: \"Identify compliance risks in Q4 data\" \r\n3. sessions_send to strategy_advisor: \"Recommend actions based on Q4 trends\"\r\n4. Wait for all responses via sessions_history\r\n5. Synthesize: Combine metrics + risks + recommendations into executive summary\r\n```\r\n\r\n## Security Considerations\r\n\r\n1. **Never bypass the permission wall** for gated resources\r\n2. **Always include justification** explaining the business need\r\n3. **Use minimal scope** - request only what you need\r\n4. **Check token expiry** - tokens are valid for 5 minutes\r\n5. **Validate tokens** - use `python {baseDir}/scripts/validate_token.py TOKEN` to verify grant tokens before use\r\n6. **Audit trail** - all permission requests are logged\r\n\r\n## 📝 Audit Trail Requirements (MANDATORY)\r\n\r\n**Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.\r\n\r\n### What Gets Logged Automatically\r\n\r\nThe scripts automatically log these events:\r\n- `permission_granted` - When access is approved\r\n- `permission_denied` - When access is rejected\r\n- `permission_revoked` - When a token is manually revoked\r\n- `ttl_cleanup` - When expired tokens are purged\r\n- `result_validated` / `result_rejected` - Swarm Guard validations\r\n\r\n### Log Entry Format\r\n\r\n```json\r\n{\r\n \"timestamp\": \"2026-02-04T10:30:00+00:00\",\r\n \"action\": \"permission_granted\",\r\n \"details\": {\r\n \"agent_id\": \"data_analyst\",\r\n \"resource_type\": \"DATABASE\",\r\n \"justification\": \"Q4 revenue analysis\",\r\n \"token\": \"grant_abc123...\",\r\n \"restrictions\": [\"read_only\", \"max_records:100\"]\r\n }\r\n}\r\n```\r\n\r\n### Reading the Audit Log\r\n\r\n```bash\r\n# View recent entries (last 10)\r\ntail -10 {baseDir}/data/audit_log.jsonl\r\n\r\n# Search for specific agent\r\ngrep \"data_analyst\" {baseDir}/data/audit_log.jsonl\r\n\r\n# Count actions by type\r\ncat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c\r\n```\r\n\r\n### Custom Audit Entries\r\n\r\nIf you perform a sensitive action manually, log it:\r\n\r\n```python\r\nimport json\r\nfrom datetime import datetime, timezone\r\nfrom pathlib import Path\r\n\r\naudit_file = Path(\"{baseDir}/data/audit_log.jsonl\")\r\nentry = {\r\n \"timestamp\": datetime.now(timezone.utc).isoformat(),\r\n \"action\": \"manual_data_access\",\r\n \"details\": {\r\n \"agent\": \"orchestrator\",\r\n \"description\": \"Direct database query for debugging\",\r\n \"justification\": \"Investigating data sync issue #1234\"\r\n }\r\n}\r\nwith open(audit_file, \"a\") as f:\r\n f.write(json.dumps(entry) + \"\\n\")\r\n```\r\n\r\n## 🧹 TTL Enforcement (Token Lifecycle)\r\n\r\nExpired permission tokens are automatically tracked. Run periodic cleanup:\r\n\r\n```bash\r\n# Validate a grant token\r\npython {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6\r\n\r\n# List expired tokens (without removing)\r\npython {baseDir}/scripts/revoke_token.py --list-expired\r\n\r\n# Remove all expired tokens\r\npython {baseDir}/scripts/revoke_token.py --cleanup\r\n\r\n# Output:\r\n# 🧹 TTL Cleanup Complete\r\n# Removed: 3 expired token(s)\r\n# Remaining active grants: 2\r\n```\r\n\r\n**Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.\r\n\r\n## ⚠️ Swarm Guard: Preventing Common Failures\r\n\r\nTwo critical issues can derail multi-agent swarms:\r\n\r\n### 1. The Handoff Tax 💸\r\n\r\n**Problem**: Agents waste tokens \"talking about\" work instead of doing it.\r\n\r\n**Prevention**:\r\n```bash\r\n# Before each handoff, check your budget:\r\npython {baseDir}/scripts/swarm_guard.py check-handoff --task-id \"task_001\"\r\n\r\n# Output:\r\n# 🟢 Task: task_001\r\n# Handoffs: 1/3\r\n# Remaining: 2\r\n# Action Ratio: 100%\r\n```\r\n\r\n**Rules enforced**:\r\n- **Max 3 handoffs per task** - After 3, produce output or abort\r\n- **Max 500 chars per message** - Be concise: instruction + constraints + expected output\r\n- **60% action ratio** - At least 60% of handoffs must produce artifacts\r\n- **2-minute planning limit** - No output after 2min = timeout\r\n\r\n```bash\r\n# Record a handoff (with tax checking):\r\npython {baseDir}/scripts/swarm_guard.py record-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze sales data, output JSON summary\" \\\r\n --artifact # Include if this handoff produces output\r\n```\r\n\r\n### 2. Silent Failure Detection 👻\r\n\r\n**Problem**: One agent fails silently, others keep working on bad data.\r\n\r\n**Prevention - Heartbeats**:\r\n```bash\r\n# Agents must send heartbeats while working:\r\npython {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id \"task_001\"\r\n\r\n# Check if an agent is healthy:\r\npython {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst\r\n\r\n# Output if healthy:\r\n# 💚 Agent 'data_analyst' is HEALTHY\r\n# Last seen: 15s ago\r\n\r\n# Output if failed:\r\n# 💔 Agent 'data_analyst' is UNHEALTHY\r\n# Reason: STALE_HEARTBEAT\r\n# → Do NOT use any pending results from this agent.\r\n```\r\n\r\n**Prevention - Result Validation**:\r\n```bash\r\n# Before using another agent's result, validate it:\r\npython {baseDir}/scripts/swarm_guard.py validate-result \\\r\n --task-id \"task_001\" \\\r\n --agent data_analyst \\\r\n --result '{\"status\": \"success\", \"output\": {\"revenue\": 125000}, \"confidence\": 0.85}'\r\n\r\n# Output:\r\n# ✅ RESULT VALID\r\n# → APPROVED - Result can be used by other agents\r\n```\r\n\r\n**Required result fields**: `status`, `output`, `confidence`\r\n\r\n### Supervisor Review\r\n\r\nBefore finalizing any task, run supervisor review:\r\n```bash\r\npython {baseDir}/scripts/swarm_guard.py supervisor-review --task-id \"task_001\"\r\n\r\n# Output:\r\n# ✅ SUPERVISOR VERDICT: APPROVED\r\n# Task: task_001\r\n# Age: 1.5 minutes\r\n# Handoffs: 2\r\n# Artifacts: 2\r\n```\r\n\r\n**Verdicts**:\r\n- `APPROVED` - Task healthy, results usable\r\n- `WARNING` - Issues detected, review recommended\r\n- `BLOCKED` - Critical failures, do NOT use results\r\n\r\n## Troubleshooting\r\n\r\n### Permission Denied\r\n- Provide more specific justification (mention task, purpose, expected outcome)\r\n- Narrow the requested scope\r\n- Check agent trust level\r\n\r\n### Blackboard Read Returns Null\r\n- Entry may have expired (check TTL)\r\n- Key may be misspelled\r\n- Entry was never written\r\n\r\n### Session Not Found\r\n- Run `sessions_list` to see available sessions\r\n- Session may need to be started first\r\n\r\n## References\r\n\r\n- [AuthGuardian Details](references/auth-guardian.md) - Full permission system documentation\r\n- [Blackboard Schema](references/blackboard-schema.md) - Data structure specifications\r\n- [Agent Trust Levels](references/trust-levels.md) - How trust is calculated\n\nFile v4.0.13:_meta.json\n\n{\n \"ownerId\": \"kn75j1xcebk74re38bv714kh1h81804p\",\n \"slug\": \"network-ai\",\n \"version\": \"4.0.13\",\n \"publishedAt\": 1772304515783\n}\n\nFile v4.0.13:ARCHITECTURE.md\n\n# Architecture\r\n\r\n## The Multi-Agent Race Condition Problem\r\n\r\nMost agent frameworks let you run multiple AI agents in parallel. None of them protect you when those agents write to the same resource at the same time.\r\n\r\n**The \"Bank Run\" scenario:**\r\n\r\n```\r\nAgent A reads balance: $10,000\r\nAgent B reads balance: $10,000 (same moment)\r\nAgent A writes balance: $10,000 - $7,000 = $3,000\r\nAgent B writes balance: $10,000 - $6,000 = $4,000 ← Agent A's write is gone\r\n```\r\n\r\nBoth agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.\r\n\r\nWithout concurrency control, parallel agents will:\r\n- **Corrupt shared state** — two agents overwrite each other's blackboard entries\r\n- **Double-spend budgets** — token costs exceed limits because agents don't see each other's spending\r\n- **Produce contradictory outputs** — Agent A says \"approved\", Agent B says \"denied\", both write to the same key\r\n\r\n**How Network-AI prevents this:**\r\n\r\n```typescript\r\n// Atomic commit — no other agent can read/write \"account:balance\" during this operation\r\nconst changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');\r\nblackboard.validateChange(changeId); // checks for conflicts\r\nblackboard.commitChange(changeId); // atomic write with file-system mutex\r\n```\r\n\r\n---\r\n\r\n## Component Overview\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────┐\r\n│ Your Application │\r\n└──────────────────────────┬──────────────────────────────────┘\r\n │ createSwarmOrchestrator()\r\n┌──────────────────────────▼──────────────────────────────────┐\r\n│ SwarmOrchestrator │\r\n│ │\r\n│ ┌──────────────┐ ┌───────────────┐ ┌─────────────────┐ │\r\n│ │ AdapterRegistry│ │ AuthGuardian │ │ FederatedBudget │ │\r\n│ │ (route tasks) │ │ (permissions) │ │ (token ceilings)│ │\r\n│ └──────┬───────┘ └───────────────┘ └─────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼──────────────────────────────────────────────┐ │\r\n│ │ LockedBlackboard (shared state) │ │\r\n│ │ propose → validate → commit (file-system mutex) │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼───────────────────────────────────────────────┐ │\r\n│ │ Adapters (plug any framework in, swap out freely) │ │\r\n│ │ LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │… │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n└─────────────────────────────────────────────────────────────┘\r\n │\r\n HMAC-signed audit log (data/audit_log.jsonl)\r\n```\r\n\r\n### LockedBlackboard\r\n\r\nThe coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss.\r\n\r\n- `propose(key, value, agentId, ttl?, priority?)` — stages a change, detects conflicts\r\n- `validate(changeId, validatorId)` — confirms no race occurred since propose\r\n- `commit(changeId)` — atomic write\r\n- Conflict strategies: `first-commit-wins`, `priority-wins`, `last-write-wins`\r\n\r\n### AuthGuardian\r\n\r\nPermission gating before sensitive operations. Agents must request a token with a business justification — the guardian evaluates trust level, resource risk, and justification quality before granting.\r\n\r\n```typescript\r\nconst grant = auth.requestPermission('data_analyst', 'DATABASE', 'read',\r\n 'Need customer order history for sales report');\r\n// grant.token is scoped HMAC-signed token with TTL\r\n```\r\n\r\nResource types: `DATABASE` (risk 0.5), `PAYMENTS` (0.7), `EMAIL` (0.4), `FILE_EXPORT` (0.6)\r\n\r\nPermission scoring: justification quality 40%, agent trust level 30%, resource risk 30%. Threshold: 0.5.\r\n\r\n### FederatedBudget\r\n\r\nHard token ceilings per agent and per task. Even if 5 agents run in parallel, total spend cannot exceed the budget.\r\n\r\n```bash\r\npython scripts/swarm_guard.py budget-init --task-id \"task_001\" --budget 10000\r\npython scripts/swarm_guard.py budget-check --task-id \"task_001\"\r\npython scripts/swarm_guard.py budget-report --task-id \"task_001\"\r\n```\r\n\r\n### AdapterRegistry\r\n\r\nRoutes tasks to the right agent/framework automatically. Register multiple adapters and the registry dispatches by agent ID.\r\n\r\n```typescript\r\nconst registry = new AdapterRegistry();\r\nregistry.register('my-langchain-agent', langchainAdapter);\r\nregistry.register('my-autogen-agent', autogenAdapter);\r\n```\r\n\r\n---\r\n\r\n## FSM Journey (JourneyFSM)\r\n\r\nThe FSM governs agent phase transitions for long-running pipelines. Each phase transition is:\r\n- Gated by AuthGuardian tokens\r\n- Logged to the audit trail\r\n- Subject to timeout enforcement\r\n\r\n```\r\nIDLE → PLANNING → EXECUTING → REVIEWING → COMMITTING → COMPLETE\r\n ↓\r\n BLOCKED (on violation)\r\n```\r\n\r\nComplianceMonitor captures violations in real-time:\r\n- `TOOL_ABUSE` — too many rapid writes\r\n- `TURN_TAKING` — consecutive actions without yield\r\n- `RESPONSE_TIMEOUT` — agent exceeds time budget\r\n- `JOURNEY_TIMEOUT` — overall pipeline exceeds wall-clock limit\r\n\r\n---\r\n\r\n## Handoff Protocol\r\n\r\nFormat messages for delegation between agents:\r\n\r\n```\r\n[HANDOFF]\r\nInstruction: Analyze monthly sales by product category\r\nContext: Using database export from ./data/sales_export.csv\r\nConstraints: Focus on top 5 categories only\r\nExpected Output: JSON summary with category, revenue, growth_pct\r\n[/HANDOFF]\r\n```\r\n\r\nBudget-aware handoff (wraps `sessions_send` with budget checks):\r\n\r\n```bash\r\npython scripts/swarm_guard.py intercept-handoff \\\r\n --task-id \"task_001\" \\\r\n --from orchestrator \\\r\n --to data_analyst \\\r\n --message \"Analyze Q4 revenue data\"\r\n```\r\n\r\nOutput:\r\n```\r\nHANDOFF ALLOWED: orchestrator -> data_analyst\r\n Tokens spent: 156\r\n Budget remaining: 9,844\r\n Handoff #1 (remaining: 2)\r\n -> Proceed with sessions_send\r\n```\r\n\r\n---\r\n\r\n## Content Quality Gate\r\n\r\nTwo-layer validation before blackboard writes:\r\n\r\n**Layer 1 — BlackboardValidator (rule-based, zero LLM calls)**\r\n- Hallucination detection (vague, unsupported, fabricated content)\r\n- Dangerous code detection (`eval()`, `exec()`, `rm -rf`)\r\n- Placeholder rejection (TODO/FIXME/stub content)\r\n- Throughput: ~500,000 ops/sec on 1 KB inputs\r\n\r\n**Layer 2 — QualityGateAgent (AI-assisted)**\r\n- Async, intended for high-value writes only\r\n- Quarantine system for suspicious content\r\n- Adds LLM latency — use selectively\r\n\r\n---\r\n\r\n## Agent Trust Levels\r\n\r\n| Agent | Trust | Role |\r\n|---|---|---|\r\n| `orchestrator` | 0.9 | Primary coordinator |\r\n| `risk_assessor` | 0.85 | Compliance specialist |\r\n| `data_analyst` | 0.8 | Data processing |\r\n| `strategy_advisor` | 0.7 | Business strategy |\r\n| Unknown | 0.5 | Default |\r\n\r\nConfigure in `scripts/check_permission.py`:\r\n\r\n```python\r\nDEFAULT_TRUST_LEVELS = {\r\n \"orchestrator\": 0.9,\r\n \"my_new_agent\": 0.75,\r\n}\r\nGRANT_TOKEN_TTL_MINUTES = 5\r\n```\r\n\r\n---\r\n\r\n## Project Structure\r\n\r\n```\r\nNetwork-AI/\r\n├── index.ts # Core orchestrator (SwarmOrchestrator, AuthGuardian, TaskDecomposer)\r\n├── security.ts # Security module (tokens, encryption, rate limiting, audit)\r\n├── setup.ts # Developer setup & installation checker\r\n├── adapters/ # 12 plug-and-play agent framework adapters\r\n│ ├── adapter-registry.ts # Multi-adapter routing & discovery\r\n│ ├── base-adapter.ts # Abstract base class\r\n│ ├── custom-adapter.ts # Custom function/HTTP agent adapter\r\n│ ├── langchain-adapter.ts\r\n│ ├── autogen-adapter.ts\r\n│ ├── crewai-adapter.ts\r\n│ ├── mcp-adapter.ts\r\n│ ├── llamaindex-adapter.ts\r\n│ ├── semantic-kernel-adapter.ts\r\n│ ├── openai-assistants-adapter.ts\r\n│ ├── haystack-adapter.ts\r\n│ ├── dspy-adapter.ts\r\n│ ├── agno-adapter.ts\r\n│ └── openclaw-adapter.ts\r\n├── lib/\r\n│ ├── locked-blackboard.ts # Atomic commits with file-system mutexes\r\n│ ├── blackboard-validator.ts # Content quality gate (Layer 1 + Layer 2)\r\n│ ├── fsm-journey.ts # FSM state machine and compliance monitor\r\n│ └── swarm-utils.ts # Helper utilities\r\n├── scripts/ # Python helper scripts (local orchestration only)\r\n│ ├── blackboard.py # Shared state management with atomic commits\r\n│ ├── swarm_guard.py # Handoff tax prevention, budget tracking\r\n│ ├── check_permission.py # AuthGuardian permission checker + active grants\r\n│ ├── validate_token.py # Token validation\r\n│ └── revoke_token.py # Token revocation + TTL cleanup\r\n├── types/\r\n│ ├── agent-adapter.d.ts # Universal adapter interfaces\r\n│ └── openclaw-core.d.ts # OpenClaw type stubs\r\n├── references/ # Deep-dive documentation\r\n│ ├── adapter-system.md\r\n│ ├── auth-guardian.md\r\n│ ├── blackboard-schema.md\r\n│ ├── trust-levels.md\r\n│ └── mcp-roadmap.md\r\n├── examples/ # Runnable examples (01–06)\r\n│ ├── 01-hello-swarm.ts\r\n│ ├── 02-fsm-pipeline.ts\r\n│ ├── 03-parallel-agents.ts\r\n│ ├── 04-live-swarm.ts\r\n│ └── 05-code-review-swarm.ts\r\n└── data/\r\n ├── audit_log.jsonl # HMAC-signed audit trail (local only)\r\n └── pending_changes/ # In-flight atomic change records\r\n```\n\nFile v4.0.13:AWESOME_LISTS.md\n\n# Awesome List PR Submissions\r\n\r\nReady-to-use PR titles, one-liners, and context for each list.\r\nSubmit these as pull requests to the respective repositories.\r\n\r\n---\r\n\r\n## 1. awesome-mcp-servers\r\n**Repo:** https://github.com/punkpeye/awesome-mcp-servers\r\n\r\n**PR title:**\r\n> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration MCP server. 20+ MCP tools: blackboard read/write, agent spawn/stop, FSM transitions, budget tracking, token management, audit log query. `npx network-ai-server --port 3001`. TypeScript/Node.js.\r\n```\r\n\r\n**Where to add it:** Under the orchestration or multi-agent section.\r\n\r\n**PR body:**\r\n> network-ai ships a production-ready MCP server (`network-ai-server` binary) that exposes the full orchestration control plane over HTTP/SSE + JSON-RPC 2.0. It includes 20+ tools across 4 groups: blackboard coordination (read/write/lock), agent control (spawn/stop/list), FSM governance (transition/state), and observability (budget status, audit trail, token lifecycle). Zero config — `npx network-ai-server` starts immediately.\r\n\r\n---\r\n\r\n## 2. awesome-ai-agents\r\n**Repo:** https://github.com/e2b-dev/awesome-ai-agents\r\n\r\n**PR title:**\r\n> Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Plug-and-play multi-agent orchestration for TypeScript/Node.js. Connects 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, MCP, and more) with atomic shared state, FSM governance, per-agent budget enforcement, and cryptographic audit trails. Solves race conditions and split-brain writes in concurrent agent systems.\r\n```\r\n\r\n**PR body:**\r\n> network-ai fills a gap that most agent frameworks leave open: safe coordination when agents share state. It wraps any agent framework via adapters (12 supported) and adds atomic blackboard writes, FSM state gating, per-agent token budget ceilings, and a ComplianceMonitor for behavioral governance. MIT licensed, 1,200+ tests, CodeQL + OpenSSF Scorecard.\r\n\r\n---\r\n\r\n## 3. awesome-langchain\r\n**Repo:** https://github.com/kyrolabs/awesome-langchain\r\n\r\n**PR title:**\r\n> Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration framework with a first-class LangChain adapter. Wraps LangChain Runnables, chains, and agents with atomic shared state, permission gating, budget enforcement, and FSM governance. Prevents race conditions when multiple LangChain agents write to shared resources concurrently.\r\n```\r\n\r\n**Where to add it:** Under Tools / Agent frameworks / Orchestration.\r\n\r\n---\r\n\r\n## 4. awesome-llamaindex\r\n**Repo:** https://github.com/emptycrown/awesome-llamaindex (or the official one)\r\n\r\n**PR title:**\r\n> Add network-ai — orchestration layer with LlamaIndex adapter\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Orchestration framework with a LlamaIndex adapter supporting query engines, chat engines, and agent runners. Adds atomic shared state, FSM governance, and per-agent budget ceilings to LlamaIndex-based pipelines.\r\n```\r\n\r\n---\r\n\r\n## 5. awesome-mcp (or MCP-related lists)\r\n**Search:** github.com/topics/model-context-protocol\r\n\r\n**PR title:**\r\n> Add network-ai — MCP server + client transport for multi-agent orchestration\r\n\r\n**One-liner:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - MCP server (`network-ai-server`) and transport (`McpSseTransport`) for multi-agent orchestration. Exposes blackboard, FSM, budget, token, and audit tools over SSE/JSON-RPC 2.0. Also includes an MCP adapter so MCP tool handlers can be registered as governed agents.\r\n```\r\n\r\n---\r\n\r\n## Submission checklist\r\n\r\nBefore each PR:\r\n- [ ] Fork the target repo\r\n- [ ] Add the one-liner in alphabetical order by tool name within its section\r\n- [ ] PR title follows the repo's existing convention (check other recent PRs)\r\n- [ ] Verify the repo's README or CONTRIBUTING.md for any format requirements\r\n- [ ] Star the repo before submitting (improves PR acceptance rate)\r\n\r\n## Other lists to check\r\n\r\n- https://github.com/jim-schwoebel/awesome-ai-frameworks\r\n- https://github.com/AgentOps-AI/agentops (list of frameworks)\r\n- https://github.com/topics/ai-agents (GitHub topic — add `ai-agents` to repo if not there)\r\n- Product Hunt — \"AI Developer Tools\" category launch\n\nFile v4.0.13:BENCHMARKS.md\n\n# Benchmarks & Performance\r\n\r\n> Performance data for Network-AI deployments. Your swarm is only as fast as the backend it calls — this page helps you choose the right setup.\r\n\r\n## BlackboardValidator Throughput\r\n\r\nLayer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:\r\n\r\n| Input size | Ops/sec | Latency |\r\n|---|---|---|\r\n| Small entry (~100 chars) | ~1,000,000 | < 1 µs |\r\n| Medium entry (~1 KB) | ~500,000 | ~2 µs |\r\n| Large entry (~10 KB) | ~159,000 | ~6 µs |\r\n\r\nLayer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.\r\n\r\n---\r\n\r\n## Cloud Provider Performance\r\n\r\nNot all cloud APIs perform the same. Model size, inference infrastructure, and tier all affect how fast each agent gets a response — and that directly multiplies across every agent in your swarm.\r\n\r\n| Provider / Model | Avg response (5-agent swarm) | RPM limit (free/tier-1) | Notes |\r\n|---|---|---|---|\r\n| **OpenAI gpt-5.2** | 6–10s per call | 3–6 RPM | Flagship model, high latency, strict RPM |\r\n| **OpenAI gpt-4o-mini** | 2–4s per call | 500 RPM | Fast, cheap, good for reviewer agents |\r\n| **OpenAI gpt-4o** | 4–7s per call | 60–500 RPM | Balanced quality/speed |\r\n| **Anthropic Claude 3.5 Haiku** | 2–3s per call | 50 RPM | Fastest Claude, great for parallel agents |\r\n| **Anthropic Claude 3.7 Sonnet** | 4–8s per call | 50 RPM | Stronger reasoning, higher latency |\r\n| **Google Gemini 2.0 Flash** | 1–3s per call | 15 RPM (free) | Very fast inference, low RPM on free tier |\r\n| **Groq (Llama 3.3 70B)** | 0.5–2s per call | 30 RPM | Fastest cloud inference available |\r\n| **Together AI / Fireworks** | 1–3s per call | Varies by plan | Good for parallel workloads |\r\n\r\n**Key insight:** A 5-agent swarm using `gpt-4o-mini` at 500 RPM can fire all 5 agents truly in parallel and finish in ~4s total. The same swarm on `gpt-5.2` at 6 RPM must go sequential and takes 60s. **The model tier matters more than the orchestration framework.**\r\n\r\n### Choosing a Model for Swarm Agents\r\n\r\n- **Speed over depth** (many agents, real-time) → `gpt-4o-mini`, `claude-3.5-haiku`, `gemini-2.0-flash`, `groq/llama-3.3-70b`\r\n- **Depth over speed** (few agents, high-stakes) → `gpt-4o`, `claude-3.7-sonnet`\r\n- **Free / no-cost testing** → Groq free tier, Gemini free tier, or Ollama locally\r\n- **Production with budget** → multiple keys across providers, route agents to different models\r\n\r\n---\r\n\r\n## Rate Limit Patterns\r\n\r\nWhen you run a 5-agent swarm sharing one API key and hit the RPM ceiling, the API silently returns empty responses — not a 429 error, just blank content. Network-AI's swarm demos handle this automatically with **sequential dispatch** and **adaptive header-based pacing** (reads `x-ratelimit-reset-requests` to wait exactly as long as needed).\r\n\r\n| You have | What to expect |\r\n|---|---|\r\n| One cloud API key | Sequential dispatch, 40–70s per 5-agent swarm — handled automatically |\r\n| Multiple cloud keys | Near-parallel, 10–15s — one key per adapter instance |\r\n| Local GPU (Ollama, vLLM) | True parallel, 5–20s depending on hardware |\r\n| Home GPU + cloud mix | Local agents never block — cloud agents rate-paced independently |\r\n\r\n### Multiple Keys = True Parallel\r\n\r\n```typescript\r\nimport { CustomAdapter, AdapterRegistry } from 'network-ai';\r\n\r\nconst registry = new AdapterRegistry();\r\n\r\nfor (const reviewer of REVIEWERS) {\r\n const adapter = new CustomAdapter();\r\n const client = new OpenAI({ apiKey: process.env[`OPENAI_KEY_${reviewer.id.toUpperCase()}`] });\r\n\r\n adapter.registerHandler(reviewer.id, async (payload) => {\r\n const resp = await client.chat.completions.create({ /* ... */ });\r\n return { findings: extractContent(resp) };\r\n });\r\n\r\n registry.register(reviewer.id, adapter);\r\n}\r\n\r\n// All 5 dispatch in parallel via Promise.all — ~8–12s instead of ~60s\r\n```\r\n\r\n### Local GPU = Zero Rate Limits\r\n\r\n```typescript\r\nconst localClient = new OpenAI({\r\n apiKey : 'not-needed',\r\n baseURL: 'http://localhost:11434/v1', // Ollama, vLLM, llama.cpp\r\n});\r\n\r\nadapter.registerHandler('reviewer', async (payload) => {\r\n const resp = await localClient.chat.completions.create({\r\n model : 'llama3.2',\r\n messages: [/* ... */],\r\n });\r\n return { findings: extractContent(resp) };\r\n});\r\n```\r\n\r\n---\r\n\r\n## Cloud GPU Instances (Self-Hosted)\r\n\r\nRunning your own model on AWS / GCP / Azure sits between managed APIs and local hardware:\r\n\r\n| Setup | Speed vs managed API | RPM |\r\n|---|---|---|\r\n| A100 (80GB) + vLLM, Llama 3.3 70B | Faster — 0.5–2s/call | None |\r\n| H100 + vLLM, Mixtral 8x7B | Faster — 0.3–1s/call | None |\r\n| T4 / V100 + Ollama, Llama 3.2 8B | Comparable | None |\r\n\r\nCost: $1–5/hr for GPU VMs. For high-volume production swarms or teams that want no external API dependency, it is the fastest architecture available. The connection is identical to local Ollama — just point `baseURL` at your VM's IP.\r\n\r\n---\r\n\r\n## `max_completion_tokens` — The Silent Truncation Trap\r\n\r\nOne of the most common failure modes in agentic output tasks. When a model hits the `max_completion_tokens` ceiling it stops mid-output and returns whatever it has — no error, no warning. The API call succeeds with `finish_reason: \"length\"` instead of `\"stop\"`.\r\n\r\n**This is especially dangerous for code-rewrite agents** where the output is a full file.\r\n\r\n```\r\n# Real numbers (gpt-5-mini, order-service.ts rewrite):\r\n Blockers section: ~120 tokens\r\n Fixed code: ~2,800 tokens (213 lines with // FIX: comments)\r\n Total needed: ~3,000 tokens ← hits the cap exactly → empty output\r\n Fix: set to 16,000 → full rewrite delivered in one shot\r\n```\r\n\r\n### Rule of Thumb by Task\r\n\r\n| Task | Recommended cap |\r\n|---|---|\r\n| Short classification / sentiment | 200–500 |\r\n| Code review findings (one reviewer) | 400–800 |\r\n| Blocker summary (coordinator) | 500–1,000 |\r\n| Full file rewrite (≤300 lines) | 12,000–16,000 |\r\n| Full file rewrite (≤1,000 lines) | 32,000–64,000 |\r\n| Document / design revision | 16,000–32,000 |\r\n\r\nAll GPT-5 variants support **128,000 max output tokens** — the ceiling is never the model, it is always the cap you set.\r\n\r\n### Lessons from Building the Code-Review Swarm\r\n\r\n| Issue | Root cause | Fix |\r\n|---|---|---|\r\n| Fixed code output was empty | `max_completion_tokens: 3000` too low | Raise to `16000`+ for any code-output agent |\r\n| `finish_reason: \"length\"` silently discards | Model hits cap, partial response, no error | Always check `choices[0].finish_reason` and alert on `\"length\"` |\r\n| Flagship model slow + expensive for reviewers | High latency + $14/1M output tokens | Use `gpt-5-mini` ($2/1M, same RPM) for reviewer/fixer agents |\r\n| Coordinator + fixer as two calls | Second call hits rate limit window, +60s | Merge into one structured two-section call |\n\nFile v4.0.13:INTEGRATION_GUIDE.md\n\n# Network-AI Integration Guide\r\n\r\n**For technical leads, solutions architects, and engineering teams evaluating or deploying Network-AI in a production environment.**\r\n\r\nThis guide walks from \"we want this\" to \"it's running in production\" — covering discovery, framework mapping, phased rollout, enterprise concerns, and validation.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Before You Start — Discovery](#1-before-you-start--discovery)\r\n2. [Framework Mapping](#2-framework-mapping)\r\n3. [Primitive Mapping — What Solves What](#3-primitive-mapping--what-solves-what)\r\n4. [Phased Rollout](#4-phased-rollout)\r\n5. [Enterprise Concerns](#5-enterprise-concerns)\r\n6. [Architecture Patterns](#6-architecture-patterns)\r\n7. [Validation Checklist](#7-validation-checklist)\r\n8. [Common Integration Mistakes](#8-common-integration-mistakes)\r\n\r\n---\r\n\r\n## 1. Before You Start — Discovery\r\n\r\nBefore touching any code, answer these questions. They determine which adapters you need and which governance primitives are non-negotiable.\r\n\r\n### 1.1 Agent Inventory\r\n\r\nDocument every AI agent or automated process your team currently runs:\r\n\r\n| Agent / Process | Language | Framework | Shares State With | Writes To |\r\n|----------------|----------|-----------|-------------------|-----------|\r\n| e.g. \"invoice classifier\" | Python | LangChain | \"approvals bot\" | Postgres |\r\n| e.g. \"customer triage\" | Node | AutoGen | \"CRM writer\" | Salesforce API |\r\n\r\n> **Why this matters:** Each row maps to one or more Network-AI adapters. Agents that share state with others are your highest-risk race condition points.\r\n\r\n### 1.2 Race Condition Audit\r\n\r\nFor each pair of agents that write to the same resource, ask:\r\n\r\n- Can both agents run at the same time?\r\n- What happens if Agent A's write is overwritten by Agent B before Agent A reads it back?\r\n- Is there any locking or retry logic today?\r\n\r\nIf the answer to the first question is \"yes\" and the second is \"data loss / wrong decision / double spend\" — that's a `LockedBlackboard` candidate.\r\n\r\n### 1.3 Budget and Cost Exposure\r\n\r\n- Do you have per-agent token limits today?\r\n- Can a single runaway agent exhaust your OpenAI / Anthropic budget?\r\n- Do you have hard cut-offs or just alerts?\r\n\r\nNetwork-AI's `FederatedBudget` enforces hard ceilings. If you have no ceiling today, this is your first priority.\r\n\r\n### 1.4 Compliance and Audit Requirements\r\n\r\n- Does your industry require audit trails for automated decisions (GDPR, SOC 2, HIPAA, PCI-DSS)?\r\n- Do you need to prove *which agent* made *which decision* and *when*?\r\n- Are there regulatory rules about which systems an AI agent may access?\r\n\r\nAnswers drive `AuthGuardian` configuration and audit log retention policy.\r\n\r\n---\r\n\r\n## 2. Framework Mapping\r\n\r\nNetwork-AI ships 12 adapters. Map your existing agents to the right one:\r\n\r\n| Your Stack | Network-AI Adapter | Notes |\r\n|-----------|-------------------|-------|\r\n| LangChain (JS/TS) | `LangChainAdapter` | Supports Runnables, chains, agents |\r\n| AutoGen / AG2 | `AutoGenAdapter` | Supports `.run()` and `.generateReply()` |\r\n| CrewAI | `CrewAIAdapter` | Individual agents and full crew objects |\r\n| OpenAI Assistants | `OpenAIAssistantsAdapter` | Thread management included |\r\n| LlamaIndex | `LlamaIndexAdapter` | Query engines, chat engines, agent runners |\r\n| Semantic Kernel | `SemanticKernelAdapter` | Microsoft SK kernels, functions, planners |\r\n| Haystack | `HaystackAdapter` | Pipelines, agents, components |\r\n| DSPy | `DSPyAdapter` | Modules, programs, predictors |\r\n| Agno (ex-Phidata) | `AgnoAdapter` | Agents, teams, functions |\r\n| MCP tools | `McpAdapter` | Tool serving and discovery |\r\n| OpenClaw / Clawdbot / Moltbot | `OpenClawAdapter` | Native skill execution via `callSkill` |\r\n| **Anything else** | `CustomAdapter` | Wrap any async function or HTTP endpoint |\r\n\r\n### No matching framework?\r\n\r\nUse `CustomAdapter`. Any async function becomes a governed agent in three lines:\r\n\r\n```typescript\r\nimport { CustomAdapter } from 'network-ai';\r\n\r\nconst adapter = new CustomAdapter();\r\nadapter.registerHandler('my-agent', async (payload) => {\r\n // your existing logic here — unchanged\r\n return { result: '...' };\r\n});\r\n```\r\n\r\nThis is the recommended entry point for **legacy systems**, **internal microservices**, and **REST APIs** — you do not need to rewrite anything.\r\n\r\n---\r\n\r\n## 3. Primitive Mapping — What Solves What\r\n\r\nMatch your problem to the Network-AI primitive:\r\n\r\n| Problem | Primitive | How |\r\n|---------|-----------|-----|\r\n| Two agents overwriting each other's data | `LockedBlackboard` | Atomic `propose → validate → commit` with file-system mutex |\r\n| Agent overspending token budget | `FederatedBudget` | Per-agent ceiling; hard cut-off on overspend |\r\n| Agent accessing a resource it shouldn't | `AuthGuardian` + `SecureTokenManager` | HMAC-signed scoped tokens required at every sensitive operation |\r\n| No audit trail for automated decisions | Audit log (`data/audit_log.jsonl`) | Cryptographic HMAC-signed chain, every write recorded |\r\n| Agent running out of turn / taking too many actions | `ComplianceMonitor` | TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT detected in real time |\r\n| Workflow needs defined states (e.g. INTAKE → REVIEW → APPROVE) | `JourneyFSM` | State machine gates which agents may act in which states |\r\n| Content safety / hallucination in agent outputs | `QualityGateAgent` + `BlackboardValidator` | Two-layer validation before output enters the blackboard |\r\n| Race conditions in parallel agent writes | `LockedBlackboard` with `priority-wins` | Higher-priority agents preempt lower-priority writes on conflict |\r\n| Need to expose all tools to an AI via MCP | `McpSseServer` + `network-ai-server` | HTTP/SSE server at `GET /sse`, `POST /mcp`, `GET /tools` |\r\n| Runtime AI control of the orchestrator | `ControlMcpTools` | AI can read/set config, spawn/stop agents, drive FSM transitions |\r\n\r\n---\r\n\r\n## 4. Phased Rollout\r\n\r\nDo not try to enable everything at once. This is the recommended sequence for a zero-disruption integration:\r\n\r\n### Phase 1 — Wrap (Day 1–3)\r\n\r\n**Goal:** Get your existing agents running inside Network-AI without changing their behaviour.\r\n\r\n1. `npm install network-ai`\r\n2. Wrap each agent in the matching adapter (see §2)\r\n3. Register all adapters with `AdapterRegistry`\r\n4. Replace direct agent calls with `registry.executeAgent(...)` or `orchestrator.execute(...)`\r\n5. Run `npm run demo -- --08` to verify the framework itself is healthy in your environment\r\n\r\n**Nothing changes behaviourally yet.** This phase is purely structural.\r\n\r\n```typescript\r\nimport { createSwarmOrchestrator, CustomAdapter } from 'network-ai';\r\n\r\nconst orchestrator = createSwarmOrchestrator({ swarmName: 'acme-swarm' });\r\nconst adapter = new CustomAdapter();\r\n\r\n// Wrap your existing function — unchanged\r\nadapter.registerHandler('invoice-classifier', async (payload) => {\r\n return await yourExistingClassifier(payload.params);\r\n});\r\n\r\nawait orchestrator.addAdapter(adapter);\r\n```\r\n\r\n---\r\n\r\n### Phase 2 — Shared State (Day 3–7)\r\n\r\n**Goal:** Replace ad-hoc shared resources (databases, files, in-memory objects) with the blackboard.\r\n\r\n1. Identify all keys agents share (from your §1.1 audit)\r\n2. Introduce `SharedBlackboard` for low-contention data\r\n3. Introduce `LockedBlackboard` for any key that two or more agents write to concurrently\r\n\r\n```typescript\r\nimport { LockedBlackboard } from 'network-ai';\r\n\r\nconst board = new LockedBlackboard('.', { conflictResolution: 'priority-wins' });\r\n\r\n// Atomic write — no other agent can interfere during this operation\r\nconst changeId = board.proposeChange('account:balance', newBalance, 'payment-agent');\r\nboard.validateChange(changeId);\r\nboard.commitChange(changeId);\r\n```\r\n\r\n> **Migration tip:** Start by shadowing — write to both your existing DB and the blackboard simultaneously. Once you're confident they match, remove the DB writes.\r\n\r\n---\r\n\r\n### Phase 3 — Budget Enforcement (Day 7–10)\r\n\r\n**Goal:** Add hard token ceilings so no single agent can exhaust your LLM budget.\r\n\r\n```typescript\r\nimport { FederatedBudget } from 'network-ai/lib/federated-budget';\r\n\r\nconst budget = new FederatedBudget({\r\n pools: {\r\n 'classifier': { ceiling: 50_000 }, // tokens per run\r\n 'summarizer': { ceiling: 100_000 },\r\n 'orchestrator': { ceiling: 200_000 },\r\n }\r\n});\r\n\r\n// Check before each LLM call\r\nconst check = budget.canSpend('classifier', estimatedTokens);\r\nif (!check.allowed) throw new Error(`Budget ceiling reached: ${check.reason}`);\r\n\r\n// Record actual spend after\r\nbudget.recordSpend('classifier', actualTokens);\r\n```\r\n\r\nMap your cost centers to pool names. Budget state persists across agent runs.\r\n\r\n---\r\n\r\n### Phase 4 — Access Control (Day 10–14)\r\n\r\n**Goal:** Gate access to sensitive APIs and resources behind cryptographically signed tokens.\r\n\r\n1. Define your resources and risk levels (see `references/auth-guardian.md`)\r\n2. Map your agents to trust levels (see `references/trust-levels.md`)\r\n3. Replace direct API calls with `AuthGuardian`-gated calls\r\n\r\n```typescript\r\nimport { AuthGuardian, SecureTokenManager } from 'network-ai';\r\n\r\nconst guardian = new AuthGuardian();\r\nconst tokenManager = new SecureTokenManager(process.env.HMAC_SECRET!);\r\n\r\n// Agent requests access with a justification\r\nconst request = await guardian.requestPermission({\r\n agentId: 'payment-agent',\r\n resource: 'PAYMENTS',\r\n action: 'write',\r\n justification: 'Processing approved invoice #INV-2847 per workflow step 3',\r\n trustLevel: 0.8,\r\n});\r\n\r\nif (request.approved) {\r\n const token = tokenManager.createToken('payment-agent', ['PAYMENTS:write'], 300);\r\n // pass token to downstream call\r\n}\r\n```\r\n\r\n**IAM integration:** The token payload (agentId, permissions, expiry) can be forwarded as a JWT claim to your existing IAM layer. Network-AI does not replace your IAM — it sits in front of it as a pre-authorization layer.\r\n\r\n---\r\n\r\n### Phase 5 — Governance and FSM (Day 14–21)\r\n\r\n**Goal:** Define explicit workflow states so agents can only act when the system is in the right state.\r\n\r\n```typescript\r\nimport { JourneyFSM, WORKFLOW_STATES } from 'network-ai';\r\n\r\nconst fsm = new JourneyFSM({\r\n agentId: 'workflow',\r\n journeyId: 'invoice-processing',\r\n transitions: [\r\n { from: 'INTAKE', to: 'ANALYZE', allowedAgents: ['intake-agent'] },\r\n { from: 'ANALYZE', to: 'APPROVE', allowedAgents: ['analyst-agent'] },\r\n { from: 'APPROVE', to: 'EXECUTE', allowedAgents: ['approver-agent'] },\r\n { from: 'EXECUTE', to: 'DELIVER', allowedAgents: ['payment-agent'] },\r\n ]\r\n});\r\n\r\n// Before any agent acts, check the FSM\r\nconst canAct = fsm.canTransition(currentState, nextState, agentId);\r\n```\r\n\r\nAdd `ComplianceMonitor` to detect violations in real time without blocking the main thread:\r\n\r\n```typescript\r\nimport { ComplianceMonitor } from 'network-ai';\r\n\r\nconst monitor = new ComplianceMonitor(fsm, {\r\n maxActionsPerTurn: 5,\r\n responseTimeoutMs: 30_000,\r\n journeyTimeoutMs: 300_000,\r\n});\r\nmonitor.start(1_000); // poll every second\r\n```\r\n\r\n---\r\n\r\n### Phase 6 — Observability and MCP (Day 21+)\r\n\r\n**Goal:** Expose everything to your monitoring stack and optionally give your AI models control-plane access.\r\n\r\nStart the MCP server (exposes 20+ tools via SSE/JSON-RPC):\r\n\r\n```bash\r\nnpx network-ai-server --port 3001 --audit-log data/audit_log.jsonl --ceiling 500000\r\n```\r\n\r\nConnect your AI model to `http://localhost:3001/sse` — it can now:\r\n- Read and write live config (`config_get`, `config_set`)\r\n- Spawn and stop agents (`agent_spawn`, `agent_stop`)\r\n- Drive FSM transitions (`fsm_transition`)\r\n- Query the audit log (`audit_query`, `audit_tail`)\r\n- Check and top up budgets (`budget_status`, `budget_spend`)\r\n\r\n---\r\n\r\n## 5. Enterprise Concerns\r\n\r\n### Authentication & IAM\r\n\r\nNetwork-AI does **not** require or replace an external IAM system. `AuthGuardian` operates as a **pre-authorization layer**:\r\n\r\n```\r\nAI Agent → AuthGuardian (justification scoring) → your IAM (final auth) → resource\r\n```\r\n\r\nThe HMAC secret (`HMAC_SECRET` env var) should be rotated on the same schedule as your other API keys and stored in your secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).\r\n\r\n### Audit Log Retention\r\n\r\nThe audit log at `data/audit_log.jsonl` is a HMAC-signed append-only chain. Each entry contains: timestamp, agentId, eventType, resource, outcome, and a chain signature.\r\n\r\n- **GDPR / right to erasure:** Entries are immutable by design. If data subject erasure applies, store identifying data outside the log and reference only pseudonymized agent IDs inside it.\r\n- **Retention:** Rotate files using your standard log rotation tooling (logrotate, Fluentd, etc.). The chain continues across files — verification just needs the previous file's last hash.\r\n- **SIEM integration:** Stream `audit_log.jsonl` to Splunk, Datadog, or Elastic via the `audit_tail` MCP tool or a simple `tail -F` feed.\r\n\r\n### Air-Gapped / On-Prem Deployment\r\n\r\nNetwork-AI has **zero required external network calls**. All operations (blackboard, FSM, compliance, budget, tokens, audit) run entirely on-premises:\r\n\r\n- No telemetry, no call-home, no cloud dependency\r\n- LLM calls only happen if *you* add an adapter that calls an LLM — e.g. `OpenAIAssistantsAdapter` will call `api.openai.com`, but this is your explicit choice\r\n- The MCP server (`network-ai-server`) binds to localhost by default; deploy behind your internal API gateway to expose it to your agent fleet\r\n\r\n### Multi-Tenant Deployments\r\n\r\nIsolate tenants by:\r\n1. **Separate blackboard roots** — each tenant gets their own directory path passed to `LockedBlackboard(tenantPath)`\r\n2. **Separate budget pools** — prefix pool names with tenant ID: `tenant-abc:classifier`\r\n3. **Separate HMAC secrets** — one `SecureTokenManager` instance per tenant\r\n4. **Namespace scoping** — use consistent key prefixes in the blackboard (e.g. `tenant-abc:invoice:42`)\r\n\r\n### Scaling\r\n\r\nNetwork-AI is a **single-process orchestrator** by design — it does not require a broker, queue, or service mesh. For horizontal scaling:\r\n\r\n- **Shared `LockedBlackboard`:** Point multiple instances at the same directory on a shared volume (NFS, EFS, Azure Files). File-system mutexes work across processes on the same mount.\r\n- **Independent budget tracking:** Each instance tracks its own pool. Use a sidecar or the `audit_tail` MCP tool to aggregate spend across instances.\r\n- **FSM per workflow:** One `JourneyFSM` per workflow instance, not per process. FSM state persists to the blackboard, so any process can resume an interrupted journey.\r\n\r\n---\r\n\r\n## 6. Architecture Patterns\r\n\r\n### Pattern A — Sidecar (Minimal Disruption)\r\n\r\nKeep your existing agent orchestration. Add Network-AI only for coordination, safety, and audit on the shared state layer.\r\n\r\n```\r\n[Existing LangChain agent] ──writes──▶ [LockedBlackboard] ◀──reads── [Existing AutoGen agent]\r\n │\r\n [Audit log]\r\n [Budget tracking]\r\n```\r\n\r\nNo changes to your agent code. Network-AI wraps the shared resource only.\r\n\r\n---\r\n\r\n### Pattern B — Full Orchestrator\r\n\r\nNetwork-AI owns the entire agent lifecycle. All agents run through the adapter registry.\r\n\r\n```\r\nUser request\r\n │\r\n ▼\r\nSwarmOrchestrator\r\n │\r\n ├──▶ AuthGuardian (permission check)\r\n ├──▶ JourneyFSM (state gate)\r\n ├──▶ FederatedBudget (cost check)\r\n │\r\n ├──▶ LangChainAdapter ──▶ your LangChain agent\r\n ├──▶ AutoGenAdapter ──▶ your AutoGen agent\r\n └──▶ CustomAdapter ──▶ your existing functions\r\n```\r\n\r\n---\r\n\r\n### Pattern C — MCP Control Plane\r\n\r\nYour AI model connects to `network-ai-server` via SSE and drives the whole system through MCP tools — no hand-coded orchestration logic at all.\r\n\r\n```\r\nAI Model (Claude / GPT-4o)\r\n │ SSE/JSON-RPC\r\n ▼\r\nnetwork-ai-server (port 3001)\r\n │\r\n ├── ControlMcpTools (spawn agents, drive FSM, set config)\r\n ├── ExtendedMcpTools (budget, tokens, audit)\r\n └── BlackboardMCPTools (read/write blackboard)\r\n```\r\n\r\n---\r\n\r\n## 7. Validation Checklist\r\n\r\nRun these before declaring the integration production-ready:\r\n\r\n### Functional\r\n\r\n- [ ] All agents execute via the adapter registry without errors\r\n- [ ] `npx ts-node test-standalone.ts` — 79 core tests pass\r\n- [ ] `npx ts-node test-security.ts` — 33 security tests pass\r\n- [ ] `npx ts-node test-adapters.ts` — 139 adapter tests pass\r\n- [ ] `npx ts-node test-phase4.ts` — 147 behavioral tests pass\r\n- [ ] `npm run demo -- --08` runs to completion in < 10 seconds\r\n\r\n### Race Condition Safety\r\n\r\n- [ ] Two agents can write to the same blackboard key concurrently without data loss\r\n- [ ] `LockedBlackboard.validateChange()` rejects a stale change after a conflict\r\n- [ ] `priority-wins` correctly overwrites a lower-priority pending write\r\n\r\n### Budget Enforcement\r\n\r\n- [ ] Spending past the ceiling throws / returns `allowed: false`\r\n- [ ] Budget state persists across process restart\r\n- [ ] Per-agent pools are independent (overspending in pool A does not affect pool B)\r\n\r\n### Access Control\r\n\r\n- [ ] A token issued by `SecureTokenManager` validates correctly\r\n- [ ] An expired token is rejected\r\n- [ ] A token with insufficient scope is rejected at the `AuthGuardian` gate\r\n- [ ] `--active-grants` shows the correct active token set\r\n\r\n### Compliance\r\n\r\n- [ ] `ComplianceMonitor` fires `TOOL_ABUSE` after the configured action threshold\r\n- [ ] `RESPONSE_TIMEOUT` fires when an agent exceeds the timeout window\r\n- [ ] `JOURNEY_TIMEOUT` fires when the overall journey exceeds its ceiling\r\n- [ ] FSM blocks a transition attempted by an unauthorized agent\r\n\r\n### Audit\r\n\r\n- [ ] Every blackboard write produces a signed entry in `audit_log.jsonl`\r\n- [ ] `audit_query` returns filtered results correctly\r\n- [ ] The audit chain signature is intact after N entries (run the chain verifier)\r\n\r\n---\r\n\r\n## 8. Common Integration Mistakes\r\n\r\n| Mistake | Consequence | Fix |\r\n|---------|-------------|-----|\r\n| Using `SharedBlackboard` for concurrent writes | Race conditions / data loss | Use `LockedBlackboard` for any key two agents write to |\r\n| Not committing the lock file (`package-lock.json`) | CI `npm ci` fails on Node version mismatch | Always commit `package-lock.json` after version bumps |\r\n| Not including `socket.json` in `package.json` `files` | Socket.dev ignores aren't shipped; supply chain score drops | Add `socket.json` to the `files` array |\r\n| Hardcoded agent IDs in trust level config | Agent added later gets default 0.5 trust and is silently denied | Maintain a central trust registry; register new agents before deploying |\r\n| One `FederatedBudget` pool shared by all agents | One runaway agent exhausts budget for everyone | One pool per agent or per role |\r\n| FSM with no timeout | Stuck workflow holds locks indefinitely | Always set `timeoutMs` on states that involve external calls |\r\n| Storing PII as blackboard keys | Audit log contains PII in plain text | Use pseudonymised keys; store PII in a separate encrypted store |\r\n| Running `network-ai-server` on `0.0.0.0` in production | MCP control plane is publicly accessible | Bind to localhost and expose via authenticated internal API gateway only |\r\n\r\n---\r\n\r\n## Further Reading\r\n\r\n| Document | What It Covers |\r\n|----------|---------------|\r\n| [QUICKSTART.md](QUICKSTART.md) | Get running in 5 minutes |\r\n| [references/adapter-system.md](references/adapter-system.md) | All 12 adapters with code examples |\r\n| [references/trust-levels.md](references/trust-levels.md) | Trust scoring formula and agent roles |\r\n| [references/auth-guardian.md](references/auth-guardian.md) | Permission system, justification scoring, token lifecycle |\r\n| [references/blackboard-schema.md](references/blackboard-schema.md) | Blackboard key conventions and namespacing |\r\n| [references/mcp-roadmap.md](references/mcp-roadmap.md) | MCP server tools reference |\r\n| [examples/README.md](examples/README.md) | All runnable demos |\r\n| [CHANGELOG.md](CHANGELOG.md) | Full version history |\r\n\r\n---\r\n\r\n*Network-AI v4.0.6 · MIT License · https://github.com/jovanSAPFIONEER/Network-AI*\n\nFile v4.0.13:SHOW_HN.md\n\n# Show HN: Network-AI — Multi-Agent Race Condition Prevention for TypeScript\r\n\r\n**Post title:**\r\n> Show HN: Network-AI – plug-and-play orchestrator that prevents race conditions when AI agents share state\r\n\r\n---\r\n\r\n## Body\r\n\r\nI built Network-AI because I kept hitting the same problem: run two AI agents in parallel, they write to the same resource at the same time, and one of them silently overwrites the other. No error. No warning. Just wrong output.\r\n\r\nMost agent frameworks give you parallelism. None of them give you coordination safety.\r\n\r\n**The classic failure:**\r\n\r\n```\r\nAgent A reads balance: $10,000\r\nAgent B reads balance: $10,000 ← same moment\r\nAgent A writes balance: $3,000 ← deducts $7,000\r\nAgent B writes balance: $4,000 ← deducts $6,000, ignoring Agent A's write\r\n```\r\n\r\nBoth agents believed they had $10,000. Both spent from it. You now have a $3,000 error with no trace of what happened.\r\n\r\nThis is a split-brain problem, and it happens any time two LLM agents hit a shared database, file, or API concurrently. It's not theoretical — I've seen it in production pipelines.\r\n\r\n---\r\n\r\n**What Network-AI does:**\r\n\r\n- **Atomic blackboard** — `propose → validate → commit` with file-system mutex. No two agents can write to the same key simultaneously.\r\n- **Priority preemption** — if two agents conflict, the higher-priority write wins deterministically (not \"last write wins\" chaos)\r\n- **FSM governance** — agents can only act when the workflow is in the right state\r\n- **FederatedBudget** — per-agent token ceilings with hard cut-off. One runaway agent cannot exhaust your OpenAI bill.\r\n- **ComplianceMonitor** — detects TOOL_ABUSE, turn-taking violations, response timeouts, journey timeouts in real time\r\n- **12 framework adapters** — LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and a CustomAdapter for anything else\r\n\r\n---\r\n\r\n**You can see the whole thing in 2 seconds with no API key:**\r\n\r\n```bash\r\ngit clone https://github.com/jovanSAPFIONEER/Network-AI\r\ncd Network-AI\r\nnpm install\r\nnpm run demo -- --08\r\n```\r\n\r\nThis runs the control-plane stress demo: atomic commits, priority preemption, FSM timeout, and 17 live compliance violations — all in ~2 seconds, no LLM calls.\r\n\r\n---\r\n\r\n**Or the full AI showcase** (needs `OPENAI_API_KEY`):\r\n\r\n```bash\r\nnpm run demo -- --07\r\n```\r\n\r\n8-agent pipeline that builds a Payment Processing Service with FSM gating, scoped auth tokens, per-agent budget ceilings, AI quality gates, automated code fixing, and deterministic 10/10 scoring. Writes a cryptographically signed audit trail to disk on every run.\r\n\r\n---\r\n\r\n**Stack:** TypeScript, Node.js 18+. Zero required external services. Works on-prem, air-gapped, or cloud.\r\n\r\n**Repo:** https://github.com/jovanSAPFIONEER/Network-AI \r\n**npm:** `npm install network-ai` \r\n**MCP server:** `npx network-ai-server --port 3001`\r\n\r\nHappy to answer questions about the coordination model, the FSM design, or how the atomic commits work.\r\n\r\n---\r\n\r\n## Timing notes\r\n\r\n- Post on a **Tuesday or Wednesday between 9–11am ET** — peak HN traffic window\r\n- Tag: `Show HN`\r\n- Do not post the same week as a major AI framework release (it will get buried)\r\n- Have the demo commands ready to paste in the comments — someone will ask immediately\r\n\r\n## Expected comment threads to prepare for\r\n\r\n1. \"How is this different from LangGraph / LangChain?\" → answer: Network-AI is the coordination layer, not the agent logic. It works *with* LangChain (there's an adapter).\r\n2. \"Does this work with Python?\" → Python scripts are included (`scripts/`), TypeScript is the orchestration layer\r\n3. \"What's the performance overhead of the file-system mutex?\" → microseconds for local; designed for workloads where LLM latency (100ms–10s) dominates\r\n4. \"Is this production-ready?\" → MIT, 1,200+ tests, CodeQL + OpenSSF Scorecard on CI, 2,500+ weekly npm downloads at 24 days old\n\nFile v4.0.13:requirements.txt\n\n# Python dependencies for Swarm Orchestrator Skill\r\n# Install: pip install -r requirements.txt\r\n\r\n# Core dependencies (all optional - stdlib works on Unix)\r\n# filelock>=3.0.0 # Cross-platform file locking (recommended for Windows)\r\n\r\n# Note: The blackboard uses fcntl on Unix (built-in) with fallback for Windows.\r\n# For production Windows deployments, uncomment filelock above.\r\n\r\n# If you want to run type checking:\r\n# mypy>=1.0.0\r\n\r\n# If you want to run tests:\r\n# pytest>=7.0.0","readmeExcerpt":"Skill: Network-AI Owner: jovanSAPFIONEER Summary: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e... Tags: audit:4.0.4, autogen:4.0.4, blackboard:4.0.4, crewai:4.0.4, langchain:4.0.4, latest:4.0.14, mcp:4.0.4, multi-agent:4.0.4, orchestration:4.0.4, permissions:4.0.4, security:4.0.4, swarm:4.0.4 Version histo","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"File v4.0.14:AWESOME_LISTS.md\n\n# Awesome List PR Submissions\r\n\r\nReady-to-use PR titles, one-liners, and context for each list.\r\nSubmit these as pull requests to the respective repositories.\r\n\r\n---\r\n\r\n## 1. awesome-mcp-servers\r\n**Repo:** https://github.com/punkpeye/awesome-mcp-servers\r\n\r\n**PR title:**\r\n> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools\r\n\r\n**One-liner to add to the list:**"},{"language":"text","snippet":"File v4.0.13:AWESOME_LISTS.md\n\n# Awesome List PR Submissions\r\n\r\nReady-to-use PR titles, one-liners, and context for each list.\r\nSubmit these as pull requests to the respective repositories.\r\n\r\n---\r\n\r\n## 1. awesome-mcp-servers\r\n**Repo:** https://github.com/punkpeye/awesome-mcp-servers\r\n\r\n**PR title:**\r\n> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools\r\n\r\n**One-liner to add to the list:**"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: Network-AI\r\ndescription: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and enforces permission walls before sensitive operations. All execution is local and sandboxed.\r\nmetadata:\r\n openclaw:\r\n emoji: \"\\U0001F41D\"\r\n homepage: https://github.com/jovanSAPFIONEER/Network-AI\r\n requires:\r\n bins:\r\n - python3\r\n optional_bins:\r\n - node # Only needed if you separately install and run the Node.js MCP server (network-ai-server via npm). Not required for this skill's Python instructions.\r\n env:\r\n SWARM_TOKEN_SECRET:\r\n required: false\r\n description: \"Node.js MCP server only — not used by these Python scripts. The Python permission layer uses UUID-based tokens stored in data/active_grants.json.\"\r\n SWARM_ENCRYPTION_KEY:\r\n required: false\r\n description: \"Node.js MCP server only — not used by these Python scripts. The Python blackboard does not encrypt data at rest.\"\r\n OPENAI_API_KEY:\r\n required: false\r\n description: \"Not used by these Python scripts. Only used by the optional Node.js demo examples when running the companion npm package.\"\r\n privacy:\r\n audit_log:\r\n path: data/audit_log.jsonl\r\n scope: local-only\r\n description: \"Local append-only JSONL file recording operation metadata (agentId, action, timestamp, outcome). No data leaves the machine. Disable with --no-audit flag on network-ai-server, or pass auditLogPath: undefined in createSwarmOrchestrator config.\"\r\n---\r\n\r\n# Swarm Orchestrator Skill\r\n\r\n> **Scope of this skill bundle:** All instructions below run local Python scripts (`scripts/*.py`). No network calls are made by this skill. Tokens are UUID-based (`grant_{uuid4().hex}`) stored in `data/active_grants.json`. Audit logging is plain JSONL (`data/audit_log.jsonl`) — no HMAC signing in the Python layer. HMAC-signed tokens, AES-256 encryption, and the standalone MCP server are all features of the **companion Node.js package** (`npm install -g network-ai`) — they are **not** implemented in these Python scripts and do **not** run automatically.\r\n\r\nMulti-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.\r\n\r\n## 🎯 Orchestrator System Instructions\r\n\r\n**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:\r\n\r\n### Core Responsibilities\r\n\r\n1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks\r\n2. **DELEGATE** using the budget-aware handoff protocol\r\n3. **VERIFY** results on the blackboard before committing\r\n4. **SYNTHESIZE** final output only after all validations pass\r\n\r\n### Task Decomposition Protocol\r\n\r\nWhen you receive a complex request, decompose it into exactly **3 sub-tasks**:\r\n\r\n```\r\n┌──────────────────────────────"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75j1xcebk74re38bv714kh1h81804p\",\n \"slug\": \"network-ai\",\n \"version\": \"4.0.14\",\n \"publishedAt\": 1772305198541\n}"},{"path":"ARCHITECTURE.md","content":"# Architecture\r\n\r\n## The Multi-Agent Race Condition Problem\r\n\r\nMost agent frameworks let you run multiple AI agents in parallel. None of them protect you when those agents write to the same resource at the same time.\r\n\r\n**The \"Bank Run\" scenario:**\r\n\r\n```\r\nAgent A reads balance: $10,000\r\nAgent B reads balance: $10,000 (same moment)\r\nAgent A writes balance: $10,000 - $7,000 = $3,000\r\nAgent B writes balance: $10,000 - $6,000 = $4,000 ← Agent A's write is gone\r\n```\r\n\r\nBoth agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.\r\n\r\nWithout concurrency control, parallel agents will:\r\n- **Corrupt shared state** — two agents overwrite each other's blackboard entries\r\n- **Double-spend budgets** — token costs exceed limits because agents don't see each other's spending\r\n- **Produce contradictory outputs** — Agent A says \"approved\", Agent B says \"denied\", both write to the same key\r\n\r\n**How Network-AI prevents this:**\r\n\r\n```typescript\r\n// Atomic commit — no other agent can read/write \"account:balance\" during this operation\r\nconst changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');\r\nblackboard.validateChange(changeId); // checks for conflicts\r\nblackboard.commitChange(changeId); // atomic write with file-system mutex\r\n```\r\n\r\n---\r\n\r\n## Component Overview\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────┐\r\n│ Your Application │\r\n└──────────────────────────┬──────────────────────────────────┘\r\n │ createSwarmOrchestrator()\r\n┌──────────────────────────▼──────────────────────────────────┐\r\n│ SwarmOrchestrator │\r\n│ │\r\n│ ┌──────────────┐ ┌───────────────┐ ┌─────────────────┐ │\r\n│ │ AdapterRegistry│ │ AuthGuardian │ │ FederatedBudget │ │\r\n│ │ (route tasks) │ │ (permissions) │ │ (token ceilings)│ │\r\n│ └──────┬───────┘ └───────────────┘ └─────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼──────────────────────────────────────────────┐ │\r\n│ │ LockedBlackboard (shared state) │ │\r\n│ │ propose → validate → commit (file-system mutex) │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n│ │ │\r\n│ ┌──────▼───────────────────────────────────────────────┐ │\r\n│ │ Adapters (plug any framework in, swap out freely) │ │\r\n│ │ LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │… │ │\r\n│ └──────────────────────────────────────────────────────┘ │\r\n└─────────────────────────────────────────────────────────────┘\r\n │\r\n HMAC-signed audit log (data/audit_log.jsonl)\r\n```\r\n\r\n### LockedBlackboard\r\n\r\nThe coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss."},{"path":"AWESOME_LISTS.md","content":"# Awesome List PR Submissions\r\n\r\nReady-to-use PR titles, one-liners, and context for each list.\r\nSubmit these as pull requests to the respective repositories.\r\n\r\n---\r\n\r\n## 1. awesome-mcp-servers\r\n**Repo:** https://github.com/punkpeye/awesome-mcp-servers\r\n\r\n**PR title:**\r\n> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration MCP server. 20+ MCP tools: blackboard read/write, agent spawn/stop, FSM transitions, budget tracking, token management, audit log query. `npx network-ai-server --port 3001`. TypeScript/Node.js.\r\n```\r\n\r\n**Where to add it:** Under the orchestration or multi-agent section.\r\n\r\n**PR body:**\r\n> network-ai ships a production-ready MCP server (`network-ai-server` binary) that exposes the full orchestration control plane over HTTP/SSE + JSON-RPC 2.0. It includes 20+ tools across 4 groups: blackboard coordination (read/write/lock), agent control (spawn/stop/list), FSM governance (transition/state), and observability (budget status, audit trail, token lifecycle). Zero config — `npx network-ai-server` starts immediately.\r\n\r\n---\r\n\r\n## 2. awesome-ai-agents\r\n**Repo:** https://github.com/e2b-dev/awesome-ai-agents\r\n\r\n**PR title:**\r\n> Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Plug-and-play multi-agent orchestration for TypeScript/Node.js. Connects 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, MCP, and more) with atomic shared state, FSM governance, per-agent budget enforcement, and cryptographic audit trails. Solves race conditions and split-brain writes in concurrent agent systems.\r\n```\r\n\r\n**PR body:**\r\n> network-ai fills a gap that most agent frameworks leave open: safe coordination when agents share state. It wraps any agent framework via adapters (12 supported) and adds atomic blackboard writes, FSM state gating, per-agent token budget ceilings, and a ComplianceMonitor for behavioral governance. MIT licensed, 1,200+ tests, CodeQL + OpenSSF Scorecard.\r\n\r\n---\r\n\r\n## 3. awesome-langchain\r\n**Repo:** https://github.com/kyrolabs/awesome-langchain\r\n\r\n**PR title:**\r\n> Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety\r\n\r\n**One-liner to add to the list:**\r\n```markdown\r\n- [network-ai](https://github.com/jovanSAPFIONEER/Network-AI) - Multi-agent orchestration framework with a first-class LangChain adapter. Wraps LangChain Runnables, chains, and agents with atomic shared state, permission gating, budget enforcement, and FSM governance. Prevents race conditions when multiple LangChain agents write to shared resources concurrently.\r\n```\r\n\r\n**Where to add it:** Under Tools / Agent frameworks / Orchestration.\r\n\r\n---\r\n\r\n## 4. awesome-"},{"path":"BENCHMARKS.md","content":"# Benchmarks & Performance\r\n\r\n> Performance data for Network-AI deployments. Your swarm is only as fast as the backend it calls — this page helps you choose the right setup.\r\n\r\n## BlackboardValidator Throughput\r\n\r\nLayer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:\r\n\r\n| Input size | Ops/sec | Latency |\r\n|---|---|---|\r\n| Small entry (~100 chars) | ~1,000,000 | < 1 µs |\r\n| Medium entry (~1 KB) | ~500,000 | ~2 µs |\r\n| Large entry (~10 KB) | ~159,000 | ~6 µs |\r\n\r\nLayer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.\r\n\r\n---\r\n\r\n## Cloud Provider Performance\r\n\r\nNot all cloud APIs perform the same. Model size, inference infrastructure, and tier all affect how fast each agent gets a response — and that directly multiplies across every agent in your swarm.\r\n\r\n| Provider / Model | Avg response (5-agent swarm) | RPM limit (free/tier-1) | Notes |\r\n|---|---|---|---|\r\n| **OpenAI gpt-5.2** | 6–10s per call | 3–6 RPM | Flagship model, high latency, strict RPM |\r\n| **OpenAI gpt-4o-mini** | 2–4s per call | 500 RPM | Fast, cheap, good for reviewer agents |\r\n| **OpenAI gpt-4o** | 4–7s per call | 60–500 RPM | Balanced quality/speed |\r\n| **Anthropic Claude 3.5 Haiku** | 2–3s per call | 50 RPM | Fastest Claude, great for parallel agents |\r\n| **Anthropic Claude 3.7 Sonnet** | 4–8s per call | 50 RPM | Stronger reasoning, higher latency |\r\n| **Google Gemini 2.0 Flash** | 1–3s per call | 15 RPM (free) | Very fast inference, low RPM on free tier |\r\n| **Groq (Llama 3.3 70B)** | 0.5–2s per call | 30 RPM | Fastest cloud inference available |\r\n| **Together AI / Fireworks** | 1–3s per call | Varies by plan | Good for parallel workloads |\r\n\r\n**Key insight:** A 5-agent swarm using `gpt-4o-mini` at 500 RPM can fire all 5 agents truly in parallel and finish in ~4s total. The same swarm on `gpt-5.2` at 6 RPM must go sequential and takes 60s. **The model tier matters more than the orchestration framework.**\r\n\r\n### Choosing a Model for Swarm Agents\r\n\r\n- **Speed over depth** (many agents, real-time) → `gpt-4o-mini`, `claude-3.5-haiku`, `gemini-2.0-flash`, `groq/llama-3.3-70b`\r\n- **Depth over speed** (few agents, high-stakes) → `gpt-4o`, `claude-3.7-sonnet`\r\n- **Free / no-cost testing** → Groq free tier, Gemini free tier, or Ollama locally\r\n- **Production with budget** → multiple keys across providers, route agents to different models\r\n\r\n---\r\n\r\n## Rate Limit Patterns\r\n\r\nWhen you run a 5-agent swarm sharing one API key and hit the RPM ceiling, the API silently returns empty responses — not a 429 error, just blank content. Network-AI's swarm demos handle this automatically with **sequential dispatch** and **adaptive header-based pacing** (reads `x-ratelimit-reset-requests` to wait exactly as long as needed).\r\n\r\n| You have | What to expect |\r\n|---|---|\r\n| One cloud API key | Sequential dispatch, 40–70s per 5-agent swarm — handled automatically |\r\n| Multiple cloud keys | Near-parallel, 10–15s — "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e... Skill: Network-AI Owner: jovanSAPFIONEER Summary: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and e... Tags: audit:4.0.4, autogen:4.0.4, blackboard:4.0.4, crewai:4.0.4, langchain:4.0.4, latest:4.0.14, mcp:4.0.4, multi-agent:4.0.4, orchestration:4.0.4, permissions:4.0.4, security:4.0.4, swarm:4.0.4 Version histo","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1742,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:54:06.532Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}