How should Network-AI be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

Claim this agent

Agent DossierCLAWHUBSafety 84/100

Xpersona Agent

Network-AI

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

OpenClaw · self-declared

788 downloadsTrust evidence available

View on ClawHub

clawhub skill install kn75j1xcebk74re38bv714kh1h81804p:network-ai

Overall rank

#62

Adoption

788 downloads

Trust

Unknown

Freshness

Mar 1, 2026

Freshness

Last checked Mar 1, 2026

Best For

Network-AI is best for general automation workflows where OpenClaw compatibility matters.

Not Ideal For

Contract metadata is missing or unavailable for deterministic execution.

Evidence Sources Checked

editorial-content, CLAWHUB, runtime-metrics, public facts pack

Overview Evidence & Timeline Artifacts & Docs API & Reliability Media & Related Machine Appendix

Overview

Key links, install path, reliability highlights, and the shortest practical read before diving into the crawl record.

Verifiededitorial-content

Overview

Executive Summary

No verified compatibility signals788 downloads

Trust score

Unknown

Compatibility

OpenClaw

Freshness

Mar 1, 2026

Vendor

Clawhub

Artifacts

Benchmarks

Last release

4.0.14

Install & run

Setup Snapshot

clawhub skill install kn75j1xcebk74re38bv714kh1h81804p:network-ai

1
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.
2
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.

Evidence & Timeline

Public facts grouped by evidence type, plus release and crawl events with provenance and freshness.

Verifiededitorial-content

Public facts

Evidence Ledger

Vendor (1)

Vendor

Clawhub

profilemedium

Observed Apr 15, 2026Source link Provenance

Compatibility (1)

Protocol compatibility

OpenClaw

contractmedium

Observed Apr 15, 2026Source link Provenance

Release (1)

Latest release

4.0.14

releasemedium

Observed Feb 28, 2026Source link Provenance

Adoption (1)

Adoption signal

788 downloads

profilemedium

Observed Apr 15, 2026Source link Provenance

Security (1)

Handshake status

UNKNOWN

trustmedium

Observed unknownSource link Provenance

Events

Release & Crawl Timeline

Release

Release 4.0.14

releasemedium

**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.

Observed Feb 28, 2026

Artifacts & Docs

Parameters, dependencies, examples, extracted files, editorial overview, and the complete README when available.

Self-declaredCLAWHUB

Captured outputs

Artifacts Archive

Extracted files

Examples

Snippets

Languages

Unknown

Executable Examples

text

File v4.0.14:AWESOME_LISTS.md

# Awesome List PR Submissions

Ready-to-use PR titles, one-liners, and context for each list.
Submit these as pull requests to the respective repositories.

---

## 1. awesome-mcp-servers
**Repo:** https://github.com/punkpeye/awesome-mcp-servers

**PR title:**
> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools

**One-liner to add to the list:**

text

File v4.0.13:AWESOME_LISTS.md

# Awesome List PR Submissions

Ready-to-use PR titles, one-liners, and context for each list.
Submit these as pull requests to the respective repositories.

---

## 1. awesome-mcp-servers
**Repo:** https://github.com/punkpeye/awesome-mcp-servers

**PR title:**
> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools

**One-liner to add to the list:**

Extracted Files

SKILL.md

---
name: Network-AI
description: 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.
metadata:
openclaw:
emoji: "\U0001F41D"
homepage: https://github.com/jovanSAPFIONEER/Network-AI
requires:
bins:
- python3
optional_bins:
- 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.
env:
SWARM_TOKEN_SECRET:
required: false
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."
SWARM_ENCRYPTION_KEY:
required: false
description: "Node.js MCP server only — not used by these Python scripts. The Python blackboard does not encrypt data at rest."
OPENAI_API_KEY:
required: false
description: "Not used by these Python scripts. Only used by the optional Node.js demo examples when running the companion npm package."
privacy:
audit_log:
path: data/audit_log.jsonl
scope: local-only
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."
---

# Swarm Orchestrator Skill

> **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.

Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.

## 🎯 Orchestrator System Instructions

**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:

### Core Responsibilities

1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks
2. **DELEGATE** using the budget-aware handoff protocol
3. **VERIFY** results on the blackboard before committing
4. **SYNTHESIZE** final output only after all validations pass

### Task Decomposition Protocol

When you receive a complex request, decompose it into exactly **3 sub-tasks**:

```
┌──────────────────────────────

_meta.json

{
  "ownerId": "kn75j1xcebk74re38bv714kh1h81804p",
  "slug": "network-ai",
  "version": "4.0.14",
  "publishedAt": 1772305198541
}

ARCHITECTURE.md

# Architecture

## The Multi-Agent Race Condition Problem

Most 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.

**The "Bank Run" scenario:**

```
Agent A reads balance:  $10,000
Agent B reads balance:  $10,000       (same moment)
Agent A writes balance: $10,000 - $7,000 = $3,000
Agent B writes balance: $10,000 - $6,000 = $4,000   ← Agent A's write is gone
```

Both agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.

Without concurrency control, parallel agents will:
- **Corrupt shared state** — two agents overwrite each other's blackboard entries
- **Double-spend budgets** — token costs exceed limits because agents don't see each other's spending
- **Produce contradictory outputs** — Agent A says "approved", Agent B says "denied", both write to the same key

**How Network-AI prevents this:**

```typescript
// Atomic commit — no other agent can read/write "account:balance" during this operation
const changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');
blackboard.validateChange(changeId);   // checks for conflicts
blackboard.commitChange(changeId);     // atomic write with file-system mutex
```

---

## Component Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
└──────────────────────────┬──────────────────────────────────┘
                           │  createSwarmOrchestrator()
┌──────────────────────────▼──────────────────────────────────┐
│                  SwarmOrchestrator                          │
│                                                             │
│  ┌──────────────┐  ┌───────────────┐  ┌─────────────────┐  │
│  │ AdapterRegistry│  │ AuthGuardian  │  │ FederatedBudget │  │
│  │ (route tasks) │  │ (permissions) │  │ (token ceilings)│  │
│  └──────┬───────┘  └───────────────┘  └─────────────────┘  │
│         │                                                    │
│  ┌──────▼──────────────────────────────────────────────┐   │
│  │            LockedBlackboard (shared state)           │   │
│  │   propose → validate → commit  (file-system mutex)  │   │
│  └──────────────────────────────────────────────────────┘   │
│         │                                                    │
│  ┌──────▼───────────────────────────────────────────────┐  │
│  │  Adapters (plug any framework in, swap out freely)   │  │
│  │  LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │…  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           │
          HMAC-signed audit log (data/audit_log.jsonl)
```

### LockedBlackboard

The coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss.

AWESOME_LISTS.md

# Awesome List PR Submissions

Ready-to-use PR titles, one-liners, and context for each list.
Submit these as pull requests to the respective repositories.

---

## 1. awesome-mcp-servers
**Repo:** https://github.com/punkpeye/awesome-mcp-servers

**PR title:**
> Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools

**One-liner to add to the list:**
```markdown
- [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.
```

**Where to add it:** Under the orchestration or multi-agent section.

**PR body:**
> 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.

---

## 2. awesome-ai-agents
**Repo:** https://github.com/e2b-dev/awesome-ai-agents

**PR title:**
> Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems

**One-liner to add to the list:**
```markdown
- [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.
```

**PR body:**
> 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.

---

## 3. awesome-langchain
**Repo:** https://github.com/kyrolabs/awesome-langchain

**PR title:**
> Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety

**One-liner to add to the list:**
```markdown
- [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.
```

**Where to add it:** Under Tools / Agent frameworks / Orchestration.

---

## 4. awesome-

BENCHMARKS.md

# Benchmarks & Performance

> 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.

## BlackboardValidator Throughput

Layer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:

| Input size | Ops/sec | Latency |
|---|---|---|
| Small entry (~100 chars) | ~1,000,000 | < 1 µs |
| Medium entry (~1 KB) | ~500,000 | ~2 µs |
| Large entry (~10 KB) | ~159,000 | ~6 µs |

Layer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.

---

## Cloud Provider Performance

Not 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.

| Provider / Model | Avg response (5-agent swarm) | RPM limit (free/tier-1) | Notes |
|---|---|---|---|
| **OpenAI gpt-5.2** | 6–10s per call | 3–6 RPM | Flagship model, high latency, strict RPM |
| **OpenAI gpt-4o-mini** | 2–4s per call | 500 RPM | Fast, cheap, good for reviewer agents |
| **OpenAI gpt-4o** | 4–7s per call | 60–500 RPM | Balanced quality/speed |
| **Anthropic Claude 3.5 Haiku** | 2–3s per call | 50 RPM | Fastest Claude, great for parallel agents |
| **Anthropic Claude 3.7 Sonnet** | 4–8s per call | 50 RPM | Stronger reasoning, higher latency |
| **Google Gemini 2.0 Flash** | 1–3s per call | 15 RPM (free) | Very fast inference, low RPM on free tier |
| **Groq (Llama 3.3 70B)** | 0.5–2s per call | 30 RPM | Fastest cloud inference available |
| **Together AI / Fireworks** | 1–3s per call | Varies by plan | Good for parallel workloads |

**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.**

### Choosing a Model for Swarm Agents

- **Speed over depth** (many agents, real-time) → `gpt-4o-mini`, `claude-3.5-haiku`, `gemini-2.0-flash`, `groq/llama-3.3-70b`
- **Depth over speed** (few agents, high-stakes) → `gpt-4o`, `claude-3.7-sonnet`
- **Free / no-cost testing** → Groq free tier, Gemini free tier, or Ollama locally
- **Production with budget** → multiple keys across providers, route agents to different models

---

## Rate Limit Patterns

When 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).

| You have | What to expect |
|---|---|
| One cloud API key | Sequential dispatch, 40–70s per 5-agent swarm — handled automatically |
| Multiple cloud keys | Near-parallel, 10–15s —

Editorial read

Docs & README

Docs source

CLAWHUB

Editorial quality

ready

Full README

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 history:

v4.0.14 | 2026-02-28T18:59:58.541Z | auto

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.

v4.0.13 | 2026-02-28T18:48:35.783Z | auto

Version 4.0.13

Added detailed system architecture overview (ARCHITECTURE.md)
Added performance and benchmarking documentation (BENCHMARKS.md)

v4.0.12 | 2026-02-28T17:34:33.499Z | auto

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.

v4.0.11 | 2026-02-28T17:23:30.321Z | user

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.

v4.0.10 | 2026-02-28T17:12:09.694Z | user

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.

v4.0.9 | 2026-02-28T15:21:02.527Z | user

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)

v4.0.8 | 2026-02-28T14:36:29.590Z | user

Fix metadata drift: skill.json maxParallelAgents corrected to Infinity default, MCP handshake handlers added, CORS headers for Cursor/Claude Desktop, version consistency fixes

v4.0.7 | 2026-02-28T10:48:49.754Z | user

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

v4.0.6 | 2026-02-27T21:46:42.601Z | user

Fix 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

v4.0.5 | 2026-02-26T22:43:00.967Z | user

Add demos 07 & 08, unified npm run demo launcher, deterministic 10/10 scoring, debugger_agent two-pass hardening, --silent-summary mode

v4.0.4 | 2026-02-26T15:09:06.548Z | user

v4.0.4: guard adapter-registry regex against ReDoS; align skill.json resource names; all 1216 tests passing

v4.0.3 | 2026-02-26T14:50:23.342Z | auto

Updated permission wall resource types: replaced SAP_API, FINANCIAL_API, and DATA_EXPORT with abstract local resources (DATABASE, PAYMENTS, EMAIL, FILE_EXPORT).
Clarified that no external credentials are required for permission walls; all access checks are local.
Revised example permission check usage to reflect new resource types.
Documentation remains focused on agent orchestration, budget and handoff protocols, and blackboard coordination.

v4.0.2 | 2026-02-26T14:35:44.451Z | auto

No changes detected in this version.

No file or documentation changes were made for version 4.0.2.

v4.0.1 | 2026-02-26T14:13:34.430Z | auto

No user-facing changes in this release.

Version updated to 4.0.1 with no modifications detected in code or documentation.

v4.0.0 | 2026-02-26T12:40:54.960Z | auto

Network-AI 4.0.0

SKILL.md significantly streamlined: redundant sections and partial/duplicate handoff protocol instructions removed.
Core orchestration steps and agent delegation instructions clarified and made more concise.
All quick start, handoff, and agent coordination sections retained, but duplicate or incomplete text removed for clarity.
No code or file changes detected; documentation update only.

v3.9.0 | 2026-02-25T17:45:29.777Z | auto

No user-visible changes; SKILL.md remains effectively unchanged.

No file changes detected in this version.
Functionality and documentation are the same as previous release.

v3.8.0 | 2026-02-25T17:16:11.450Z | auto

No user-facing changes in this release.

Version update with no detected file or documentation changes.
All features and workflows remain the same as the previous version.

v3.7.1 | 2026-02-25T16:21:48.162Z | auto

No code or documentation changes were detected in this version.

Version 3.7.1 is functionally identical to the previous release.
No file changes were made.

v3.7.0 | 2026-02-25T15:43:36.499Z | auto

No user-visible changes in this release; no file changes detected.

v3.6.2 | 2026-02-24T16:59:04.253Z | auto

No user-facing changes in this release.

Version bump to 3.6.2 with no modifications to files or documentation.

v3.6.0 | 2026-02-24T15:31:21.013Z | auto

No user-visible changes in this release (no file changes detected).

v3.5.1 | 2026-02-23T16:40:19.873Z | auto

No user-facing changes in this version.

No file changes detected between this version and the previous release.

v3.5.0 | 2026-02-23T16:14:51.100Z | auto

Version 3.5.0 of Network-AI

No file changes detected in this release.
No user-facing updates or modifications to core features.
Behavioral, workflow, and protocol remain identical to the previous version.

v3.4.1 | 2026-02-23T15:30:26.094Z | auto

No file changes detected for version 3.4.1

No updates or changes were made to the skill in this version.
Documentation, source code, and functionality all remain unchanged from the previous release.

