v4.3.3 — Security: CWE-367 TOCTOU fix (CodeQL #86 / #87)

Security patch — CWE-367 TOCTOU resolved (CodeQL #86 / #87)

Two High severity CodeQL alerts (js/file-system-race, CWE-367) introduced with the v4.3.0 CLI have been fixed. No functional changes — all 1,399 tests pass.

---

What was wrong

Both issues were classic time-of-check to time-of-use (TOCTOU) races: the file's state was read with fs.statSync(filename), and then the file was opened separately with fs.openSync(filename). In the window between those two calls, the file could be replaced or modified by another process.

---

Alert #86 — bin/cli.ts:269 (audit tail command)

Before:

const newSize = fs.statSync(logFile).size;   // ← check
if (newSize > size) {
  const fd = fs.openSync(logFile, 'r');       // ← use  (race window here)
  const buf = Buffer.alloc(newSize - size);
  fs.readSync(fd, buf, 0, buf.length, size);
  fs.closeSync(fd);
}

After — fd opened first, fstatSync on the descriptor:

const fd = fs.openSync(logFile, 'r');         // ← open first
try {
  const newSize = fs.fstatSync(fd).size;      // ← check on already-open fd
  if (newSize > size) {
    const buf = Buffer.alloc(newSize - size);
    fs.readSync(fd, buf, 0, buf.length, size);
    buf.toString('utf-8').trim().split('\n').filter(Boolean).forEach(l => console.log(l));
    size = newSize;
  }
} finally {
  fs.closeSync(fd);
}

---

Alert #87 — test-cli.ts:360 (Section 9b tail test)

Before:

const before = fs.statSync(logFile).size;
fs.appendFileSync(logFile, JSON.stringify({ event: 'write', key: 'k' }) + '\n');
const after = fs.statSync(logFile).size;

After — single fd, no filename re-check:

const fd = fs.openSync(logFile, 'a+');
try {
  const before = fs.fstatSync(fd).size;
  fs.writeSync(fd, JSON.stringify({ event: 'write', key: 'k' }) + '\n');
  const after = fs.fstatSync(fd).size;
  assert(after > before, 'file size grew after append (tail would detect this)');
} finally {
  fs.closeSync(fd);
}

---

Also in this release

• SECURITY.md Supported Versions table updated to reflect 4.3.x as current
• SECURITY.md CodeQL note updated to document both TOCTOU resolutions

---

All 1,399 assertions across 17 suites pass.
Full Changelog: https://github.com/jovanSAPFIONEER/Network-AI/blob/main/CHANGELOG.md

v4.3.2 — CLI + full docs sync

v4.3.2 — CLI + docs, fully synced

This release consolidates everything shipped in v4.3.0 and v4.3.1 into a single clean version reference. No code changes — 1,399 passing assertions across 17 suites.

---

What's in the 4.3.x series

network-ai CLI (shipped in v4.3.0)

Full in-process CLI — imports LockedBlackboard, AuthGuardian, and FederatedBudget directly, no server required.

npm install -g network-ai
network-ai --help

network-ai bb — Blackboard CRUD + atomic workflow

network-ai bb get agent:status
network-ai bb set agent:status running --agent orchestrator
network-ai bb list
network-ai bb snapshot

# Atomic propose → commit
network-ai bb propose agent:status complete    # prints changeId
network-ai bb commit  <changeId>
network-ai bb abort   <changeId>

network-ai auth — AuthGuardian tokens

network-ai auth token data_analyst \
  --resource DATABASE --action read \
  --justification "Need Q4 invoices for revenue report"
network-ai auth check grant_a1b2c3...
network-ai auth revoke grant_a1b2c3...

network-ai budget — FederatedBudget

network-ai budget status
network-ai budget set-ceiling 50000

network-ai audit — Audit log

network-ai audit log --limit 50
network-ai audit tail       # live-stream
network-ai audit clear

Global flags: --data <path> · --json

---

Documentation (shipped in v4.3.1)

CLI documented across all docs:

• README — ## CLI section with command-group table
• QUICKSTART — ## 10. CLI full reference
• ARCHITECTURE — ### CLI (bin/cli.ts) component + Project Structure entry
• SECURITY — CLI audit commands in Audit Trail section
• ENTERPRISE — CLI row in Integration Entry Points
• AUDIT_LOG_SCHEMA — CLI access in File Location section
• INTEGRATION_GUIDE — CLI in Further Reading
• references/auth-guardian — ## CLI Usage section
• references/trust-levels — ## CLI and Trust Levels section
• SKILL.md — ### 5. Use the Node.js CLI in Quick Start

---

Full Changelog: https://github.com/jovanSAPFIONEER/Network-AI/blob/main/CHANGELOG.md

v4.3.1 — CLI documentation patch

What's new in v4.3.1

CLI documentation added across all docs

Full CLI reference (
etwork-ai bb, �uth, �udget, �udit) is now documented throughout:

• README — new ## CLI\ section with command-group table and global flags
• QUICKSTART — new ## 10. CLI\ section with full command reference for all groups
• ARCHITECTURE — new ### CLI (bin/cli.ts)\ subsection; \�in/cli.ts\ in Project Structure tree
• SECURITY — CLI audit commands added to Audit Trail section
• ENTERPRISE — CLI row in Integration Entry Points table
• AUDIT_LOG_SCHEMA — CLI access commands in File Location section
• INTEGRATION_GUIDE — CLI row in Further Reading table
• references/auth-guardian — new ## CLI Usage\ section
• references/trust-levels — new ## CLI and Trust Levels\ section

No code changes

All 1,399 tests pass. Semantic versioning: docs-only patch bump (4.3.0 → 4.3.1).

---

Full Changelog: https://github.com/jovanSAPFIONEER/Network-AI/blob/main/CHANGELOG.md

v4.3.0 — Full CLI (network-ai bb / auth / budget / audit)

CLI — direct terminal control over all Network-AI internals

v4.3.0 ships a full built-in CLI so you can inspect and control the swarm from the terminal without running a server. It imports LockedBlackboard, AuthGuardian, and FederatedBudget directly — same core the MCP server uses.

Install

npm install -g network-ai
network-ai --help

Or from source without installing:

npx ts-node bin/cli.ts --help

---

network-ai bb — Blackboard

network-ai bb set agent:status running --agent orchestrator
network-ai bb get agent:status
network-ai bb delete agent:status
network-ai bb list
network-ai bb snapshot                         # pretty-print full state

# Atomic propose → commit workflow
network-ai bb propose agent:status complete    # prints changeId
network-ai bb commit  <changeId>
network-ai bb abort   <changeId>

network-ai auth — AuthGuardian

# Issue a scoped permission token
network-ai auth token data_analyst \
  --resource DATABASE --action read \
  --justification "Need Q4 invoices for revenue report"

network-ai auth check grant_a1b2c3...         # validate a token
network-ai auth revoke grant_a1b2c3...        # revoke a token

network-ai budget — FederatedBudget

network-ai budget status                       # view spend across all agents
network-ai budget set-ceiling 50000            # raise / lower the ceiling

network-ai audit — Audit log

network-ai audit log --limit 50               # print recent entries
network-ai audit tail                          # live-stream new entries
network-ai audit clear                         # reset the log

Global flags (every command)

Flag	Default	Purpose
--data <path>	./data	Override data directory
--json	off	Machine-readable JSON output

---

What else shipped in v4.3.0

• bin/cli.ts — fully in-process CLI implementation (4 command groups, 14 subcommands)
• test-cli.ts — 65 new assertions covering all CLI commands
• commander v13 added as production dependency
• package.json bin: "network-ai": "./dist/bin/cli.js" alongside network-ai-server
• Test runner: 17 suites, 1,399 passing (was 16 / 1,334)

---

Full Changelog: https://github.com/jovanSAPFIONEER/Network-AI/blob/main/CHANGELOG.md

v4.2.0 — CodexAdapter (OpenAI Codex CLI / chat / completion)

v4.2.0 — CodexAdapter (OpenAI Codex CLI / chat / completion)

---

## What's new

### CodexAdapter — 14th adapter

Adds first-class support for OpenAI Codex and code-focused models in three execution modes:

| Mode | Description |
|---|---|
| `chat` | `/v1/chat/completions` — gpt-4o, o4-mini, any chat model |
| `completion` | `/v1/completions` — code-davinci-002 and legacy Codex models |
| `cli` | Wraps the [Codex CLI tool](https://github.com/openai/codex) via a user-supplied executor function |

**BYOC (bring your own client)** — pass any OpenAI SDK instance directly, or let the adapter use the built-in `fetch` path with your API key:

```typescript
import { CodexAdapter } from 'network-ai';

const adapter = new CodexAdapter();

// Chat mode — gpt-4o
adapter.registerCodexAgent('refactor', {
  mode: 'chat',
  model: 'gpt-4o',
  systemPrompt: 'You are a refactoring assistant.',
  apiKey: process.env.OPENAI_API_KEY,
});

// CLI mode — Codex CLI tool
adapter.registerCodexAgent('codex-cli', {
  mode: 'cli',
  executor: async (prompt) => myCodexCLIWrapper(prompt),
});

// BYOC — bring your own OpenAI SDK instance
adapter.registerCodexAgent('analyst', {
  mode: 'chat',
  model: 'o4-mini',
  client: openai.chat.completions,
});

Blackboard snapshots and handoff instructions are automatically included in the prompt. AbortController timeout (60s) guards all fetch-based calls.

Stats

• 14 adapters (was 13)
• 1,334 passing assertions across 16 test suites (51 new in test-codex.ts)

Full changelog

See CHANGELOG.md for the complete entry.

v4.1.0 — Streaming Adapters, A2A Protocol, Real LangChain Example

v4.1.0 — Streaming Adapters, A2A Protocol, Real LangChain Example

## What's New

### 🔴 Streaming Adapters
Incremental token streaming is now a first-class adapter primitive.

- **`StreamingBaseAdapter`** — abstract base class with `executeAgentStream()` returning `AsyncIterable<StreamingChunk>`. Default single-chunk fallback wraps any existing `executeAgent()` result, so no existing adapter breaks.
- **`LangChainStreamingAdapter`** — drop-in replacement for `LangChainAdapter`. Automatically detects Runnables that expose `.stream()` (LCEL chains, `ChatOpenAI`, etc.) and yields tokens incrementally. Falls back to `.invoke()` for non-streamable runnables.
- **`CustomStreamingAdapter`** — drop-in replacement for `CustomAdapter`. Handlers can now be async generator functions that `yield` tokens. Plain `Promise`-returning handlers continue to work unchanged.
- **`collectStream()` helper** — drain any stream into `{ output: string, chunks: StreamingChunk[] }` in one call.
- **`types/streaming-adapter.d.ts`** — `StreamingChunk`, `IStreamingAdapter`, `StreamCollector` types.

```typescript
for await (const chunk of adapter.executeAgentStream('analyst', payload, ctx)) {
  process.stdout.write(chunk.text);
  if (chunk.done) break;
}

🤝 A2A Protocol Adapter

Full implementation of the Google A2A open protocol — the emerging standard for agent interoperability.

• Fetches remote Agent Cards from /.well-known/agent.json
• Sends JSON-RPC 2.0 tasks/send envelopes to the agent's task endpoint
• Bearer token auth, configurable timeout, AbortController hang guard
• registerRemoteAgent(id, baseUrl) — auto-discovers capability from the card
• registerLocalA2AAgent(id, card) — register without a network fetch (e.g. from config)

const adapter = new A2AAdapter();
await adapter.initialize({});
await adapter.registerRemoteAgent('remote-analyst', 'https://agent.example.com');
// then use in any orchestrator: delegate_task → a2a:remote-analyst

🔗 Real LangChain Example (09-real-langchain.ts)

End-to-end walkthrough wiring actual LangChain Runnables into the orchestrator — no mocks in production code. Swap the mockRunnable() stubs for ChatOpenAI + RunnableSequence and it runs against a real LLM. Shows:

• LangChain analysis chain → summary chain pipeline
• CustomAdapter running in parallel in the same swarm (cross-framework)
• AuthGuardian permission gate + blackboard persistence

---

Tests

1,283 passing across 15 suites — 67 new assertions, 0 failures.

New suite	Assertions	Covers
test-streaming.ts	31	Fallback wrapper, collectStream, generator handlers, AIMessage chunks, error paths
test-a2a.ts	34	Init, local/remote register, happy-path execute, HTTP/A2A/state errors, multi-artifact, mock fetch

---

Breaking Changes

None. All additions are additive — no existing exports, types, or behaviours were modified.

---

Upgrade

npm install network-ai@4.1.0
# or
clawhub update network-ai

https://github.com/jovanSAPFIONEER/Network-AI/blob/main/CHANGELOG.md#4100---2026-03-05

v4.0.17 — Socket supply chain fix + documentation accuracy pass

What's changed

Fixed

• Socket.dev supply chain score — eval( string literals in test fixture data were being flagged by static analysis as dynamic code execution. The strings are now assembled via concatenation so the pattern only exists at runtime; all 79 dangerous-code detection assertions still pass.

Documentation

• Architecture diagram — replaced ASCII art with a colour-coded Mermaid flowchart reflecting the actual code (SharedBlackboard, not LockedBlackboard; QualityGateAgent as a built-in component; FederatedBudget correctly noted as a standalone export)
• Comparison table — replaced absolute ❌ marks with honest ⚠️ not built-in / possible via X for LangGraph, CrewAI, and AutoGen; corrected audit trail description from "HMAC-signed" to "plain JSONL"
• Keywords section — replaced 90-term keyword dump with a focused 30-term list

Scores after this release

Scanner	Score
Socket Vulnerability	100
Socket Quality	100
Socket Maintenance	96
Socket License	100
Socket Supply Chain	↑ (eval false positive removed)

Install

npm install network-ai@4.0.17

v4.0.16 — Enterprise demo: AuthGuardian gate + violation deduplication

v4.0.16 — Enterprise demo: AuthGuardian gate + violation deduplication

## What's in this release

### v4.0.16 — Enterprise demo improvements

The control-plane demo (`examples/08-control-plane-stress-demo.ts`) is now video-ready and covers every major guardrail in a single no-API-key run.

**Changes:**
- **AuthGuardian permission gate added as Phase 2** — agent attempts `PAYMENTS` access with a weak justification → `BLOCKED`; retries with a specific task-scoped justification → `GRANTED` with a token + `["audit_required"]` restriction — the most enterprise-relevant moment in the whole stack, now visible in the demo
- **Violation deduplication** — `ComplianceMonitor` previously printed the same `RESPONSE_TIMEOUT` / `JOURNEY_TIMEOUT` line 8–12 times during the sleep window; now prints the first occurrence of each `type+agentId` pair and shows a suppressed-count summary line at the end
- Phases renumbered 1→4: Priority Preemption, Permission Gate, FSM + Compliance, Summary

**Run it (no API key required):**
```bash
npx ts-node examples/08-control-plane-stress-demo.ts

---

v4.0.15 — Enterprise trust artifacts

Three new files designed to let an engineer evaluate Network-AI without a meeting:

• ENTERPRISE.md — evaluation checklist (offline/air-gapped, data ownership, audit trail, adapter compatibility, security supply chain, cost), architecture summary, versioning + support policy, stability signals, integration entry points
• AUDIT_LOG_SCHEMA.md — complete audit log field reference: all 9 event types (permission_request, permission_granted, permission_denied, permission_revoked, ttl_cleanup, budget_initialized, handoff_allowed, handoff_blocked, safety_shutdown), per-event details schemas with typed field tables, weighted scoring formula, retention and privacy notes
• ADOPTERS.md — adopters registry; open a PR to add your organization or project

---

No breaking changes

No API, behaviour, or runtime changes in either release. Documentation and demo only.

---

npm: npm install network-ai@4.0.16
Full changelog: CHANGELOG.md

v4.0.14 — Accurate Python skill bundle documentation

What changed

The OpenClaw scanner flagged that skill.json and SKILL.md overstated what the Python scripts actually do. The HMAC-signed tokens, AES-256-GCM encryption, and standalone MCP server are all features of the Node.js package (network-ai on npm) — they are not present in the Python skill bundle. This release corrects every affected document.

Fixed

• skill.json description — removed "enforces HMAC-gated AuthGuardian permissions"; now accurately describes UUID-based grant tokens and plain JSONL audit logging; added explicit callout that HMAC/AES-256 are Node.js-only
• skill.json env block — SWARM_TOKEN_SECRET and SWARM_ENCRYPTION_KEY marked "Node.js MCP server only — NOT used by the Python scripts"
• SKILL.md scope notice — tokens are grant_{uuid4().hex}; audit logging is plain JSONL append; HMAC-signed tokens / AES-256 encryption / standalone MCP server are Node.js package features
• SKILL.md env block — all three env vars corrected to match
• .github/SECURITY.md — "Security Measures" and "Audit Trail" sections split into two explicit layers:
  • Python skill bundle: UUID tokens, plain JSONL, weighted permission scoring, prompt-injection detection, path traversal protection
  • Node.js package: AES-256-GCM encryption, HMAC-SHA256 signed tokens, SecureAuditLogger
• README — keywords block restored; RSS feed badge added (links to releases Atom feed)

No breaking changes

No API, behaviour, or runtime changes. Documentation only.

---

npm: npm install network-ai@4.0.14
Full changelog: CHANGELOG.md

v4.0.12 — OpenClaw scanner: fix documentation/bundle mismatch

v4.0.12 — OpenClaw scanner: fix documentation/bundle mismatch

## What changed

The OpenClaw scanner correctly identified a documentation/bundle mismatch introduced in earlier versions. This release fixes all three root causes:

### Fixed

- **`skill.json` runtime mismatch** — `runtime` changed from `"node"` to `"python"`; `entrypoint` changed from `"index.ts"` to `"scripts/swarm_guard.py"`. The SKILL.md instructions only call Python scripts — the Node/TS claim was incorrect.
- **`node` listed as required binary** — removed from `requires.bins` in SKILL.md. Moved to `optional_bins` with an explicit note: only needed if the user separately installs the npm MCP server (`npm install -g network-ai`). It does not run automatically.
- **Description implied full Node.js ecosystem is bundled** — `skill.json` description rewritten to accurately describe the Python-based local orchestrator. The Node.js MCP server is now explicitly called out as a separate optional npm package (`network-ai`) that is not part of this skill bundle and is not auto-fetched.
- **`install` block restructured** — Python scripts listed as `bundled / instruction-only` (nothing downloaded at install time). Node MCP server moved to `optional_node_server` key with a clear "must be installed manually" note.
- **SKILL.md scope notice** — added a prominent block at the top of the instructions section stating: Python-only execution, no automatic network calls, Node server is a separate opt-in component.

### Summary: what this skill does

All SKILL.md instructions run local Python scripts (`scripts/*.py`).  
No network calls are made by the bundled skill.  
The Node.js MCP server (`npx network-ai-server`) is a **separate optional component** — install with `npm install -g network-ai` only if you want MCP/IDE integration.

### Installation

```bash
# Python skill (this bundle — no install step required)
# Use via OpenClaw / ClawHub directly

# Optional: Node.js MCP server (separate component)
npm install -g network-ai
npx network-ai-server --port 3001

Changelog

See CHANGELOG.md for full details.