network-ai 5.8.0 → 5.8.2

package/INTEGRATION_GUIDE.md

@@ -564,4 +564,4 @@ Run these before declaring the integration production-ready:
 
 ---
 
-*Network-AI v5.8.0 · MIT License · https://github.com/Jovancoding/Network-AI*
+*Network-AI v5.8.2 · MIT License · https://github.com/Jovancoding/Network-AI*

package/README.md

@@ -5,7 +5,7 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v5.8.0-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.8.2-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
 [![Tests](https://img.shields.io/badge/tests-3136%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-29%20supported-blueviolet.svg)](#adapter-system)

package/SKILL.md

@@ -1,12 +1,22 @@
 ---
 name: network-ai
-description: "Local Python orchestration skill: multi-agent workflows via shared blackboard file, permission gating, token budget scripts, and persistent project context. All bundled scripts run locally with zero network calls and zero third-party dependencies."
+description: "Local Python orchestration skill: multi-agent workflows via shared blackboard file, permission gating, token budget scripts, and persistent project context. All bundled Python scripts run locally with zero network calls. The full npm package (npm install network-ai) additionally ships a TypeScript library, CLI, and an optional operator-started MCP SSE server that binds a TCP port."
 metadata:
   openclaw:
     emoji: "\U0001F41D"
     homepage: https://network-ai.org
-    bundle_scope: "Python scripts only (scripts/*.py). All execution is local. Only Python stdlib — no other runtimes, adapters, or CLI tools are included."
-    network_calls: "none — bundled scripts make zero network calls and spawn no subprocesses."
+    capabilities:
+      filesystem: "read/write — data/ directory only (blackboard state, audit log, active_grants.json, project-context.json). No access outside the data/ subtree."
+      env_vars: "read — NETWORK_AI_ENV (environment routing), NETWORK_AI_MCP_SECRET (MCP bearer auth), NETWORK_AI_MINIMAL (minimal-mode flag). No env vars are written."
+      shell_exec: "optional — AgentRuntime (lib/agent-runtime.ts) with SandboxPolicy and ApprovalGate; disabled by default. Never auto-enabled by this skill. auto_approve must NOT be set in production (see auto_approve_warning below)."
+      tcp_port: "optional — MCP SSE server (bin/mcp-server.ts) binds 127.0.0.1 only when explicitly started by the operator. Requires a non-empty bearer-token secret. Never auto-started by this skill or any bundled Python script."
+    bundle_scope:
+      clawhub_python_scripts: "Python stdlib only — scripts/*.py (blackboard.py, check_permission.py, context_manager.py, swarm_guard.py, token_manager.py, check_context.py). Zero network calls, zero subprocesses, zero third-party packages. This is the scope scanned by SkillSpector."
+      npm_full_package: "The npm package (npm install network-ai) adds: TypeScript library modules, CLI (bin/cli.ts), and optional MCP SSE server (bin/mcp-server.ts). The MCP SSE server exposes a TCP port and is NOT activated by installing or importing the package — it must be explicitly started by the operator."
+    network_calls:
+      python_scripts: none
+      typescript_library: "none — BYOC (bring your own client); zero outbound calls from library code; all LLM/API clients are injected by the caller"
+      mcp_sse_server: "optional — binds 127.0.0.1:<port> when explicitly started by the operator; all connections require a bearer-token secret (NETWORK_AI_MCP_SECRET); never auto-started"
     inter_agent_comms: "none — this skill does not implement, invoke, or control inter-agent messaging or sessions_send. All coordination is via local file-based blackboard only."
     sessions_send: "NOT implemented or invoked by this skill. sessions_send is a host-platform built-in entirely outside this skill's control. See data-flow notice below."
     sessions_ops: "platform-provided — outside this skill's control"
@@ -20,12 +30,13 @@ metadata:
         path: data/audit_log.jsonl
         scope: local-only
         description: "Local append-only JSONL file recording operation metadata. No data leaves the machine."
-        pii_warning: "Do not include PII, secrets, or credentials in justification fields. Log entries persist on disk."
+        pii_warning: "Do not include PII, secrets, or credentials in justification fields. Log entries persist on disk. Grant tokens are masked to a short prefix in all listing outputs; full tokens appear only at issuance time."
       data_directory:
         path: data/
         scope: local-only
         files: ["audit_log.jsonl", "active_grants.json", "project-context.json"]
         description: "All persistent state is local-only. No files are transmitted over the network."
+      auto_approve_warning: "ApprovalGate.auto_approve (lib/agent-runtime.ts) must NOT be enabled in production or untrusted environments. It is only appropriate in explicitly isolated CI/dev sandboxes where all commands executed by the runtime are known and trusted in advance."
 ---
 
 # Swarm Orchestrator Skill
@@ -713,7 +724,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Permission manifest** | `metadata.openclaw` in SKILL.md frontmatter explicitly declares `bundle_scope: "Python scripts only"`, `network_calls: none`, `requires.bins: [python3]` — no shell tools, no API credentials, no external services |
+| **Permission manifest** | `metadata.openclaw` in SKILL.md frontmatter explicitly declares `bundle_scope` (Python scripts: local-only; full npm package: includes optional MCP SSE server), `network_calls` (Python scripts: none; MCP SSE server: TCP, operator-started, bearer-token required), `requires.bins: [python3]` — no API credentials, no external services in core |
 | **Least-privilege resource gating** | `check_permission.py` uses a weighted scoring model (justification 40 %, trust 30 %, risk 30 %); PAYMENTS and FILE_EXPORT require `--confirm-high-risk` acknowledgment before any token is issued; `--scope` limits every grant to minimum required access |
 | **Abstract resource labels only** | PAYMENTS, DATABASE, EMAIL, FILE_EXPORT are local scoring labels — no external credentials exist in the skill; there is nothing to leak to an external service |
 | **HMAC-signed grant tokens** | Since v5.5.2, every grant record carries `_sig` (HMAC-SHA256 over canonical fields); `validate_token.py` rejects tampered records — privilege escalation via forged grants is detected at validation time |
@@ -726,7 +737,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Zero network calls, zero subprocesses** | All bundled Python scripts use Python stdlib only, spawn no subprocesses, and make no network calls — declared in `metadata.openclaw.network_calls: none` and `bundle_scope`; enforceable by platform inspection |
+| **Zero network calls (Python scripts)** | All bundled Python scripts use Python stdlib only, spawn no subprocesses, and make no network calls — declared in `metadata.openclaw.network_calls` and `bundle_scope`. The optional MCP SSE server (`bin/mcp-server.ts`) binds a TCP port only when explicitly started by the operator and requires a non-empty bearer-token secret. |
 | **AgentRuntime sandbox** | `ShellExecutor` enforces per-command timeout and output-size limits; `SandboxPolicy` allowlist/blocklist prevents unapproved shell commands from running at all |
 | **Source protection** | `SandboxPolicy.sourceProtection` constrains `FileAccessor.read/write/list` to `data/<env>/` only; any attempt to read outside that boundary throws `SourceProtectionError` — the agent receives `{success: false}`, no path details leak |
 | **Environment isolation** | `NETWORK_AI_ENV` / `--env` routes all state to `data/<env>/`; dev, staging, and production state are fully separated; live state (`audit_log.jsonl`, `active_grants.json`) never promotes across environments |
@@ -739,7 +750,7 @@ The following findings are drawn from the **MAESTRO Agent Security Threat** fram
 
 | Control | How Network-AI addresses it |
 |---|---|
-| **Exact version pinning** | npm `package.json` uses exact `"version": "5.8.0"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |
+| **Exact version pinning** | npm `package.json` uses exact `"version": "5.8.2"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |
 | **Zero transitive dependency drift** | All bundled Python scripts use Python stdlib only — `pip install` is never required; there are no third-party packages to drift, be compromised upstream, or introduce CVEs |
 | **Signed, tagged releases** | Every release is committed with a signed Git tag (`v5.7.x`); commit hash is verifiable against CHANGELOG.md; GitHub releases link tag → diff → changelog entry |
 | **Supply chain monitoring** | npm package continuously scored by Socket.dev (score A); any new dependency or permission change triggers an alert |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "5.8.0",
+  "version": "5.8.2",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 29 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, OpenAI Agents SDK, Vertex AI, Pydantic AI, Browser Agent, Hermes, Orchestrator, RLM + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://network-ai.org",
   "main": "dist/index.js",

package/scripts/check_permission.py

@@ -7,6 +7,12 @@
 #           data[/<env>]/.signing_key (on first run only; chmod 0o600)
 # Imports used: argparse, json, re, sys, uuid, hmac, hashlib, datetime, pathlib, typing
 # No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
+#
+# SECURITY: Justification strings supplied via --justification are logged verbatim
+# to data/audit_log.jsonl. Do NOT include PII, credentials, secret names, API keys,
+# or other sensitive business data in justification fields. Treat justifications as
+# permanently visible log entries. Grant tokens are only shown at issuance time;
+# listing commands (--active-grants) always mask tokens to a short prefix.
 """
 AuthGuardian Permission Checker
 
@@ -551,7 +557,6 @@ def list_active_grants(agent_filter: Optional[str] = None, as_json: bool = False
 
         active.append({
             "token": token[:16] + "..." if len(token) > 16 else token,
-            "token_full": token,
             "agent_id": grant.get("agent_id", "unknown"),
             "resource_type": grant.get("resource_type", "unknown"),
             "scope": grant.get("scope"),
@@ -565,7 +570,7 @@ def list_active_grants(agent_filter: Optional[str] = None, as_json: bool = False
     active.sort(key=lambda g: g["expires_at"])
 
     if as_json:
-        # In JSON mode, include full tokens
+        # Token values are masked (prefix only) — never emit full live tokens in output.
         output: dict[str, Any] = {
             "grants": active,
             "total": len(active),

package/scripts/context_manager.py

@@ -21,7 +21,7 @@ THE 3-LAYER MEMORY MODEL
 Usage:
     python context_manager.py init --name "MyProject" [--description "..."] [--version "1.0.0"]
     python context_manager.py show
-    python context_manager.py inject
+    python context_manager.py inject [--force]
     python context_manager.py update --section decisions  --add '{"decision": "...", "rationale": "..."}'
     python context_manager.py update --section milestones --complete "task name"
     python context_manager.py update --section milestones --add '{"planned": "task name"}'
@@ -33,7 +33,8 @@ Examples:
     python context_manager.py init --name "Network-AI" --description "Multi-agent swarm framework" --version "4.5.0"
     python context_manager.py update --section decisions --add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions"}'
     python context_manager.py update --section milestones --complete "v4.4.3 ClawHub clean-scan"
-    python context_manager.py inject
+    python context_manager.py inject                          # blocked if context has prompt-injection patterns
+    python context_manager.py inject --force                  # override block (trusted/CI environments only)
 """
 
 import argparse
@@ -214,7 +215,7 @@ def cmd_show(args: argparse.Namespace) -> int:  # noqa: ARG001
     return 0
 
 
-def cmd_inject(args: argparse.Namespace) -> int:  # noqa: ARG001
+def cmd_inject(args: argparse.Namespace) -> int:
     """Print a formatted block suitable for injection into an agent system prompt."""
     ctx = _load()
     warnings = _validate_context(ctx)
@@ -222,7 +223,14 @@ def cmd_inject(args: argparse.Namespace) -> int:  # noqa: ARG001
         print("[context_manager] VALIDATION WARNINGS \u2014 context has potential issues:", file=sys.stderr)
         for w in warnings:
             print(f"  ! {w}", file=sys.stderr)
-        print("[context_manager] Proceeding with inject, but review warnings above.", file=sys.stderr)
+        if not getattr(args, "force", False):
+            print(
+                "[context_manager] ERROR: Injection blocked. Context contains potential prompt-injection "
+                "content. Use --force to override (only in trusted, controlled environments).",
+                file=sys.stderr,
+            )
+            return 1
+        print("[context_manager] --force: proceeding with inject despite warnings.", file=sys.stderr)
     p = ctx.get("project", {})
 
     lines: list[str] = []
@@ -390,7 +398,12 @@ def build_parser() -> argparse.ArgumentParser:
     sub.add_parser("show", help="Print the full context as JSON")
 
     # inject
-    sub.add_parser("inject", help="Print formatted context for agent system-prompt injection")
+    p_inject = sub.add_parser("inject", help="Print formatted context for agent system-prompt injection")
+    p_inject.add_argument(
+        "--force",
+        action="store_true",
+        help="Proceed with injection even when validation warnings are present (prompt-injection risk — only use in trusted environments)",
+    )
 
     # update
     p_update = sub.add_parser("update", help="Update a specific context section")

package/scripts/swarm_guard.py

@@ -1,8 +1,13 @@
 #!/usr/bin/env python3
 # SECURITY: This script makes NO network calls and spawns NO subprocesses.
-# All I/O is local file operations only:
-#   READS:  data/swarm_budgets.json, data/heartbeats.json, data/audit_log.jsonl
-#   WRITES: data/swarm_budgets.json, data/heartbeats.json, data/audit_log.jsonl
+# All I/O is local file operations only.
+# Base data directory is data/ (root) or data/<env>/ when NETWORK_AI_ENV or --env is set.
+#   READS:  <data_dir>/swarm_budgets.json, <data_dir>/heartbeats.json,
+#           <data_dir>/audit_log.jsonl, <data_dir>/task_tracking.json,
+#           <data_dir>/agent_health.json, <data_dir>/budget_tracking.json
+#   WRITES: <data_dir>/swarm_budgets.json, <data_dir>/heartbeats.json,
+#           <data_dir>/audit_log.jsonl, <data_dir>/task_tracking.json,
+#           <data_dir>/agent_health.json, <data_dir>/budget_tracking.json
 # Imports used: argparse, json, os, sys, datetime, pathlib, typing
 # No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
 """