v3.4.0 | 2026-02-23T14:34:24.271Z | auto

No code or documentation changes detected in this version.
Skill behavior, protocols, and usage remain unchanged from the previous release.

v3.3.11 | 2026-02-22T13:10:27.067Z | auto

No user-facing or functional changes detected in this release.

No modifications were made to the skill files.
Documentation and protocols remain unchanged.
All agent orchestration, budget, and verification procedures are consistent with the previous version.

v3.3.10 | 2026-02-22T13:02:17.848Z | auto

No code or content changes; documentation was re-saved without modification.
All features, instructions, and protocols remain the same as in the previous version.

v3.3.9 | 2026-02-22T12:42:06.077Z | auto

Documentation refreshed with improved formatting and clarity; content remains functionally the same.
No code or file changes detected for this release.
Existing protocol and workflow descriptions are unchanged.

v3.3.8 | 2026-02-22T12:20:20.333Z | auto

No changes detected in version 3.3.8 (no file changes).

The skill documentation and functionality remain unchanged.
No updates or additions in this release.

v3.3.7 | 2026-02-21T22:23:23.258Z | auto

No file changes detected for this release.
Documentation was cleaned up by removing unfinished or extraneous content at the end of the SKILL.md file.
There are no functional or behavioral changes in this version.

v3.3.6 | 2026-02-21T21:22:33.048Z | auto

Removed the file: swarm-blackboard.md, simplifying the repository structure.
No changes to configuration or orchestrator protocols documented in SKILL.md.
All existing instructions and usage workflows remain unchanged.
Update reduces redundancy in documentation regarding the blackboard system.

v3.3.3 | 2026-02-20T17:38:13.843Z | user

Fix serialization crash in parallel waves, adapter failure propagation, cache abort fix + 3 working examples

v3.3.2 | 2026-02-20T09:46:48.084Z | auto

No file changes detected in this version.
No updates or modifications to the code or documentation.
Behavior and instructions remain unchanged from the previous release.

v3.3.1 | 2026-02-19T20:40:32.183Z | auto

network-ai 3.3.1

Documentation updated: SKILL.md removed duplicate or truncated instruction block from the Agent-to-Agent Handoff Protocol section.
No changes to features, APIs, or command protocols; this is a documentation cleanup release only.

v3.3.0 | 2026-02-19T20:24:42.290Z | auto

network-ai 3.3.0

Documentation updated in swarm-blackboard.md for improved clarity and usability.
No changes to code or functionality; update is documentation-only.
Streamlines orchestrator protocols and usage instructions.

v3.2.11 | 2026-02-19T15:47:30.792Z | auto

network-ai 3.2.11

Documentation updates in swarm-blackboard.md to clarify task orchestration protocols.
No changes to code or functionality.

v3.2.10 | 2026-02-19T14:37:34.407Z | user

Fix: resolve all remaining CodeQL unused-variable alerts; add word boundaries to TODO/FIXME detection pattern; dismiss false-positive alerts; clean unused imports

v3.2.9 | 2026-02-19T14:19:12.486Z | user

Fix: 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

v3.2.8 | 2026-02-18T22:33:35.354Z | user

Fix: 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

v3.2.7 | 2026-02-18T21:49:44.082Z | user

Fix: 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+)

v3.2.6 | 2026-02-18T20:04:41.440Z | user

Fix: 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

v3.2.5 | 2026-02-18T17:18:22.987Z | user

Re-publish: unstick ClawHub scanner from v3.2.4 pending state

v3.2.4 | 2026-02-18T16:27:12.783Z | user

Phase 4 partial: observability commands, governance vocabulary, competitive comparison, Pylance fixes

v3.2.2 | 2026-02-17T15:46:46.004Z | user

Re-release of v3.2.1 security patch to resolve stuck VirusTotal scan. Hardened justification scoring against prompt injection, keyword stuffing, and padding attacks.

v3.2.1 | 2026-02-17T13:45:15.429Z | user

Security patch: hardened justification scoring against prompt injection, keyword stuffing, and padding attacks. Fixed audit log integrity test isolation.

v3.2.0 | 2026-02-17T13:20:46.285Z | user

Phase 3: Priority-based conflict resolution with preemption

v3.1.3 | 2026-02-16T15:35:31.292Z | user

Fix scanner mismatches: remove node from requires.bins (bundle is Python-only), document validate_token.py in SKILL.md, sanitize capability terms

v3.1.2 | 2026-02-16T15:25:04.323Z | user

Security fix: path traversal vulnerability in blackboard.py change_id handling - blocks Unix and Windows traversal attacks

v3.1.1 | 2026-02-16T15:12:51.896Z | user

Clean bundle: .clawhubignore added, description clarified for security scan

v3.1.0 | 2026-02-16T13:46:38.498Z | user

Phase 2: Trust - structured logging, typed errors, input validation, JSDoc, audit integration

Archive index:

Archive v4.0.14: 13 files, 56363 bytes

Files: 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)

File v4.0.14:SKILL.md

name: Network-AI description: 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. metadata: openclaw: emoji: "\U0001F41D" homepage: https://github.com/jovanSAPFIONEER/Network-AI requires: bins: - python3 optional_bins: - 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. env: SWARM_TOKEN_SECRET: required: false 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." SWARM_ENCRYPTION_KEY: required: false description: "Node.js MCP server only — not used by these Python scripts. The Python blackboard does not encrypt data at rest." OPENAI_API_KEY: required: false description: "Not used by these Python scripts. Only used by the optional Node.js demo examples when running the companion npm package." privacy: audit_log: path: data/audit_log.jsonl scope: local-only 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."

Swarm Orchestrator Skill

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.

Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.

🎯 Orchestrator System Instructions

You are the Orchestrator Agent responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:

Core Responsibilities

DECOMPOSE complex prompts into 3 specialized sub-tasks
DELEGATE using the budget-aware handoff protocol
VERIFY results on the blackboard before committing
SYNTHESIZE final output only after all validations pass

Task Decomposition Protocol

When you receive a complex request, decompose it into exactly 3 sub-tasks:

┌─────────────────────────────────────────────────────────────────┐
│                     COMPLEX USER REQUEST                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  SUB-TASK 1   │   │  SUB-TASK 2   │   │  SUB-TASK 3   │
│ data_analyst  │   │ risk_assessor │   │strategy_advisor│
│    (DATA)     │   │   (VERIFY)    │   │  (RECOMMEND)  │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
                    ┌───────────────┐
                    │  SYNTHESIZE   │
                    │ orchestrator  │
                    └───────────────┘

Decomposition Template:

TASK DECOMPOSITION for: "{user_request}"

Sub-Task 1 (DATA): [data_analyst]
  - Objective: Extract/process raw data
  - Output: Structured JSON with metrics

Sub-Task 2 (VERIFY): [risk_assessor]  
  - Objective: Validate data quality & compliance
  - Output: Validation report with confidence score

Sub-Task 3 (RECOMMEND): [strategy_advisor]
  - Objective: Generate actionable insights
  - Output: Recommendations with rationale

Budget-Aware Handoff Protocol

CRITICAL: Before EVERY sessions_send, call the handoff interceptor:

# ALWAYS run this BEFORE sessions_send
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 revenue data"

Decision Logic:

IF result.allowed == true:
    → Proceed with sessions_send
    → Note tokens_spent and remaining_budget
ELSE:
    → STOP - Do NOT call sessions_send
    → Report blocked reason to user
    → Consider: reduce scope or abort task

Pre-Commit Verification Workflow

Before returning final results to the user:

# Step 1: Check all sub-task results on blackboard
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"
python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"

# Step 2: Validate each result
python {baseDir}/scripts/swarm_guard.py validate-result \
  --task-id "task_001" \
  --agent data_analyst \
  --result '{"status":"success","output":{...},"confidence":0.85}'

# Step 3: Supervisor review (checks all issues)
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"

# Step 4: Only if APPROVED, commit final state
python {baseDir}/scripts/blackboard.py write "task:001:final" \
  '{"status":"SUCCESS","output":{...}}'

Verdict Handling: | Verdict | Action | |---------|--------| | APPROVED | Commit and return results to user | | WARNING | Review issues, fix if possible, then commit | | BLOCKED | Do NOT return results. Report failure. |

When to Use This Skill

Task Delegation: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)
Parallel Execution: Run multiple agents simultaneously and synthesize results
Permission Wall: Gate access to DATABASE, PAYMENTS, EMAIL, or FILE_EXPORT operations (abstract local resource types — no external credentials required)
Shared Blackboard: Coordinate agent state via persistent markdown file

Quick Start

1. Initialize Budget (FIRST!)

Always initialize a budget before any multi-agent task:

python {baseDir}/scripts/swarm_guard.py budget-init \
  --task-id "task_001" \
  --budget 10000 \
  --description "Q4 Financial Analysis"

2. Delegate a Task to Another Session

Use OpenClaw's built-in session tools to delegate work:

sessions_list    # See available sessions/agents
sessions_send    # Send task to another session
sessions_history # Check results from delegated work

Example delegation prompt:

Use sessions_send to ask the data_analyst session to:
"Analyze Q4 revenue trends from the SAP export data and summarize key insights"

3. Check Permission Before API Access

Before accessing SAP or Financial APIs, evaluate the request:

# Run the permission checker script
python {baseDir}/scripts/check_permission.py \
  --agent "data_analyst" \
  --resource "DATABASE" \
  --justification "Need Q4 invoice data for quarterly report" \
  --scope "read:invoices"

The script will output a grant token if approved, or denial reason if rejected.

4. Use the Shared Blackboard

Read/write coordination state:

# Write to blackboard
python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'

# Read from blackboard  
python {baseDir}/scripts/blackboard.py read "task:q4_analysis"

# List all entries
python {baseDir}/scripts/blackboard.py list

Agent-to-Agent Handoff Protocol

When delegating tasks between agents/sessions:

Step 1: Initialize Budget & Check Capacity

# Initialize budget (if not already done)
python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000

# Check current status
python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"

Step 2: Identify Target Agent

sessions_list  # Find available agents

Common agent types: | Agent | Specialty | |-------|-----------| | data_analyst | Data processing, SQL, analytics | | strategy_advisor | Business strategy, recommendations | | risk_assessor | Risk analysis, compliance checks | | orchestrator | Coordination, task decomposition |

Step 3: Intercept Before Handoff (REQUIRED)

# This checks budget AND handoff limits before allowing the call
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 data" \
  --artifact  # Include if expecting output

If ALLOWED: Proceed to Step 4 If BLOCKED: Stop - do not call sessions_send

Step 4: Construct Handoff Message

Include these fields in your delegation:

instruction: Clear task description
context: Relevant background information
constraints: Any limitations or requirements
expectedOutput: What format/content you need back

Step 5: Send via sessions_send

sessions_send to data_analyst:
"[HANDOFF]
Instruction: Analyze Q4 revenue by product category
Context: Using SAP export from ./data/q4_export.csv
Constraints: Focus on top 5 categories only
Expected Output: JSON summary with category, revenue, growth_pct
[/HANDOFF]"

Step 4: Check Results

sessions_history data_analyst  # Get the response

Permission Wall (AuthGuardian)

CRITICAL: Always check permissions before accessing:

DATABASE - Internal database / data store access
PAYMENTS - Financial/payment data services
EMAIL - Email sending capability
FILE_EXPORT - Exporting data to local files

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.

Permission Evaluation Criteria

| Factor | Weight | Criteria | |--------|--------|----------| | Justification | 40% | Must explain specific task need | | Trust Level | 30% | Agent's established trust score | | Risk Assessment | 30% | Resource sensitivity + scope breadth |

Using the Permission Script

# Request permission
python {baseDir}/scripts/check_permission.py \
  --agent "your_agent_id" \
  --resource "PAYMENTS" \
  --justification "Generating quarterly financial summary for board presentation" \
  --scope "read:revenue,read:expenses"

# Output if approved:
# ✅ GRANTED
# Token: grant_a1b2c3d4e5f6
# Expires: 2026-02-04T15:30:00Z
# Restrictions: read_only, no_pii_fields, audit_required

# Output if denied:
# ❌ DENIED
# Reason: Justification is insufficient. Please provide specific task context.

Restriction Types

| Resource | Default Restrictions | |----------|---------------------| | DATABASE | read_only, max_records:100 | | PAYMENTS | read_only, no_pii_fields, audit_required | | EMAIL | rate_limit:10_per_minute | | FILE_EXPORT | anonymize_pii, local_only |

Shared Blackboard Pattern

The blackboard (swarm-blackboard.md) is a markdown file for agent coordination:

# Swarm Blackboard
Last Updated: 2026-02-04T10:30:00Z

## Knowledge Cache
### task:q4_analysis
{"status": "completed", "result": {...}, "agent": "data_analyst"}

### cache:revenue_summary  
{"q4_total": 1250000, "growth": 0.15}

Blackboard Operations

# Write with TTL (expires after 1 hour)
python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600

# Read (returns null if expired)
python {baseDir}/scripts/blackboard.py read "cache:temp_data"

# Delete
python {baseDir}/scripts/blackboard.py delete "cache:temp_data"

# Get full snapshot
python {baseDir}/scripts/blackboard.py snapshot

Parallel Execution

For tasks requiring multiple agent perspectives:

Strategy 1: Merge (Default)

Combine all agent outputs into unified result.

Ask data_analyst AND strategy_advisor to both analyze the dataset.
Merge their insights into a comprehensive report.

Strategy 2: Vote

Use when you need consensus - pick the result with highest confidence.

Strategy 3: First-Success

Use for redundancy - take first successful result.

Strategy 4: Chain

Sequential processing - output of one feeds into next.

Example Parallel Workflow

1. sessions_send to data_analyst: "Extract key metrics from Q4 data"
2. sessions_send to risk_assessor: "Identify compliance risks in Q4 data"  
3. sessions_send to strategy_advisor: "Recommend actions based on Q4 trends"
4. Wait for all responses via sessions_history
5. Synthesize: Combine metrics + risks + recommendations into executive summary

Security Considerations

Never bypass the permission wall for gated resources
Always include justification explaining the business need
Use minimal scope - request only what you need
Check token expiry - tokens are valid for 5 minutes
Validate tokens - use python {baseDir}/scripts/validate_token.py TOKEN to verify grant tokens before use
Audit trail - all permission requests are logged

📝 Audit Trail Requirements (MANDATORY)

Every sensitive action MUST be logged to data/audit_log.jsonl to maintain compliance and enable forensic analysis.

What Gets Logged Automatically

The scripts automatically log these events:

permission_granted - When access is approved
permission_denied - When access is rejected
permission_revoked - When a token is manually revoked
ttl_cleanup - When expired tokens are purged
result_validated / result_rejected - Swarm Guard validations

Log Entry Format

{
  "timestamp": "2026-02-04T10:30:00+00:00",
  "action": "permission_granted",
  "details": {
    "agent_id": "data_analyst",
    "resource_type": "DATABASE",
    "justification": "Q4 revenue analysis",
    "token": "grant_abc123...",
    "restrictions": ["read_only", "max_records:100"]
  }
}

Reading the Audit Log

# View recent entries (last 10)
tail -10 {baseDir}/data/audit_log.jsonl

# Search for specific agent
grep "data_analyst" {baseDir}/data/audit_log.jsonl

# Count actions by type
cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c

Custom Audit Entries

If you perform a sensitive action manually, log it:

import json
from datetime import datetime, timezone
from pathlib import Path

audit_file = Path("{baseDir}/data/audit_log.jsonl")
entry = {
    "timestamp": datetime.now(timezone.utc).isoformat(),
    "action": "manual_data_access",
    "details": {
        "agent": "orchestrator",
        "description": "Direct database query for debugging",
        "justification": "Investigating data sync issue #1234"
    }
}
with open(audit_file, "a") as f:
    f.write(json.dumps(entry) + "\n")

🧹 TTL Enforcement (Token Lifecycle)

Expired permission tokens are automatically tracked. Run periodic cleanup:

# Validate a grant token
python {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6

# List expired tokens (without removing)
python {baseDir}/scripts/revoke_token.py --list-expired

# Remove all expired tokens
python {baseDir}/scripts/revoke_token.py --cleanup

# Output:
# 🧹 TTL Cleanup Complete
#    Removed: 3 expired token(s)
#    Remaining active grants: 2

Best Practice: Run --cleanup at the start of each multi-agent task to ensure a clean permission state.

⚠️ Swarm Guard: Preventing Common Failures

Two critical issues can derail multi-agent swarms:

1. The Handoff Tax 💸

Problem: Agents waste tokens "talking about" work instead of doing it.

Prevention:

# Before each handoff, check your budget:
python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"

# Output:
# 🟢 Task: task_001
#    Handoffs: 1/3
#    Remaining: 2
#    Action Ratio: 100%

Rules enforced:

Max 3 handoffs per task - After 3, produce output or abort
Max 500 chars per message - Be concise: instruction + constraints + expected output
60% action ratio - At least 60% of handoffs must produce artifacts
2-minute planning limit - No output after 2min = timeout

# Record a handoff (with tax checking):
python {baseDir}/scripts/swarm_guard.py record-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze sales data, output JSON summary" \
  --artifact  # Include if this handoff produces output

2. Silent Failure Detection 👻

Problem: One agent fails silently, others keep working on bad data.

Prevention - Heartbeats:

# Agents must send heartbeats while working:
python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"

# Check if an agent is healthy:
python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst

# Output if healthy:
# 💚 Agent 'data_analyst' is HEALTHY
#    Last seen: 15s ago

# Output if failed:
# 💔 Agent 'data_analyst' is UNHEALTHY
#    Reason: STALE_HEARTBEAT
#    → Do NOT use any pending results from this agent.

Prevention - Result Validation:

# Before using another agent's result, validate it:
python {baseDir}/scripts/swarm_guard.py validate-result \
  --task-id "task_001" \
  --agent data_analyst \
  --result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'

# Output:
# ✅ RESULT VALID
#    → APPROVED - Result can be used by other agents

Required result fields: status, output, confidence

Supervisor Review

Before finalizing any task, run supervisor review:

python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"

# Output:
# ✅ SUPERVISOR VERDICT: APPROVED
#    Task: task_001
#    Age: 1.5 minutes
#    Handoffs: 2
#    Artifacts: 2

Verdicts:

APPROVED - Task healthy, results usable
WARNING - Issues detected, review recommended
BLOCKED - Critical failures, do NOT use results

Troubleshooting

Permission Denied

Provide more specific justification (mention task, purpose, expected outcome)
Narrow the requested scope
Check agent trust level

Blackboard Read Returns Null

Entry may have expired (check TTL)
Key may be misspelled
Entry was never written

Session Not Found

Run sessions_list to see available sessions
Session may need to be started first

References

AuthGuardian Details - Full permission system documentation
Blackboard Schema - Data structure specifications
Agent Trust Levels - How trust is calculated

File v4.0.14:_meta.json

{ "ownerId": "kn75j1xcebk74re38bv714kh1h81804p", "slug": "network-ai", "version": "4.0.14", "publishedAt": 1772305198541 }

File v4.0.14:ARCHITECTURE.md

Architecture

The Multi-Agent Race Condition Problem

Most 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.

The "Bank Run" scenario:

Agent A reads balance:  $10,000
Agent B reads balance:  $10,000       (same moment)
Agent A writes balance: $10,000 - $7,000 = $3,000
Agent B writes balance: $10,000 - $6,000 = $4,000   ← Agent A's write is gone

Both agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.

Without concurrency control, parallel agents will:

Corrupt shared state — two agents overwrite each other's blackboard entries
Double-spend budgets — token costs exceed limits because agents don't see each other's spending
Produce contradictory outputs — Agent A says "approved", Agent B says "denied", both write to the same key

How Network-AI prevents this:

// Atomic commit — no other agent can read/write "account:balance" during this operation
const changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');
blackboard.validateChange(changeId);   // checks for conflicts
blackboard.commitChange(changeId);     // atomic write with file-system mutex

Component Overview

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
└──────────────────────────┬──────────────────────────────────┘
                           │  createSwarmOrchestrator()
┌──────────────────────────▼──────────────────────────────────┐
│                  SwarmOrchestrator                          │
│                                                             │
│  ┌──────────────┐  ┌───────────────┐  ┌─────────────────┐  │
│  │ AdapterRegistry│  │ AuthGuardian  │  │ FederatedBudget │  │
│  │ (route tasks) │  │ (permissions) │  │ (token ceilings)│  │
│  └──────┬───────┘  └───────────────┘  └─────────────────┘  │
│         │                                                    │
│  ┌──────▼──────────────────────────────────────────────┐   │
│  │            LockedBlackboard (shared state)           │   │
│  │   propose → validate → commit  (file-system mutex)  │   │
│  └──────────────────────────────────────────────────────┘   │
│         │                                                    │
│  ┌──────▼───────────────────────────────────────────────┐  │
│  │  Adapters (plug any framework in, swap out freely)   │  │
│  │  LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │…  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           │
          HMAC-signed audit log (data/audit_log.jsonl)

LockedBlackboard

The coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss.

propose(key, value, agentId, ttl?, priority?) — stages a change, detects conflicts
validate(changeId, validatorId) — confirms no race occurred since propose
commit(changeId) — atomic write
Conflict strategies: first-commit-wins, priority-wins, last-write-wins

AuthGuardian

Permission 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.

const grant = auth.requestPermission('data_analyst', 'DATABASE', 'read',
  'Need customer order history for sales report');
// grant.token is scoped HMAC-signed token with TTL

Resource types: DATABASE (risk 0.5), PAYMENTS (0.7), EMAIL (0.4), FILE_EXPORT (0.6)

Permission scoring: justification quality 40%, agent trust level 30%, resource risk 30%. Threshold: 0.5.

FederatedBudget

Hard token ceilings per agent and per task. Even if 5 agents run in parallel, total spend cannot exceed the budget.

python scripts/swarm_guard.py budget-init   --task-id "task_001" --budget 10000
python scripts/swarm_guard.py budget-check  --task-id "task_001"
python scripts/swarm_guard.py budget-report --task-id "task_001"

AdapterRegistry

Routes tasks to the right agent/framework automatically. Register multiple adapters and the registry dispatches by agent ID.

const registry = new AdapterRegistry();
registry.register('my-langchain-agent', langchainAdapter);
registry.register('my-autogen-agent',   autogenAdapter);

FSM Journey (JourneyFSM)

The FSM governs agent phase transitions for long-running pipelines. Each phase transition is:

Gated by AuthGuardian tokens
Logged to the audit trail
Subject to timeout enforcement

IDLE → PLANNING → EXECUTING → REVIEWING → COMMITTING → COMPLETE
                                           ↓
                                       BLOCKED (on violation)

ComplianceMonitor captures violations in real-time:

TOOL_ABUSE — too many rapid writes
TURN_TAKING — consecutive actions without yield
RESPONSE_TIMEOUT — agent exceeds time budget
JOURNEY_TIMEOUT — overall pipeline exceeds wall-clock limit

Handoff Protocol

Format messages for delegation between agents:

[HANDOFF]
Instruction: Analyze monthly sales by product category
Context: Using database export from ./data/sales_export.csv
Constraints: Focus on top 5 categories only
Expected Output: JSON summary with category, revenue, growth_pct
[/HANDOFF]

Budget-aware handoff (wraps sessions_send with budget checks):

python scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 revenue data"

Output:

HANDOFF ALLOWED: orchestrator -> data_analyst
   Tokens spent: 156
   Budget remaining: 9,844
   Handoff #1 (remaining: 2)
   -> Proceed with sessions_send

Content Quality Gate

Two-layer validation before blackboard writes:

Layer 1 — BlackboardValidator (rule-based, zero LLM calls)

Hallucination detection (vague, unsupported, fabricated content)
Dangerous code detection (eval(), exec(), rm -rf)
Placeholder rejection (TODO/FIXME/stub content)
Throughput: ~500,000 ops/sec on 1 KB inputs

Layer 2 — QualityGateAgent (AI-assisted)

Async, intended for high-value writes only
Quarantine system for suspicious content
Adds LLM latency — use selectively

Agent Trust Levels

| Agent | Trust | Role | |---|---|---| | orchestrator | 0.9 | Primary coordinator | | risk_assessor | 0.85 | Compliance specialist | | data_analyst | 0.8 | Data processing | | strategy_advisor | 0.7 | Business strategy | | Unknown | 0.5 | Default |

Configure in scripts/check_permission.py:

DEFAULT_TRUST_LEVELS = {
    "orchestrator": 0.9,
    "my_new_agent": 0.75,
}
GRANT_TOKEN_TTL_MINUTES = 5

Project Structure

Network-AI/
├── index.ts                      # Core orchestrator (SwarmOrchestrator, AuthGuardian, TaskDecomposer)
├── security.ts                   # Security module (tokens, encryption, rate limiting, audit)
├── setup.ts                      # Developer setup & installation checker
├── adapters/                     # 12 plug-and-play agent framework adapters
│   ├── adapter-registry.ts       # Multi-adapter routing & discovery
│   ├── base-adapter.ts           # Abstract base class
│   ├── custom-adapter.ts         # Custom function/HTTP agent adapter
│   ├── langchain-adapter.ts
│   ├── autogen-adapter.ts
│   ├── crewai-adapter.ts
│   ├── mcp-adapter.ts
│   ├── llamaindex-adapter.ts
│   ├── semantic-kernel-adapter.ts
│   ├── openai-assistants-adapter.ts
│   ├── haystack-adapter.ts
│   ├── dspy-adapter.ts
│   ├── agno-adapter.ts
│   └── openclaw-adapter.ts
├── lib/
│   ├── locked-blackboard.ts      # Atomic commits with file-system mutexes
│   ├── blackboard-validator.ts   # Content quality gate (Layer 1 + Layer 2)
│   ├── fsm-journey.ts            # FSM state machine and compliance monitor
│   └── swarm-utils.ts            # Helper utilities
├── scripts/                      # Python helper scripts (local orchestration only)
│   ├── blackboard.py             # Shared state management with atomic commits
│   ├── swarm_guard.py            # Handoff tax prevention, budget tracking
│   ├── check_permission.py       # AuthGuardian permission checker + active grants
│   ├── validate_token.py         # Token validation
│   └── revoke_token.py           # Token revocation + TTL cleanup
├── types/
│   ├── agent-adapter.d.ts        # Universal adapter interfaces
│   └── openclaw-core.d.ts        # OpenClaw type stubs
├── references/                   # Deep-dive documentation
│   ├── adapter-system.md
│   ├── auth-guardian.md
│   ├── blackboard-schema.md
│   ├── trust-levels.md
│   └── mcp-roadmap.md
├── examples/                     # Runnable examples (01–06)
│   ├── 01-hello-swarm.ts
│   ├── 02-fsm-pipeline.ts
│   ├── 03-parallel-agents.ts
│   ├── 04-live-swarm.ts
│   └── 05-code-review-swarm.ts
└── data/
    ├── audit_log.jsonl           # HMAC-signed audit trail (local only)
    └── pending_changes/          # In-flight atomic change records

File v4.0.14:AWESOME_LISTS.md

Awesome List PR Submissions

Ready-to-use PR titles, one-liners, and context for each list. Submit these as pull requests to the respective repositories.

1. awesome-mcp-servers

Repo: https://github.com/punkpeye/awesome-mcp-servers

PR title:

Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools

One-liner to add to the list:

- [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.

Where to add it: Under the orchestration or multi-agent section.

PR body:

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.

2. awesome-ai-agents

Repo: https://github.com/e2b-dev/awesome-ai-agents

PR title:

Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems

One-liner to add to the list:

- [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.

PR body:

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.

3. awesome-langchain

Repo: https://github.com/kyrolabs/awesome-langchain

PR title:

Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety

One-liner to add to the list:

- [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.

Where to add it: Under Tools / Agent frameworks / Orchestration.

4. awesome-llamaindex

Repo: https://github.com/emptycrown/awesome-llamaindex (or the official one)

PR title:

Add network-ai — orchestration layer with LlamaIndex adapter

One-liner to add to the list:

- [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.

5. awesome-mcp (or MCP-related lists)

Search: github.com/topics/model-context-protocol

PR title:

Add network-ai — MCP server + client transport for multi-agent orchestration

One-liner:

- [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.

Submission checklist

Before each PR:

[ ] Fork the target repo
[ ] Add the one-liner in alphabetical order by tool name within its section
[ ] PR title follows the repo's existing convention (check other recent PRs)
[ ] Verify the repo's README or CONTRIBUTING.md for any format requirements
[ ] Star the repo before submitting (improves PR acceptance rate)

Other lists to check

https://github.com/jim-schwoebel/awesome-ai-frameworks
https://github.com/AgentOps-AI/agentops (list of frameworks)
https://github.com/topics/ai-agents (GitHub topic — add ai-agents to repo if not there)
Product Hunt — "AI Developer Tools" category launch

File v4.0.14:BENCHMARKS.md

Benchmarks & Performance

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.

BlackboardValidator Throughput

Layer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:

| Input size | Ops/sec | Latency | |---|---|---| | Small entry (~100 chars) | ~1,000,000 | < 1 µs | | Medium entry (~1 KB) | ~500,000 | ~2 µs | | Large entry (~10 KB) | ~159,000 | ~6 µs |

Layer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.

Cloud Provider Performance

Not 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.

| Provider / Model | Avg response (5-agent swarm) | RPM limit (free/tier-1) | Notes | |---|---|---|---| | OpenAI gpt-5.2 | 6–10s per call | 3–6 RPM | Flagship model, high latency, strict RPM | | OpenAI gpt-4o-mini | 2–4s per call | 500 RPM | Fast, cheap, good for reviewer agents | | OpenAI gpt-4o | 4–7s per call | 60–500 RPM | Balanced quality/speed | | Anthropic Claude 3.5 Haiku | 2–3s per call | 50 RPM | Fastest Claude, great for parallel agents | | Anthropic Claude 3.7 Sonnet | 4–8s per call | 50 RPM | Stronger reasoning, higher latency | | Google Gemini 2.0 Flash | 1–3s per call | 15 RPM (free) | Very fast inference, low RPM on free tier | | Groq (Llama 3.3 70B) | 0.5–2s per call | 30 RPM | Fastest cloud inference available | | Together AI / Fireworks | 1–3s per call | Varies by plan | Good for parallel workloads |

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.

Choosing a Model for Swarm Agents

Speed over depth (many agents, real-time) → gpt-4o-mini, claude-3.5-haiku, gemini-2.0-flash, groq/llama-3.3-70b
Depth over speed (few agents, high-stakes) → gpt-4o, claude-3.7-sonnet
Free / no-cost testing → Groq free tier, Gemini free tier, or Ollama locally
Production with budget → multiple keys across providers, route agents to different models

Rate Limit Patterns

When 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).

| You have | What to expect | |---|---| | One cloud API key | Sequential dispatch, 40–70s per 5-agent swarm — handled automatically | | Multiple cloud keys | Near-parallel, 10–15s — one key per adapter instance | | Local GPU (Ollama, vLLM) | True parallel, 5–20s depending on hardware | | Home GPU + cloud mix | Local agents never block — cloud agents rate-paced independently |

Multiple Keys = True Parallel

import { CustomAdapter, AdapterRegistry } from 'network-ai';

const registry = new AdapterRegistry();

for (const reviewer of REVIEWERS) {
  const adapter = new CustomAdapter();
  const client  = new OpenAI({ apiKey: process.env[`OPENAI_KEY_${reviewer.id.toUpperCase()}`] });

  adapter.registerHandler(reviewer.id, async (payload) => {
    const resp = await client.chat.completions.create({ /* ... */ });
    return { findings: extractContent(resp) };
  });

  registry.register(reviewer.id, adapter);
}

// All 5 dispatch in parallel via Promise.all — ~8–12s instead of ~60s

Local GPU = Zero Rate Limits

const localClient = new OpenAI({
  apiKey : 'not-needed',
  baseURL: 'http://localhost:11434/v1',   // Ollama, vLLM, llama.cpp
});

adapter.registerHandler('reviewer', async (payload) => {
  const resp = await localClient.chat.completions.create({
    model   : 'llama3.2',
    messages: [/* ... */],
  });
  return { findings: extractContent(resp) };
});

Cloud GPU Instances (Self-Hosted)

Running your own model on AWS / GCP / Azure sits between managed APIs and local hardware:

| Setup | Speed vs managed API | RPM | |---|---|---| | A100 (80GB) + vLLM, Llama 3.3 70B | Faster — 0.5–2s/call | None | | H100 + vLLM, Mixtral 8x7B | Faster — 0.3–1s/call | None | | T4 / V100 + Ollama, Llama 3.2 8B | Comparable | None |

Cost: $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.

`max_completion_tokens` — The Silent Truncation Trap

One 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".

This is especially dangerous for code-rewrite agents where the output is a full file.

# Real numbers (gpt-5-mini, order-service.ts rewrite):
  Blockers section:  ~120 tokens
  Fixed code:        ~2,800 tokens  (213 lines with // FIX: comments)
  Total needed:      ~3,000 tokens  ← hits the cap exactly → empty output
  Fix: set to 16,000 → full rewrite delivered in one shot

Rule of Thumb by Task

| Task | Recommended cap | |---|---| | Short classification / sentiment | 200–500 | | Code review findings (one reviewer) | 400–800 | | Blocker summary (coordinator) | 500–1,000 | | Full file rewrite (≤300 lines) | 12,000–16,000 | | Full file rewrite (≤1,000 lines) | 32,000–64,000 | | Document / design revision | 16,000–32,000 |

All GPT-5 variants support 128,000 max output tokens — the ceiling is never the model, it is always the cap you set.

Lessons from Building the Code-Review Swarm

| Issue | Root cause | Fix | |---|---|---| | Fixed code output was empty | max_completion_tokens: 3000 too low | Raise to 16000+ for any code-output agent | | finish_reason: "length" silently discards | Model hits cap, partial response, no error | Always check choices[0].finish_reason and alert on "length" | | Flagship model slow + expensive for reviewers | High latency + $14/1M output tokens | Use gpt-5-mini ($2/1M, same RPM) for reviewer/fixer agents | | Coordinator + fixer as two calls | Second call hits rate limit window, +60s | Merge into one structured two-section call |

File v4.0.14:INTEGRATION_GUIDE.md

Network-AI Integration Guide

For technical leads, solutions architects, and engineering teams evaluating or deploying Network-AI in a production environment.

This guide walks from "we want this" to "it's running in production" — covering discovery, framework mapping, phased rollout, enterprise concerns, and validation.

Before You Start — Discovery
Framework Mapping
Primitive Mapping — What Solves What
Phased Rollout
Enterprise Concerns
Architecture Patterns
Validation Checklist
Common Integration Mistakes

1. Before You Start — Discovery

Before touching any code, answer these questions. They determine which adapters you need and which governance primitives are non-negotiable.

1.1 Agent Inventory

Document every AI agent or automated process your team currently runs:

| Agent / Process | Language | Framework | Shares State With | Writes To | |----------------|----------|-----------|-------------------|-----------| | e.g. "invoice classifier" | Python | LangChain | "approvals bot" | Postgres | | e.g. "customer triage" | Node | AutoGen | "CRM writer" | Salesforce API |

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.

1.2 Race Condition Audit

For each pair of agents that write to the same resource, ask:

Can both agents run at the same time?
What happens if Agent A's write is overwritten by Agent B before Agent A reads it back?
Is there any locking or retry logic today?

If the answer to the first question is "yes" and the second is "data loss / wrong decision / double spend" — that's a LockedBlackboard candidate.

1.3 Budget and Cost Exposure

Do you have per-agent token limits today?
Can a single runaway agent exhaust your OpenAI / Anthropic budget?
Do you have hard cut-offs or just alerts?

Network-AI's FederatedBudget enforces hard ceilings. If you have no ceiling today, this is your first priority.

1.4 Compliance and Audit Requirements

Does your industry require audit trails for automated decisions (GDPR, SOC 2, HIPAA, PCI-DSS)?
Do you need to prove which agent made which decision and when?
Are there regulatory rules about which systems an AI agent may access?

Answers drive AuthGuardian configuration and audit log retention policy.

2. Framework Mapping

Network-AI ships 12 adapters. Map your existing agents to the right one:

| Your Stack | Network-AI Adapter | Notes | |-----------|-------------------|-------| | LangChain (JS/TS) | LangChainAdapter | Supports Runnables, chains, agents | | AutoGen / AG2 | AutoGenAdapter | Supports .run() and .generateReply() | | CrewAI | CrewAIAdapter | Individual agents and full crew objects | | OpenAI Assistants | OpenAIAssistantsAdapter | Thread management included | | LlamaIndex | LlamaIndexAdapter | Query engines, chat engines, agent runners | | Semantic Kernel | SemanticKernelAdapter | Microsoft SK kernels, functions, planners | | Haystack | HaystackAdapter | Pipelines, agents, components | | DSPy | DSPyAdapter | Modules, programs, predictors | | Agno (ex-Phidata) | AgnoAdapter | Agents, teams, functions | | MCP tools | McpAdapter | Tool serving and discovery | | OpenClaw / Clawdbot / Moltbot | OpenClawAdapter | Native skill execution via callSkill | | Anything else | CustomAdapter | Wrap any async function or HTTP endpoint |

No matching framework?

Use CustomAdapter. Any async function becomes a governed agent in three lines:

import { CustomAdapter } from 'network-ai';

const adapter = new CustomAdapter();
adapter.registerHandler('my-agent', async (payload) => {
  // your existing logic here — unchanged
  return { result: '...' };
});

This is the recommended entry point for legacy systems, internal microservices, and REST APIs — you do not need to rewrite anything.

3. Primitive Mapping — What Solves What

Match your problem to the Network-AI primitive:

| Problem | Primitive | How | |---------|-----------|-----| | Two agents overwriting each other's data | LockedBlackboard | Atomic propose → validate → commit with file-system mutex | | Agent overspending token budget | FederatedBudget | Per-agent ceiling; hard cut-off on overspend | | Agent accessing a resource it shouldn't | AuthGuardian + SecureTokenManager | HMAC-signed scoped tokens required at every sensitive operation | | No audit trail for automated decisions | Audit log (data/audit_log.jsonl) | Cryptographic HMAC-signed chain, every write recorded | | Agent running out of turn / taking too many actions | ComplianceMonitor | TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT detected in real time | | Workflow needs defined states (e.g. INTAKE → REVIEW → APPROVE) | JourneyFSM | State machine gates which agents may act in which states | | Content safety / hallucination in agent outputs | QualityGateAgent + BlackboardValidator | Two-layer validation before output enters the blackboard | | Race conditions in parallel agent writes | LockedBlackboard with priority-wins | Higher-priority agents preempt lower-priority writes on conflict | | Need to expose all tools to an AI via MCP | McpSseServer + network-ai-server | HTTP/SSE server at GET /sse, POST /mcp, GET /tools | | Runtime AI control of the orchestrator | ControlMcpTools | AI can read/set config, spawn/stop agents, drive FSM transitions |

4. Phased Rollout

Do not try to enable everything at once. This is the recommended sequence for a zero-disruption integration:

Phase 1 — Wrap (Day 1–3)

Goal: Get your existing agents running inside Network-AI without changing their behaviour.

npm install network-ai
Wrap each agent in the matching adapter (see §2)
Register all adapters with AdapterRegistry
Replace direct agent calls with registry.executeAgent(...) or orchestrator.execute(...)
Run npm run demo -- --08 to verify the framework itself is healthy in your environment

Nothing changes behaviourally yet. This phase is purely structural.

import { createSwarmOrchestrator, CustomAdapter } from 'network-ai';

const orchestrator = createSwarmOrchestrator({ swarmName: 'acme-swarm' });
const adapter = new CustomAdapter();

// Wrap your existing function — unchanged
adapter.registerHandler('invoice-classifier', async (payload) => {
  return await yourExistingClassifier(payload.params);
});

await orchestrator.addAdapter(adapter);

Phase 2 — Shared State (Day 3–7)

Goal: Replace ad-hoc shared resources (databases, files, in-memory objects) with the blackboard.

Identify all keys agents share (from your §1.1 audit)
Introduce SharedBlackboard for low-contention data
Introduce LockedBlackboard for any key that two or more agents write to concurrently

import { LockedBlackboard } from 'network-ai';

const board = new LockedBlackboard('.', { conflictResolution: 'priority-wins' });

// Atomic write — no other agent can interfere during this operation
const changeId = board.proposeChange('account:balance', newBalance, 'payment-agent');
board.validateChange(changeId);
board.commitChange(changeId);

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.

Phase 3 — Budget Enforcement (Day 7–10)

Goal: Add hard token ceilings so no single agent can exhaust your LLM budget.

import { FederatedBudget } from 'network-ai/lib/federated-budget';

const budget = new FederatedBudget({
  pools: {
    'classifier':   { ceiling: 50_000  },  // tokens per run
    'summarizer':   { ceiling: 100_000 },
    'orchestrator': { ceiling: 200_000 },
  }
});

// Check before each LLM call
const check = budget.canSpend('classifier', estimatedTokens);
if (!check.allowed) throw new Error(`Budget ceiling reached: ${check.reason}`);

// Record actual spend after
budget.recordSpend('classifier', actualTokens);

Map your cost centers to pool names. Budget state persists across agent runs.

Phase 4 — Access Control (Day 10–14)

Goal: Gate access to sensitive APIs and resources behind cryptographically signed tokens.

Define your resources and risk levels (see references/auth-guardian.md)
Map your agents to trust levels (see references/trust-levels.md)
Replace direct API calls with AuthGuardian-gated calls

import { AuthGuardian, SecureTokenManager } from 'network-ai';

const guardian = new AuthGuardian();
const tokenManager = new SecureTokenManager(process.env.HMAC_SECRET!);

// Agent requests access with a justification
const request = await guardian.requestPermission({
  agentId: 'payment-agent',
  resource: 'PAYMENTS',
  action: 'write',
  justification: 'Processing approved invoice #INV-2847 per workflow step 3',
  trustLevel: 0.8,
});

if (request.approved) {
  const token = tokenManager.createToken('payment-agent', ['PAYMENTS:write'], 300);
  // pass token to downstream call
}

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.

Phase 5 — Governance and FSM (Day 14–21)

Goal: Define explicit workflow states so agents can only act when the system is in the right state.

import { JourneyFSM, WORKFLOW_STATES } from 'network-ai';

const fsm = new JourneyFSM({
  agentId: 'workflow',
  journeyId: 'invoice-processing',
  transitions: [
    { from: 'INTAKE',   to: 'ANALYZE',  allowedAgents: ['intake-agent']  },
    { from: 'ANALYZE',  to: 'APPROVE',  allowedAgents: ['analyst-agent'] },
    { from: 'APPROVE',  to: 'EXECUTE',  allowedAgents: ['approver-agent'] },
    { from: 'EXECUTE',  to: 'DELIVER',  allowedAgents: ['payment-agent'] },
  ]
});

// Before any agent acts, check the FSM
const canAct = fsm.canTransition(currentState, nextState, agentId);

Add ComplianceMonitor to detect violations in real time without blocking the main thread:

import { ComplianceMonitor } from 'network-ai';

const monitor = new ComplianceMonitor(fsm, {
  maxActionsPerTurn: 5,
  responseTimeoutMs: 30_000,
  journeyTimeoutMs: 300_000,
});
monitor.start(1_000); // poll every second

Phase 6 — Observability and MCP (Day 21+)

Goal: Expose everything to your monitoring stack and optionally give your AI models control-plane access.

Start the MCP server (exposes 20+ tools via SSE/JSON-RPC):

npx network-ai-server --port 3001 --audit-log data/audit_log.jsonl --ceiling 500000

Connect your AI model to http://localhost:3001/sse — it can now:

Read and write live config (config_get, config_set)
Spawn and stop agents (agent_spawn, agent_stop)
Drive FSM transitions (fsm_transition)
Query the audit log (audit_query, audit_tail)
Check and top up budgets (budget_status, budget_spend)

5. Enterprise Concerns

Authentication & IAM

Network-AI does not require or replace an external IAM system. AuthGuardian operates as a pre-authorization layer:

AI Agent → AuthGuardian (justification scoring) → your IAM (final auth) → resource

The 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).

Audit Log Retention

The 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.

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.
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.
SIEM integration: Stream audit_log.jsonl to Splunk, Datadog, or Elastic via the audit_tail MCP tool or a simple tail -F feed.

Air-Gapped / On-Prem Deployment

Network-AI has zero required external network calls. All operations (blackboard, FSM, compliance, budget, tokens, audit) run entirely on-premises:

No telemetry, no call-home, no cloud dependency
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
The MCP server (network-ai-server) binds to localhost by default; deploy behind your internal API gateway to expose it to your agent fleet

Multi-Tenant Deployments

Isolate tenants by:

Separate blackboard roots — each tenant gets their own directory path passed to LockedBlackboard(tenantPath)
Separate budget pools — prefix pool names with tenant ID: tenant-abc:classifier
Separate HMAC secrets — one SecureTokenManager instance per tenant
Namespace scoping — use consistent key prefixes in the blackboard (e.g. tenant-abc:invoice:42)

Scaling

Network-AI is a single-process orchestrator by design — it does not require a broker, queue, or service mesh. For horizontal scaling:

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.
Independent budget tracking: Each instance tracks its own pool. Use a sidecar or the audit_tail MCP tool to aggregate spend across instances.
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.

6. Architecture Patterns

Pattern A — Sidecar (Minimal Disruption)

Keep your existing agent orchestration. Add Network-AI only for coordination, safety, and audit on the shared state layer.

[Existing LangChain agent] ──writes──▶ [LockedBlackboard] ◀──reads── [Existing AutoGen agent]
                                              │
                                       [Audit log]
                                       [Budget tracking]

No changes to your agent code. Network-AI wraps the shared resource only.

Pattern B — Full Orchestrator

Network-AI owns the entire agent lifecycle. All agents run through the adapter registry.

User request
     │
     ▼
SwarmOrchestrator
     │
     ├──▶ AuthGuardian (permission check)
     ├──▶ JourneyFSM (state gate)
     ├──▶ FederatedBudget (cost check)
     │
     ├──▶ LangChainAdapter ──▶ your LangChain agent
     ├──▶ AutoGenAdapter   ──▶ your AutoGen agent
     └──▶ CustomAdapter    ──▶ your existing functions

Pattern C — MCP Control Plane

Your AI model connects to network-ai-server via SSE and drives the whole system through MCP tools — no hand-coded orchestration logic at all.

AI Model (Claude / GPT-4o)
     │  SSE/JSON-RPC
     ▼
network-ai-server (port 3001)
     │
     ├── ControlMcpTools   (spawn agents, drive FSM, set config)
     ├── ExtendedMcpTools  (budget, tokens, audit)
     └── BlackboardMCPTools (read/write blackboard)

7. Validation Checklist

Run these before declaring the integration production-ready:

Functional

[ ] All agents execute via the adapter registry without errors
[ ] npx ts-node test-standalone.ts — 79 core tests pass
[ ] npx ts-node test-security.ts — 33 security tests pass
[ ] npx ts-node test-adapters.ts — 139 adapter tests pass
[ ] npx ts-node test-phase4.ts — 147 behavioral tests pass
[ ] npm run demo -- --08 runs to completion in < 10 seconds

Race Condition Safety

[ ] Two agents can write to the same blackboard key concurrently without data loss
[ ] LockedBlackboard.validateChange() rejects a stale change after a conflict
[ ] priority-wins correctly overwrites a lower-priority pending write

Budget Enforcement

[ ] Spending past the ceiling throws / returns allowed: false
[ ] Budget state persists across process restart
[ ] Per-agent pools are independent (overspending in pool A does not affect pool B)

Access Control

[ ] A token issued by SecureTokenManager validates correctly
[ ] An expired token is rejected
[ ] A token with insufficient scope is rejected at the AuthGuardian gate
[ ] --active-grants shows the correct active token set

Compliance

[ ] ComplianceMonitor fires TOOL_ABUSE after the configured action threshold
[ ] RESPONSE_TIMEOUT fires when an agent exceeds the timeout window
[ ] JOURNEY_TIMEOUT fires when the overall journey exceeds its ceiling
[ ] FSM blocks a transition attempted by an unauthorized agent

Audit

[ ] Every blackboard write produces a signed entry in audit_log.jsonl
[ ] audit_query returns filtered results correctly
[ ] The audit chain signature is intact after N entries (run the chain verifier)

8. Common Integration Mistakes

| Mistake | Consequence | Fix | |---------|-------------|-----| | Using SharedBlackboard for concurrent writes | Race conditions / data loss | Use LockedBlackboard for any key two agents write to | | Not committing the lock file (package-lock.json) | CI npm ci fails on Node version mismatch | Always commit package-lock.json after version bumps | | 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 | | 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 | | One FederatedBudget pool shared by all agents | One runaway agent exhausts budget for everyone | One pool per agent or per role | | FSM with no timeout | Stuck workflow holds locks indefinitely | Always set timeoutMs on states that involve external calls | | Storing PII as blackboard keys | Audit log contains PII in plain text | Use pseudonymised keys; store PII in a separate encrypted store | | 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 |

Show HN: Network-AI — Multi-Agent Race Condition Prevention for TypeScript

Post title:

Show HN: Network-AI – plug-and-play orchestrator that prevents race conditions when AI agents share state

Body

I 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.

Most agent frameworks give you parallelism. None of them give you coordination safety.

The classic failure:

Agent A reads balance:  $10,000
Agent B reads balance:  $10,000       ← same moment
Agent A writes balance: $3,000        ← deducts $7,000
Agent B writes balance: $4,000        ← deducts $6,000, ignoring Agent A's write

Both agents believed they had $10,000. Both spent from it. You now have a $3,000 error with no trace of what happened.

This 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.

What Network-AI does:

Atomic blackboard — propose → validate → commit with file-system mutex. No two agents can write to the same key simultaneously.
Priority preemption — if two agents conflict, the higher-priority write wins deterministically (not "last write wins" chaos)
FSM governance — agents can only act when the workflow is in the right state
FederatedBudget — per-agent token ceilings with hard cut-off. One runaway agent cannot exhaust your OpenAI bill.
ComplianceMonitor — detects TOOL_ABUSE, turn-taking violations, response timeouts, journey timeouts in real time
12 framework adapters — LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and a CustomAdapter for anything else

You can see the whole thing in 2 seconds with no API key:

git clone https://github.com/jovanSAPFIONEER/Network-AI
cd Network-AI
npm install
npm run demo -- --08

This runs the control-plane stress demo: atomic commits, priority preemption, FSM timeout, and 17 live compliance violations — all in ~2 seconds, no LLM calls.

Or the full AI showcase (needs OPENAI_API_KEY):

npm run demo -- --07

8-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.

Stack: TypeScript, Node.js 18+. Zero required external services. Works on-prem, air-gapped, or cloud.

Repo: https://github.com/jovanSAPFIONEER/Network-AI
npm: npm install network-ai
MCP server: npx network-ai-server --port 3001

Happy to answer questions about the coordination model, the FSM design, or how the atomic commits work.

Timing notes

Post on a Tuesday or Wednesday between 9–11am ET — peak HN traffic window
Tag: Show HN
Do not post the same week as a major AI framework release (it will get buried)
Have the demo commands ready to paste in the comments — someone will ask immediately

Expected comment threads to prepare for

"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).
"Does this work with Python?" → Python scripts are included (scripts/), TypeScript is the orchestration layer
"What's the performance overhead of the file-system mutex?" → microseconds for local; designed for workloads where LLM latency (100ms–10s) dominates
"Is this production-ready?" → MIT, 1,200+ tests, CodeQL + OpenSSF Scorecard on CI, 2,500+ weekly npm downloads at 24 days old

File v4.0.14:requirements.txt

Python dependencies for Swarm Orchestrator Skill

Install: pip install -r requirements.txt

Core dependencies (all optional - stdlib works on Unix)

filelock>=3.0.0 # Cross-platform file locking (recommended for Windows)

Note: The blackboard uses fcntl on Unix (built-in) with fallback for Windows.

For production Windows deployments, uncomment filelock above.

If you want to run type checking:

mypy>=1.0.0

If you want to run tests:

pytest>=7.0.0

Archive v4.0.13: 13 files, 56286 bytes

File v4.0.13:SKILL.md

name: Network-AI description: 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. metadata: openclaw: emoji: "\U0001F41D" homepage: https://github.com/jovanSAPFIONEER/Network-AI requires: bins: - python3 optional_bins: - 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. env: SWARM_TOKEN_SECRET: required: false description: "HMAC secret for AuthGuardian tokens. Auto-generated per process if not set (ephemeral)." SWARM_ENCRYPTION_KEY: required: false description: "AES-256 key for blackboard encryption. Auto-generated per process if not set." OPENAI_API_KEY: required: false description: "Only used by optional demo examples (07-full-showcase.ts) and the setup wizard. Not required for the core orchestrator or MCP server." privacy: audit_log: path: data/audit_log.jsonl scope: local-only 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."

Swarm Orchestrator Skill

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.

Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.

🎯 Orchestrator System Instructions

You are the Orchestrator Agent responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:

Core Responsibilities

DECOMPOSE complex prompts into 3 specialized sub-tasks
DELEGATE using the budget-aware handoff protocol
VERIFY results on the blackboard before committing
SYNTHESIZE final output only after all validations pass

Task Decomposition Protocol

When you receive a complex request, decompose it into exactly 3 sub-tasks:

┌─────────────────────────────────────────────────────────────────┐
│                     COMPLEX USER REQUEST                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  SUB-TASK 1   │   │  SUB-TASK 2   │   │  SUB-TASK 3   │
│ data_analyst  │   │ risk_assessor │   │strategy_advisor│
│    (DATA)     │   │   (VERIFY)    │   │  (RECOMMEND)  │
└───────────────┘   └───────────────┘   └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
                    ┌───────────────┐
                    │  SYNTHESIZE   │
                    │ orchestrator  │
                    └───────────────┘

Decomposition Template:

TASK DECOMPOSITION for: "{user_request}"

Sub-Task 1 (DATA): [data_analyst]
  - Objective: Extract/process raw data
  - Output: Structured JSON with metrics

Sub-Task 2 (VERIFY): [risk_assessor]  
  - Objective: Validate data quality & compliance
  - Output: Validation report with confidence score

Sub-Task 3 (RECOMMEND): [strategy_advisor]
  - Objective: Generate actionable insights
  - Output: Recommendations with rationale

Budget-Aware Handoff Protocol

CRITICAL: Before EVERY sessions_send, call the handoff interceptor:

# ALWAYS run this BEFORE sessions_send
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 revenue data"

Decision Logic:

IF result.allowed == true:
    → Proceed with sessions_send
    → Note tokens_spent and remaining_budget
ELSE:
    → STOP - Do NOT call sessions_send
    → Report blocked reason to user
    → Consider: reduce scope or abort task

Pre-Commit Verification Workflow

Before returning final results to the user:

# Step 1: Check all sub-task results on blackboard
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"
python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"

# Step 2: Validate each result
python {baseDir}/scripts/swarm_guard.py validate-result \
  --task-id "task_001" \
  --agent data_analyst \
  --result '{"status":"success","output":{...},"confidence":0.85}'

# Step 3: Supervisor review (checks all issues)
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"

# Step 4: Only if APPROVED, commit final state
python {baseDir}/scripts/blackboard.py write "task:001:final" \
  '{"status":"SUCCESS","output":{...}}'

When to Use This Skill

Task Delegation: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)
Parallel Execution: Run multiple agents simultaneously and synthesize results
Permission Wall: Gate access to DATABASE, PAYMENTS, EMAIL, or FILE_EXPORT operations (abstract local resource types — no external credentials required)
Shared Blackboard: Coordinate agent state via persistent markdown file

Quick Start

1. Initialize Budget (FIRST!)

Always initialize a budget before any multi-agent task:

python {baseDir}/scripts/swarm_guard.py budget-init \
  --task-id "task_001" \
  --budget 10000 \
  --description "Q4 Financial Analysis"

2. Delegate a Task to Another Session

Use OpenClaw's built-in session tools to delegate work:

sessions_list    # See available sessions/agents
sessions_send    # Send task to another session
sessions_history # Check results from delegated work

Example delegation prompt:

Use sessions_send to ask the data_analyst session to:
"Analyze Q4 revenue trends from the SAP export data and summarize key insights"

3. Check Permission Before API Access

Before accessing SAP or Financial APIs, evaluate the request:

# Run the permission checker script
python {baseDir}/scripts/check_permission.py \
  --agent "data_analyst" \
  --resource "DATABASE" \
  --justification "Need Q4 invoice data for quarterly report" \
  --scope "read:invoices"

The script will output a grant token if approved, or denial reason if rejected.

4. Use the Shared Blackboard

Read/write coordination state:

# Write to blackboard
python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'

# Read from blackboard  
python {baseDir}/scripts/blackboard.py read "task:q4_analysis"

# List all entries
python {baseDir}/scripts/blackboard.py list

Agent-to-Agent Handoff Protocol

When delegating tasks between agents/sessions:

Step 1: Initialize Budget & Check Capacity

# Initialize budget (if not already done)
python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000

# Check current status
python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"

Step 2: Identify Target Agent

sessions_list  # Find available agents

Step 3: Intercept Before Handoff (REQUIRED)

# This checks budget AND handoff limits before allowing the call
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 data" \
  --artifact  # Include if expecting output

If ALLOWED: Proceed to Step 4 If BLOCKED: Stop - do not call sessions_send

Step 4: Construct Handoff Message

Include these fields in your delegation:

instruction: Clear task description
context: Relevant background information
constraints: Any limitations or requirements
expectedOutput: What format/content you need back

Step 5: Send via sessions_send

sessions_send to data_analyst:
"[HANDOFF]
Instruction: Analyze Q4 revenue by product category
Context: Using SAP export from ./data/q4_export.csv
Constraints: Focus on top 5 categories only
Expected Output: JSON summary with category, revenue, growth_pct
[/HANDOFF]"

Step 4: Check Results

sessions_history data_analyst  # Get the response

Permission Wall (AuthGuardian)

CRITICAL: Always check permissions before accessing:

DATABASE - Internal database / data store access
PAYMENTS - Financial/payment data services
EMAIL - Email sending capability
FILE_EXPORT - Exporting data to local files

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.

Permission Evaluation Criteria

Using the Permission Script

# Request permission
python {baseDir}/scripts/check_permission.py \
  --agent "your_agent_id" \
  --resource "PAYMENTS" \
  --justification "Generating quarterly financial summary for board presentation" \
  --scope "read:revenue,read:expenses"

# Output if approved:
# ✅ GRANTED
# Token: grant_a1b2c3d4e5f6
# Expires: 2026-02-04T15:30:00Z
# Restrictions: read_only, no_pii_fields, audit_required

# Output if denied:
# ❌ DENIED
# Reason: Justification is insufficient. Please provide specific task context.

Restriction Types

Shared Blackboard Pattern

The blackboard (swarm-blackboard.md) is a markdown file for agent coordination:

# Swarm Blackboard
Last Updated: 2026-02-04T10:30:00Z

## Knowledge Cache
### task:q4_analysis
{"status": "completed", "result": {...}, "agent": "data_analyst"}

### cache:revenue_summary  
{"q4_total": 1250000, "growth": 0.15}

Blackboard Operations

# Write with TTL (expires after 1 hour)
python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600

# Read (returns null if expired)
python {baseDir}/scripts/blackboard.py read "cache:temp_data"

# Delete
python {baseDir}/scripts/blackboard.py delete "cache:temp_data"

# Get full snapshot
python {baseDir}/scripts/blackboard.py snapshot

Parallel Execution

For tasks requiring multiple agent perspectives:

Strategy 1: Merge (Default)

Combine all agent outputs into unified result.

Ask data_analyst AND strategy_advisor to both analyze the dataset.
Merge their insights into a comprehensive report.

Strategy 2: Vote

Use when you need consensus - pick the result with highest confidence.

Strategy 3: First-Success

Use for redundancy - take first successful result.

Strategy 4: Chain

Sequential processing - output of one feeds into next.

Example Parallel Workflow

1. sessions_send to data_analyst: "Extract key metrics from Q4 data"
2. sessions_send to risk_assessor: "Identify compliance risks in Q4 data"  
3. sessions_send to strategy_advisor: "Recommend actions based on Q4 trends"
4. Wait for all responses via sessions_history
5. Synthesize: Combine metrics + risks + recommendations into executive summary

Security Considerations

Never bypass the permission wall for gated resources
Always include justification explaining the business need
Use minimal scope - request only what you need
Check token expiry - tokens are valid for 5 minutes
Validate tokens - use python {baseDir}/scripts/validate_token.py TOKEN to verify grant tokens before use
Audit trail - all permission requests are logged

📝 Audit Trail Requirements (MANDATORY)

Every sensitive action MUST be logged to data/audit_log.jsonl to maintain compliance and enable forensic analysis.

What Gets Logged Automatically

The scripts automatically log these events:

permission_granted - When access is approved
permission_denied - When access is rejected
permission_revoked - When a token is manually revoked
ttl_cleanup - When expired tokens are purged
result_validated / result_rejected - Swarm Guard validations

Log Entry Format

{
  "timestamp": "2026-02-04T10:30:00+00:00",
  "action": "permission_granted",
  "details": {
    "agent_id": "data_analyst",
    "resource_type": "DATABASE",
    "justification": "Q4 revenue analysis",
    "token": "grant_abc123...",
    "restrictions": ["read_only", "max_records:100"]
  }
}

Reading the Audit Log

# View recent entries (last 10)
tail -10 {baseDir}/data/audit_log.jsonl

# Search for specific agent
grep "data_analyst" {baseDir}/data/audit_log.jsonl

# Count actions by type
cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c

Custom Audit Entries

If you perform a sensitive action manually, log it:

import json
from datetime import datetime, timezone
from pathlib import Path

audit_file = Path("{baseDir}/data/audit_log.jsonl")
entry = {
    "timestamp": datetime.now(timezone.utc).isoformat(),
    "action": "manual_data_access",
    "details": {
        "agent": "orchestrator",
        "description": "Direct database query for debugging",
        "justification": "Investigating data sync issue #1234"
    }
}
with open(audit_file, "a") as f:
    f.write(json.dumps(entry) + "\n")

🧹 TTL Enforcement (Token Lifecycle)

Expired permission tokens are automatically tracked. Run periodic cleanup:

# Validate a grant token
python {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6

# List expired tokens (without removing)
python {baseDir}/scripts/revoke_token.py --list-expired

# Remove all expired tokens
python {baseDir}/scripts/revoke_token.py --cleanup

# Output:
# 🧹 TTL Cleanup Complete
#    Removed: 3 expired token(s)
#    Remaining active grants: 2

Best Practice: Run --cleanup at the start of each multi-agent task to ensure a clean permission state.

⚠️ Swarm Guard: Preventing Common Failures

Two critical issues can derail multi-agent swarms:

1. The Handoff Tax 💸

Problem: Agents waste tokens "talking about" work instead of doing it.

Prevention:

# Before each handoff, check your budget:
python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"

# Output:
# 🟢 Task: task_001
#    Handoffs: 1/3
#    Remaining: 2
#    Action Ratio: 100%

Rules enforced:

Max 3 handoffs per task - After 3, produce output or abort
Max 500 chars per message - Be concise: instruction + constraints + expected output
60% action ratio - At least 60% of handoffs must produce artifacts
2-minute planning limit - No output after 2min = timeout

# Record a handoff (with tax checking):
python {baseDir}/scripts/swarm_guard.py record-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze sales data, output JSON summary" \
  --artifact  # Include if this handoff produces output

2. Silent Failure Detection 👻

Problem: One agent fails silently, others keep working on bad data.

Prevention - Heartbeats:

# Agents must send heartbeats while working:
python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"

# Check if an agent is healthy:
python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst

# Output if healthy:
# 💚 Agent 'data_analyst' is HEALTHY
#    Last seen: 15s ago

# Output if failed:
# 💔 Agent 'data_analyst' is UNHEALTHY
#    Reason: STALE_HEARTBEAT
#    → Do NOT use any pending results from this agent.

Prevention - Result Validation:

# Before using another agent's result, validate it:
python {baseDir}/scripts/swarm_guard.py validate-result \
  --task-id "task_001" \
  --agent data_analyst \
  --result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'

# Output:
# ✅ RESULT VALID
#    → APPROVED - Result can be used by other agents

Required result fields: status, output, confidence

Supervisor Review

Before finalizing any task, run supervisor review:

python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"

# Output:
# ✅ SUPERVISOR VERDICT: APPROVED
#    Task: task_001
#    Age: 1.5 minutes
#    Handoffs: 2
#    Artifacts: 2

Verdicts:

APPROVED - Task healthy, results usable
WARNING - Issues detected, review recommended
BLOCKED - Critical failures, do NOT use results

Troubleshooting

Permission Denied

Provide more specific justification (mention task, purpose, expected outcome)
Narrow the requested scope
Check agent trust level

Blackboard Read Returns Null

Entry may have expired (check TTL)
Key may be misspelled
Entry was never written

Session Not Found

Run sessions_list to see available sessions
Session may need to be started first

References

AuthGuardian Details - Full permission system documentation
Blackboard Schema - Data structure specifications
Agent Trust Levels - How trust is calculated

File v4.0.13:_meta.json

{ "ownerId": "kn75j1xcebk74re38bv714kh1h81804p", "slug": "network-ai", "version": "4.0.13", "publishedAt": 1772304515783 }

File v4.0.13:ARCHITECTURE.md

Architecture

The Multi-Agent Race Condition Problem

Most 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.

The "Bank Run" scenario:

Agent A reads balance:  $10,000
Agent B reads balance:  $10,000       (same moment)
Agent A writes balance: $10,000 - $7,000 = $3,000
Agent B writes balance: $10,000 - $6,000 = $4,000   ← Agent A's write is gone

Both agents thought they had $10,000. Both spent from it. You lost $3,000 to a race condition.

Without concurrency control, parallel agents will:

Corrupt shared state — two agents overwrite each other's blackboard entries
Double-spend budgets — token costs exceed limits because agents don't see each other's spending
Produce contradictory outputs — Agent A says "approved", Agent B says "denied", both write to the same key

How Network-AI prevents this:

// Atomic commit — no other agent can read/write "account:balance" during this operation
const changeId = blackboard.proposeChange('account:balance', { amount: 7000 }, 'agent-a');
blackboard.validateChange(changeId);   // checks for conflicts
blackboard.commitChange(changeId);     // atomic write with file-system mutex

Component Overview

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
└──────────────────────────┬──────────────────────────────────┘
                           │  createSwarmOrchestrator()
┌──────────────────────────▼──────────────────────────────────┐
│                  SwarmOrchestrator                          │
│                                                             │
│  ┌──────────────┐  ┌───────────────┐  ┌─────────────────┐  │
│  │ AdapterRegistry│  │ AuthGuardian  │  │ FederatedBudget │  │
│  │ (route tasks) │  │ (permissions) │  │ (token ceilings)│  │
│  └──────┬───────┘  └───────────────┘  └─────────────────┘  │
│         │                                                    │
│  ┌──────▼──────────────────────────────────────────────┐   │
│  │            LockedBlackboard (shared state)           │   │
│  │   propose → validate → commit  (file-system mutex)  │   │
│  └──────────────────────────────────────────────────────┘   │
│         │                                                    │
│  ┌──────▼───────────────────────────────────────────────┐  │
│  │  Adapters (plug any framework in, swap out freely)   │  │
│  │  LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │…  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           │
          HMAC-signed audit log (data/audit_log.jsonl)

LockedBlackboard

The coordination core. Uses file-system mutexes so any number of agents can write concurrently without data loss.

propose(key, value, agentId, ttl?, priority?) — stages a change, detects conflicts
validate(changeId, validatorId) — confirms no race occurred since propose
commit(changeId) — atomic write
Conflict strategies: first-commit-wins, priority-wins, last-write-wins

AuthGuardian

const grant = auth.requestPermission('data_analyst', 'DATABASE', 'read',
  'Need customer order history for sales report');
// grant.token is scoped HMAC-signed token with TTL

Resource types: DATABASE (risk 0.5), PAYMENTS (0.7), EMAIL (0.4), FILE_EXPORT (0.6)

Permission scoring: justification quality 40%, agent trust level 30%, resource risk 30%. Threshold: 0.5.

FederatedBudget

Hard token ceilings per agent and per task. Even if 5 agents run in parallel, total spend cannot exceed the budget.

python scripts/swarm_guard.py budget-init   --task-id "task_001" --budget 10000
python scripts/swarm_guard.py budget-check  --task-id "task_001"
python scripts/swarm_guard.py budget-report --task-id "task_001"

AdapterRegistry

Routes tasks to the right agent/framework automatically. Register multiple adapters and the registry dispatches by agent ID.

const registry = new AdapterRegistry();
registry.register('my-langchain-agent', langchainAdapter);
registry.register('my-autogen-agent',   autogenAdapter);

FSM Journey (JourneyFSM)

The FSM governs agent phase transitions for long-running pipelines. Each phase transition is:

Gated by AuthGuardian tokens
Logged to the audit trail
Subject to timeout enforcement

IDLE → PLANNING → EXECUTING → REVIEWING → COMMITTING → COMPLETE
                                           ↓
                                       BLOCKED (on violation)

ComplianceMonitor captures violations in real-time:

TOOL_ABUSE — too many rapid writes
TURN_TAKING — consecutive actions without yield
RESPONSE_TIMEOUT — agent exceeds time budget
JOURNEY_TIMEOUT — overall pipeline exceeds wall-clock limit

Handoff Protocol

Format messages for delegation between agents:

[HANDOFF]
Instruction: Analyze monthly sales by product category
Context: Using database export from ./data/sales_export.csv
Constraints: Focus on top 5 categories only
Expected Output: JSON summary with category, revenue, growth_pct
[/HANDOFF]

Budget-aware handoff (wraps sessions_send with budget checks):

python scripts/swarm_guard.py intercept-handoff \
  --task-id "task_001" \
  --from orchestrator \
  --to data_analyst \
  --message "Analyze Q4 revenue data"

Output:

HANDOFF ALLOWED: orchestrator -> data_analyst
   Tokens spent: 156
   Budget remaining: 9,844
   Handoff #1 (remaining: 2)
   -> Proceed with sessions_send

Content Quality Gate

Two-layer validation before blackboard writes:

Layer 1 — BlackboardValidator (rule-based, zero LLM calls)

Hallucination detection (vague, unsupported, fabricated content)
Dangerous code detection (eval(), exec(), rm -rf)
Placeholder rejection (TODO/FIXME/stub content)
Throughput: ~500,000 ops/sec on 1 KB inputs

Layer 2 — QualityGateAgent (AI-assisted)

Async, intended for high-value writes only
Quarantine system for suspicious content
Adds LLM latency — use selectively

Agent Trust Levels

Configure in scripts/check_permission.py:

DEFAULT_TRUST_LEVELS = {
    "orchestrator": 0.9,
    "my_new_agent": 0.75,
}
GRANT_TOKEN_TTL_MINUTES = 5

Project Structure

Network-AI/
├── index.ts                      # Core orchestrator (SwarmOrchestrator, AuthGuardian, TaskDecomposer)
├── security.ts                   # Security module (tokens, encryption, rate limiting, audit)
├── setup.ts                      # Developer setup & installation checker
├── adapters/                     # 12 plug-and-play agent framework adapters
│   ├── adapter-registry.ts       # Multi-adapter routing & discovery
│   ├── base-adapter.ts           # Abstract base class
│   ├── custom-adapter.ts         # Custom function/HTTP agent adapter
│   ├── langchain-adapter.ts
│   ├── autogen-adapter.ts
│   ├── crewai-adapter.ts
│   ├── mcp-adapter.ts
│   ├── llamaindex-adapter.ts
│   ├── semantic-kernel-adapter.ts
│   ├── openai-assistants-adapter.ts
│   ├── haystack-adapter.ts
│   ├── dspy-adapter.ts
│   ├── agno-adapter.ts
│   └── openclaw-adapter.ts
├── lib/
│   ├── locked-blackboard.ts      # Atomic commits with file-system mutexes
│   ├── blackboard-validator.ts   # Content quality gate (Layer 1 + Layer 2)
│   ├── fsm-journey.ts            # FSM state machine and compliance monitor
│   └── swarm-utils.ts            # Helper utilities
├── scripts/                      # Python helper scripts (local orchestration only)
│   ├── blackboard.py             # Shared state management with atomic commits
│   ├── swarm_guard.py            # Handoff tax prevention, budget tracking
│   ├── check_permission.py       # AuthGuardian permission checker + active grants
│   ├── validate_token.py         # Token validation
│   └── revoke_token.py           # Token revocation + TTL cleanup
├── types/
│   ├── agent-adapter.d.ts        # Universal adapter interfaces
│   └── openclaw-core.d.ts        # OpenClaw type stubs
├── references/                   # Deep-dive documentation
│   ├── adapter-system.md
│   ├── auth-guardian.md
│   ├── blackboard-schema.md
│   ├── trust-levels.md
│   └── mcp-roadmap.md
├── examples/                     # Runnable examples (01–06)
│   ├── 01-hello-swarm.ts
│   ├── 02-fsm-pipeline.ts
│   ├── 03-parallel-agents.ts
│   ├── 04-live-swarm.ts
│   └── 05-code-review-swarm.ts
└── data/
    ├── audit_log.jsonl           # HMAC-signed audit trail (local only)
    └── pending_changes/          # In-flight atomic change records

File v4.0.13:AWESOME_LISTS.md

Awesome List PR Submissions

Ready-to-use PR titles, one-liners, and context for each list. Submit these as pull requests to the respective repositories.

1. awesome-mcp-servers

Repo: https://github.com/punkpeye/awesome-mcp-servers

PR title:

Add network-ai — multi-agent orchestration MCP server with blackboard, FSM, and compliance tools

One-liner to add to the list:

- [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.

Where to add it: Under the orchestration or multi-agent section.

PR body:

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.

2. awesome-ai-agents

Repo: https://github.com/e2b-dev/awesome-ai-agents

PR title:

Add network-ai — TypeScript orchestration framework with concurrency safety for multi-agent systems

One-liner to add to the list:

- [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.

PR body:

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.

3. awesome-langchain

Repo: https://github.com/kyrolabs/awesome-langchain

PR title:

Add network-ai — orchestration layer with LangChain adapter for multi-agent coordination safety

One-liner to add to the list:

- [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.

Where to add it: Under Tools / Agent frameworks / Orchestration.

4. awesome-llamaindex

Repo: https://github.com/emptycrown/awesome-llamaindex (or the official one)

PR title:

Add network-ai — orchestration layer with LlamaIndex adapter

One-liner to add to the list:

- [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.

5. awesome-mcp (or MCP-related lists)

Search: github.com/topics/model-context-protocol

PR title:

Add network-ai — MCP server + client transport for multi-agent orchestration

One-liner:

- [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.

Submission checklist

Before each PR:

[ ] Fork the target repo
[ ] Add the one-liner in alphabetical order by tool name within its section
[ ] PR title follows the repo's existing convention (check other recent PRs)
[ ] Verify the repo's README or CONTRIBUTING.md for any format requirements
[ ] Star the repo before submitting (improves PR acceptance rate)

Other lists to check

https://github.com/jim-schwoebel/awesome-ai-frameworks
https://github.com/AgentOps-AI/agentops (list of frameworks)
https://github.com/topics/ai-agents (GitHub topic — add ai-agents to repo if not there)
Product Hunt — "AI Developer Tools" category launch

File v4.0.13:BENCHMARKS.md

Benchmarks & Performance

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.

BlackboardValidator Throughput

Layer 1 validation (rule-based, zero LLM calls) measured on Node.js 20, Apple M2, single-thread:

| Input size | Ops/sec | Latency | |---|---|---| | Small entry (~100 chars) | ~1,000,000 | < 1 µs | | Medium entry (~1 KB) | ~500,000 | ~2 µs | | Large entry (~10 KB) | ~159,000 | ~6 µs |

Layer 2 (QualityGateAgent) adds LLM latency and is async — intended for high-value writes, not every write.

Cloud Provider Performance

Not 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.

Choosing a Model for Swarm Agents

Speed over depth (many agents, real-time) → gpt-4o-mini, claude-3.5-haiku, gemini-2.0-flash, groq/llama-3.3-70b
Depth over speed (few agents, high-stakes) → gpt-4o, claude-3.7-sonnet
Free / no-cost testing → Groq free tier, Gemini free tier, or Ollama locally
Production with budget → multiple keys across providers, route agents to different models

Rate Limit Patterns

Multiple Keys = True Parallel

import { CustomAdapter, AdapterRegistry } from 'network-ai';

const registry = new AdapterRegistry();

for (const reviewer of REVIEWERS) {
  const adapter = new CustomAdapter();
  const client  = new OpenAI({ apiKey: process.env[`OPENAI_KEY_${reviewer.id.toUpperCase()}`] });

  adapter.registerHandler(reviewer.id, async (payload) => {
    const resp = await client.chat.completions.create({ /* ... */ });
    return { findings: extractContent(resp) };
  });

  registry.register(reviewer.id, adapter);
}

// All 5 dispatch in parallel via Promise.all — ~8–12s instead of ~60s

Local GPU = Zero Rate Limits

const localClient = new OpenAI({
  apiKey : 'not-needed',
  baseURL: 'http://localhost:11434/v1',   // Ollama, vLLM, llama.cpp
});

adapter.registerHandler('reviewer', async (payload) => {
  const resp = await localClient.chat.completions.create({
    model   : 'llama3.2',
    messages: [/* ... */],
  });
  return { findings: extractContent(resp) };
});

Cloud GPU Instances (Self-Hosted)

Running your own model on AWS / GCP / Azure sits between managed APIs and local hardware:

`max_completion_tokens` — The Silent Truncation Trap

This is especially dangerous for code-rewrite agents where the output is a full file.

# Real numbers (gpt-5-mini, order-service.ts rewrite):
  Blockers section:  ~120 tokens
  Fixed code:        ~2,800 tokens  (213 lines with // FIX: comments)
  Total needed:      ~3,000 tokens  ← hits the cap exactly → empty output
  Fix: set to 16,000 → full rewrite delivered in one shot

Rule of Thumb by Task

All GPT-5 variants support 128,000 max output tokens — the ceiling is never the model, it is always the cap you set.

Lessons from Building the Code-Review Swarm

File v4.0.13:INTEGRATION_GUIDE.md

Network-AI Integration Guide

For technical leads, solutions architects, and engineering teams evaluating or deploying Network-AI in a production environment.

This guide walks from "we want this" to "it's running in production" — covering discovery, framework mapping, phased rollout, enterprise concerns, and validation.

Before You Start — Discovery
Framework Mapping
Primitive Mapping — What Solves What
Phased Rollout
Enterprise Concerns
Architecture Patterns
Validation Checklist
Common Integration Mistakes

1. Before You Start — Discovery

Before touching any code, answer these questions. They determine which adapters you need and which governance primitives are non-negotiable.

1.1 Agent Inventory

Document every AI agent or automated process your team currently runs:

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.

1.2 Race Condition Audit

For each pair of agents that write to the same resource, ask:

Can both agents run at the same time?
What happens if Agent A's write is overwritten by Agent B before Agent A reads it back?
Is there any locking or retry logic today?

If the answer to the first question is "yes" and the second is "data loss / wrong decision / double spend" — that's a LockedBlackboard candidate.

1.3 Budget and Cost Exposure

Do you have per-agent token limits today?
Can a single runaway agent exhaust your OpenAI / Anthropic budget?
Do you have hard cut-offs or just alerts?

Network-AI's FederatedBudget enforces hard ceilings. If you have no ceiling today, this is your first priority.

1.4 Compliance and Audit Requirements

Does your industry require audit trails for automated decisions (GDPR, SOC 2, HIPAA, PCI-DSS)?
Do you need to prove which agent made which decision and when?
Are there regulatory rules about which systems an AI agent may access?

Answers drive AuthGuardian configuration and audit log retention policy.

2. Framework Mapping

Network-AI ships 12 adapters. Map your existing agents to the right one:

No matching framework?

Use CustomAdapter. Any async function becomes a governed agent in three lines:

import { CustomAdapter } from 'network-ai';

const adapter = new CustomAdapter();
adapter.registerHandler('my-agent', async (payload) => {
  // your existing logic here — unchanged
  return { result: '...' };
});

This is the recommended entry point for legacy systems, internal microservices, and REST APIs — you do not need to rewrite anything.

3. Primitive Mapping — What Solves What

Match your problem to the Network-AI primitive:

4. Phased Rollout

Do not try to enable everything at once. This is the recommended sequence for a zero-disruption integration:

Phase 1 — Wrap (Day 1–3)

Goal: Get your existing agents running inside Network-AI without changing their behaviour.

npm install network-ai
Wrap each agent in the matching adapter (see §2)
Register all adapters with AdapterRegistry
Replace direct agent calls with registry.executeAgent(...) or orchestrator.execute(...)
Run npm run demo -- --08 to verify the framework itself is healthy in your environment

Nothing changes behaviourally yet. This phase is purely structural.

import { createSwarmOrchestrator, CustomAdapter } from 'network-ai';

const orchestrator = createSwarmOrchestrator({ swarmName: 'acme-swarm' });
const adapter = new CustomAdapter();

// Wrap your existing function — unchanged
adapter.registerHandler('invoice-classifier', async (payload) => {
  return await yourExistingClassifier(payload.params);
});

await orchestrator.addAdapter(adapter);

Phase 2 — Shared State (Day 3–7)

Goal: Replace ad-hoc shared resources (databases, files, in-memory objects) with the blackboard.

Identify all keys agents share (from your §1.1 audit)
Introduce SharedBlackboard for low-contention data
Introduce LockedBlackboard for any key that two or more agents write to concurrently

import { LockedBlackboard } from 'network-ai';

const board = new LockedBlackboard('.', { conflictResolution: 'priority-wins' });

// Atomic write — no other agent can interfere during this operation
const changeId = board.proposeChange('account:balance', newBalance, 'payment-agent');
board.validateChange(changeId);
board.commitChange(changeId);

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.

Phase 3 — Budget Enforcement (Day 7–10)

Goal: Add hard token ceilings so no single agent can exhaust your LLM budget.

import { FederatedBudget } from 'network-ai/lib/federated-budget';

const budget = new FederatedBudget({
  pools: {
    'classifier':   { ceiling: 50_000  },  // tokens per run
    'summarizer':   { ceiling: 100_000 },
    'orchestrator': { ceiling: 200_000 },
  }
});

// Check before each LLM call
const check = budget.canSpend('classifier', estimatedTokens);
if (!check.allowed) throw new Error(`Budget ceiling reached: ${check.reason}`);

// Record actual spend after
budget.recordSpend('classifier', actualTokens);

Map your cost centers to pool names. Budget state persists across agent runs.

Phase 4 — Access Control (Day 10–14)

Goal: Gate access to sensitive APIs and resources behind cryptographically signed tokens.

Define your resources and risk levels (see references/auth-guardian.md)
Map your agents to trust levels (see references/trust-levels.md)
Replace direct API calls with AuthGuardian-gated calls

import { AuthGuardian, SecureTokenManager } from 'network-ai';

const guardian = new AuthGuardian();
const tokenManager = new SecureTokenManager(process.env.HMAC_SECRET!);

// Agent requests access with a justification
const request = await guardian.requestPermission({
  agentId: 'payment-agent',
  resource: 'PAYMENTS',
  action: 'write',
  justification: 'Processing approved invoice #INV-2847 per workflow step 3',
  trustLevel: 0.8,
});

if (request.approved) {
  const token = tokenManager.createToken('payment-agent', ['PAYMENTS:write'], 300);
  // pass token to downstream call
}

Phase 5 — Governance and FSM (Day 14–21)

Goal: Define explicit workflow states so agents can only act when the system is in the right state.

import { JourneyFSM, WORKFLOW_STATES } from 'network-ai';

const fsm = new JourneyFSM({
  agentId: 'workflow',
  journeyId: 'invoice-processing',
  transitions: [
    { from: 'INTAKE',   to: 'ANALYZE',  allowedAgents: ['intake-agent']  },
    { from: 'ANALYZE',  to: 'APPROVE',  allowedAgents: ['analyst-agent'] },
    { from: 'APPROVE',  to: 'EXECUTE',  allowedAgents: ['approver-agent'] },
    { from: 'EXECUTE',  to: 'DELIVER',  allowedAgents: ['payment-agent'] },
  ]
});

// Before any agent acts, check the FSM
const canAct = fsm.canTransition(currentState, nextState, agentId);

Add ComplianceMonitor to detect violations in real time without blocking the main thread:

import { ComplianceMonitor } from 'network-ai';

const monitor = new ComplianceMonitor(fsm, {
  maxActionsPerTurn: 5,
  responseTimeoutMs: 30_000,
  journeyTimeoutMs: 300_000,
});
monitor.start(1_000); // poll every second

Phase 6 — Observability and MCP (Day 21+)

Goal: Expose everything to your monitoring stack and optionally give your AI models control-plane access.

Start the MCP server (exposes 20+ tools via SSE/JSON-RPC):

npx network-ai-server --port 3001 --audit-log data/audit_log.jsonl --ceiling 500000

Connect your AI model to http://localhost:3001/sse — it can now:

Read and write live config (config_get, config_set)
Spawn and stop agents (agent_spawn, agent_stop)
Drive FSM transitions (fsm_transition)
Query the audit log (audit_query, audit_tail)
Check and top up budgets (budget_status, budget_spend)

5. Enterprise Concerns

Authentication & IAM

Network-AI does not require or replace an external IAM system. AuthGuardian operates as a pre-authorization layer:

AI Agent → AuthGuardian (justification scoring) → your IAM (final auth) → resource

The 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).

Audit Log Retention

The 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.

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.
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.
SIEM integration: Stream audit_log.jsonl to Splunk, Datadog, or Elastic via the audit_tail MCP tool or a simple tail -F feed.

Air-Gapped / On-Prem Deployment

Network-AI has zero required external network calls. All operations (blackboard, FSM, compliance, budget, tokens, audit) run entirely on-premises:

No telemetry, no call-home, no cloud dependency
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
The MCP server (network-ai-server) binds to localhost by default; deploy behind your internal API gateway to expose it to your agent fleet

Multi-Tenant Deployments

Isolate tenants by:

Separate blackboard roots — each tenant gets their own directory path passed to LockedBlackboard(tenantPath)
Separate budget pools — prefix pool names with tenant ID: tenant-abc:classifier
Separate HMAC secrets — one SecureTokenManager instance per tenant
Namespace scoping — use consistent key prefixes in the blackboard (e.g. tenant-abc:invoice:42)

Scaling

Network-AI is a single-process orchestrator by design — it does not require a broker, queue, or service mesh. For horizontal scaling:

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.
Independent budget tracking: Each instance tracks its own pool. Use a sidecar or the audit_tail MCP tool to aggregate spend across instances.
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.

6. Architecture Patterns

Pattern A — Sidecar (Minimal Disruption)

Keep your existing agent orchestration. Add Network-AI only for coordination, safety, and audit on the shared state layer.

[Existing LangChain agent] ──writes──▶ [LockedBlackboard] ◀──reads── [Existing AutoGen agent]
                                              │
                                       [Audit log]
                                       [Budget tracking]

No changes to your agent code. Network-AI wraps the shared resource only.

Pattern B — Full Orchestrator

Network-AI owns the entire agent lifecycle. All agents run through the adapter registry.

User request
     │
     ▼
SwarmOrchestrator
     │
     ├──▶ AuthGuardian (permission check)
     ├──▶ JourneyFSM (state gate)
     ├──▶ FederatedBudget (cost check)
     │
     ├──▶ LangChainAdapter ──▶ your LangChain agent
     ├──▶ AutoGenAdapter   ──▶ your AutoGen agent
     └──▶ CustomAdapter    ──▶ your existing functions

Pattern C — MCP Control Plane

Your AI model connects to network-ai-server via SSE and drives the whole system through MCP tools — no hand-coded orchestration logic at all.

AI Model (Claude / GPT-4o)
     │  SSE/JSON-RPC
     ▼
network-ai-server (port 3001)
     │
     ├── ControlMcpTools   (spawn agents, drive FSM, set config)
     ├── ExtendedMcpTools  (budget, tokens, audit)
     └── BlackboardMCPTools (read/write blackboard)

7. Validation Checklist

Run these before declaring the integration production-ready:

Functional

[ ] All agents execute via the adapter registry without errors
[ ] npx ts-node test-standalone.ts — 79 core tests pass
[ ] npx ts-node test-security.ts — 33 security tests pass
[ ] npx ts-node test-adapters.ts — 139 adapter tests pass
[ ] npx ts-node test-phase4.ts — 147 behavioral tests pass
[ ] npm run demo -- --08 runs to completion in < 10 seconds

Race Condition Safety

[ ] Two agents can write to the same blackboard key concurrently without data loss
[ ] LockedBlackboard.validateChange() rejects a stale change after a conflict
[ ] priority-wins correctly overwrites a lower-priority pending write

Budget Enforcement

[ ] Spending past the ceiling throws / returns allowed: false
[ ] Budget state persists across process restart
[ ] Per-agent pools are independent (overspending in pool A does not affect pool B)

Access Control

[ ] A token issued by SecureTokenManager validates correctly
[ ] An expired token is rejected
[ ] A token with insufficient scope is rejected at the AuthGuardian gate
[ ] --active-grants shows the correct active token set

Compliance

[ ] ComplianceMonitor fires TOOL_ABUSE after the configured action threshold
[ ] RESPONSE_TIMEOUT fires when an agent exceeds the timeout window
[ ] JOURNEY_TIMEOUT fires when the overall journey exceeds its ceiling
[ ] FSM blocks a transition attempted by an unauthorized agent

Audit

[ ] Every blackboard write produces a signed entry in audit_log.jsonl
[ ] audit_query returns filtered results correctly
[ ] The audit chain signature is intact after N entries (run the chain verifier)

8. Common Integration Mistakes

Show HN: Network-AI — Multi-Agent Race Condition Prevention for TypeScript

Post title:

Show HN: Network-AI – plug-and-play orchestrator that prevents race conditions when AI agents share state

Body

Most agent frameworks give you parallelism. None of them give you coordination safety.

The classic failure:

Agent A reads balance:  $10,000
Agent B reads balance:  $10,000       ← same moment
Agent A writes balance: $3,000        ← deducts $7,000
Agent B writes balance: $4,000        ← deducts $6,000, ignoring Agent A's write

Both agents believed they had $10,000. Both spent from it. You now have a $3,000 error with no trace of what happened.

This 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.

What Network-AI does:

Atomic blackboard — propose → validate → commit with file-system mutex. No two agents can write to the same key simultaneously.
Priority preemption — if two agents conflict, the higher-priority write wins deterministically (not "last write wins" chaos)
FSM governance — agents can only act when the workflow is in the right state
FederatedBudget — per-agent token ceilings with hard cut-off. One runaway agent cannot exhaust your OpenAI bill.
ComplianceMonitor — detects TOOL_ABUSE, turn-taking violations, response timeouts, journey timeouts in real time
12 framework adapters — LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and a CustomAdapter for anything else

You can see the whole thing in 2 seconds with no API key:

git clone https://github.com/jovanSAPFIONEER/Network-AI
cd Network-AI
npm install
npm run demo -- --08

This runs the control-plane stress demo: atomic commits, priority preemption, FSM timeout, and 17 live compliance violations — all in ~2 seconds, no LLM calls.

Or the full AI showcase (needs OPENAI_API_KEY):

npm run demo -- --07

Stack: TypeScript, Node.js 18+. Zero required external services. Works on-prem, air-gapped, or cloud.

Repo: https://github.com/jovanSAPFIONEER/Network-AI
npm: npm install network-ai
MCP server: npx network-ai-server --port 3001

Happy to answer questions about the coordination model, the FSM design, or how the atomic commits work.

Timing notes

Post on a Tuesday or Wednesday between 9–11am ET — peak HN traffic window
Tag: Show HN
Do not post the same week as a major AI framework release (it will get buried)
Have the demo commands ready to paste in the comments — someone will ask immediately

Expected comment threads to prepare for

"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).
"Does this work with Python?" → Python scripts are included (scripts/), TypeScript is the orchestration layer
"What's the performance overhead of the file-system mutex?" → microseconds for local; designed for workloads where LLM latency (100ms–10s) dominates
"Is this production-ready?" → MIT, 1,200+ tests, CodeQL + OpenSSF Scorecard on CI, 2,500+ weekly npm downloads at 24 days old

File v4.0.13:requirements.txt

Python dependencies for Swarm Orchestrator Skill

Install: pip install -r requirements.txt

Core dependencies (all optional - stdlib works on Unix)

filelock>=3.0.0 # Cross-platform file locking (recommended for Windows)

Note: The blackboard uses fcntl on Unix (built-in) with fallback for Windows.

For production Windows deployments, uncomment filelock above.

If you want to run type checking:

mypy>=1.0.0

If you want to run tests:

pytest>=7.0.0

API & Reliability

Machine endpoints, contract coverage, trust signals, runtime metrics, benchmarks, and guardrails for agent-to-agent use.

MissingCLAWHUB

Machine interfaces

Contract & API

Endpoints

Dossier API Snapshot API Contract API Trust API

Contract coverage

Status

missing

Auth

None

Streaming

Data region

Unspecified

Protocol support

OpenClaw: self-declared

Requires: none

Forbidden: none

Guardrails

Operational confidence: low

No positive guardrails captured.

Invocation examples

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"

Operational fit

Reliability & Benchmarks

Trust signals

Handshake

UNKNOWN

Confidence

unknown

Attempts 30d

unknown

Fallback rate

unknown

Runtime metrics

Observed P50

unknown

Observed P95

unknown

Rate limit

unknown

Estimated cost

unknown

Do not use if

Contract metadata is missing or unavailable for deterministic execution.

No benchmark suites or observed failure patterns are available.

Machine Appendix

Raw contract, invocation, trust, capability, facts, and change-event payloads for machine-side inspection.

MissingCLAWHUB

Contract JSON

{
  "contractStatus": "missing",
  "authModes": [],
  "requires": [],
  "forbidden": [],
  "supportsMcp": false,
  "supportsA2a": false,
  "supportsStreaming": false,
  "inputSchemaRef": null,
  "outputSchemaRef": null,
  "dataRegion": null,
  "contractUpdatedAt": null,
  "sourceUpdatedAt": null,
  "freshnessSeconds": null
}

Invocation Guide

{
  "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-09T03:45:38.896Z"
    }
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffMs": [
      500,
      1500,
      3500
    ],
    "retryableConditions": [
      "HTTP_429",
      "HTTP_503",
      "NETWORK_TIMEOUT"
    ]
  }
}

Trust JSON

{
  "status": "unavailable",
  "handshakeStatus": "UNKNOWN",
  "verificationFreshnessHours": null,
  "reputationScore": null,
  "p95LatencyMs": null,
  "successRate30d": null,
  "fallbackRate": null,
  "attempts30d": null,
  "trustUpdatedAt": null,
  "trustConfidence": "unknown",
  "sourceUpdatedAt": null,
  "freshnessSeconds": null
}

Capability Matrix

{
  "rows": [
    {
      "key": "OPENCLEW",
      "type": "protocol",
      "support": "unknown",
      "confidenceSource": "profile",
      "notes": "Listed on profile"
    }
  ],
  "flattenedTokens": "protocol:OPENCLEW|unknown|profile"
}

Facts JSON

[
  {
    "factKey": "vendor",
    "category": "vendor",
    "label": "Vendor",
    "value": "Clawhub",
    "href": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceUrl": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceType": "profile",
    "confidence": "medium",
    "observedAt": "2026-04-15T00:45:39.800Z",
    "isPublic": true
  },
  {
    "factKey": "protocols",
    "category": "compatibility",
    "label": "Protocol compatibility",
    "value": "OpenClaw",
    "href": "https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/contract",
    "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/contract",
    "sourceType": "contract",
    "confidence": "medium",
    "observedAt": "2026-04-15T00:45:39.800Z",
    "isPublic": true
  },
  {
    "factKey": "traction",
    "category": "adoption",
    "label": "Adoption signal",
    "value": "788 downloads",
    "href": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceUrl": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceType": "profile",
    "confidence": "medium",
    "observedAt": "2026-04-15T00:45:39.800Z",
    "isPublic": true
  },
  {
    "factKey": "latest_release",
    "category": "release",
    "label": "Latest release",
    "value": "4.0.14",
    "href": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceUrl": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceType": "release",
    "confidence": "medium",
    "observedAt": "2026-02-28T18:59:58.541Z",
    "isPublic": true
  },
  {
    "factKey": "handshake_status",
    "category": "security",
    "label": "Handshake status",
    "value": "UNKNOWN",
    "href": "https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/trust",
    "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-jovansapfioneer-network-ai/trust",
    "sourceType": "trust",
    "confidence": "medium",
    "observedAt": null,
    "isPublic": true
  }
]

Change Events JSON

[
  {
    "eventType": "release",
    "title": "Release 4.0.14",
    "description": "**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.",
    "href": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceUrl": "https://clawhub.ai/jovanSAPFIONEER/network-ai",
    "sourceType": "release",
    "confidence": "medium",
    "observedAt": "2026-02-28T18:59:58.541Z",
    "isPublic": true
  }
]