\r \r

Swarm Orchestrator Skill\r

\r

Scope: The bundled Python scripts (scripts/*.py) make no network calls, use only the Python standard library, and have zero third-party dependencies. Tokens are UUID-based (grant_{uuid4().hex}) stored in data/active_grants.json. Audit logging is plain JSONL (data/audit_log.jsonl).\r \r Advisory tokens notice: Grant tokens issued by check_permission.py are advisory scoring outputs only — the caller-supplied --agent identity is not cryptographically verified. Downstream systems must not treat these tokens as authenticated credentials without adding a separate identity-verification step or human approval gate, especially for PAYMENTS, DATABASE, and FILE_EXPORT resources.\r \r Data-flow notice (host platform — not this skill): This skill does NOT implement, invoke, or control sessions_send or any inter-agent messaging. All bundled Python scripts are local-only tools (budget guard, blackboard, permission scorer, context manager). If your platform has a sessions_send built-in, whether and how it is used is entirely the host platform’s responsibility and is outside this skill’s scope. If you need to prevent external network calls, disable or reroute delegation in your platform settings before installing this skill.\r \r Context file integrity: The context_manager.py inject command now validates data/project-context.json for injection patterns and oversized fields before printing the context block. Review any warnings printed to stderr before passing the output to an agent system prompt.\r \r PII / sensitive-data warning: The justification field in permission requests and the audit log (data/audit_log.jsonl) store free-text strings provided by agents. Do not include PII, secrets, or credentials in justification text. Consider restricting file permissions on data/ or running this skill in an isolated workspace.\r \r

Setup\r

\r No pip install required. All 6 scripts use Python standard library only — zero third-party packages.\r \r

Note on requirements.txt: The file exists for documentation purposes only — it lists the stdlib modules used and has no required packages. All listed deps are commented out as optional. You do not need to run pip install -r requirements.txt.\r \r

# Prerequisite: python3 (any version ≥ 3.8)\r
python3 --version\r
\r
# That's it. Run any script directly:\r
python3 scripts/blackboard.py list\r
python3 scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000\r
\r
# Optional: for cross-platform file locking on Windows production hosts\r
pip install filelock  # only needed if you see locking issues on Windows\r
```\r
\r
The `data/` directory is created automatically on first run. No configuration files, environment variables, or credentials are required.\r
\r
> **Multi-environment support (v5.4.0):** All five Python scripts now read the `NETWORK_AI_ENV` environment variable at startup and accept a `--env \x3Cname>` CLI argument. When set, all data paths are routed to `data/\x3Cenv>/` instead of the root `data/` directory. Use this to isolate dev, staging, and production state.\r
>\r
> ```bash\r
> # Run against the dev environment\r
> NETWORK_AI_ENV=dev python3 scripts/blackboard.py list\r
> python3 scripts/check_permission.py --active-grants --env dev\r
> ```\r
\r
Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.\r
\r
## 🎯 Orchestrator System Instructions\r
\r
**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:\r
\r
### Core Responsibilities\r
\r
1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks\r
2. **DELEGATE** using the budget-aware handoff protocol\r
3. **VERIFY** results on the blackboard before committing\r
4. **SYNTHESIZE** final output only after all validations pass\r
\r
### Task Decomposition Protocol\r
\r
When you receive a complex request, decompose it into exactly **3 sub-tasks**:\r
\r
```\r
┌─────────────────────────────────────────────────────────────────┐\r
│                     COMPLEX USER REQUEST                        │\r
└─────────────────────────────────────────────────────────────────┘\r
                              │\r
                              ▼\r
        ┌─────────────────────┼─────────────────────┐\r
        │                     │                     │\r
        ▼                     ▼                     ▼\r
┌───────────────┐   ┌───────────────┐   ┌───────────────┐\r
│  SUB-TASK 1   │   │  SUB-TASK 2   │   │  SUB-TASK 3   │\r
│ data_analyst  │   │ risk_assessor │   │strategy_advisor│\r
│    (DATA)     │   │   (VERIFY)    │   │  (RECOMMEND)  │\r
└───────────────┘   └───────────────┘   └───────────────┘\r
        │                     │                     │\r
        └─────────────────────┼─────────────────────┘\r
                              ▼\r
                    ┌───────────────┐\r
                    │  SYNTHESIZE   │\r
                    │ orchestrator  │\r
                    └───────────────┘\r
```\r
\r
**Decomposition Template:**\r
```\r
TASK DECOMPOSITION for: "{user_request}"\r
\r
Sub-Task 1 (DATA): [data_analyst]\r
  - Objective: Extract/process raw data\r
  - Output: Structured JSON with metrics\r
\r
Sub-Task 2 (VERIFY): [risk_assessor]  \r
  - Objective: Validate data quality & compliance\r
  - Output: Validation report with confidence score\r
\r
Sub-Task 3 (RECOMMEND): [strategy_advisor]\r
  - Objective: Generate actionable insights\r
  - Output: Recommendations with rationale\r
```\r
\r
### Budget Check Protocol\r
\r
**Run the budget interceptor before any task delegation:**\r
\r
```bash\r
# Run this before delegating to any sub-agent\r
python {baseDir}/scripts/swarm_guard.py intercept-handoff \\r
  --task-id "task_001" \\r
  --from orchestrator \\r
  --to data_analyst \\r
  --message "Analyze Q4 revenue data"\r
```\r
\r
**Decision Logic:**\r
```\r
IF result.allowed == true:\r
    → Budget check passed — proceed with the delegated task\r
    → Note tokens_spent and remaining_budget\r
ELSE:\r
    → STOP — budget exceeded or handoff limit reached\r
    → Report blocked reason to user\r
    → Consider: reduce scope or abort task\r
```\r
\r
### Pre-Commit Verification Workflow\r
\r
Before returning final results to the user:\r
\r
```bash\r
# Step 1: Check all sub-task results on blackboard\r
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"\r
python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"\r
python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"\r
\r
# Step 2: Validate each result\r
python {baseDir}/scripts/swarm_guard.py validate-result \\r
  --task-id "task_001" \\r
  --agent data_analyst \\r
  --result '{"status":"success","output":{...},"confidence":0.85}'\r
\r
# Step 3: Supervisor review (checks all issues)\r
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"\r
\r
# Step 4: Only if APPROVED, commit final state\r
python {baseDir}/scripts/blackboard.py write "task:001:final" \\r
  '{"status":"SUCCESS","output":{...}}'\r
```\r
\r
**Verdict Handling:**\r
| Verdict | Action |\r
|---------|--------|\r
| `APPROVED` | Commit and return results to user |\r
| `WARNING` | Review issues, fix if possible, then commit |\r
| `BLOCKED` | Do NOT return results. Report failure. |\r
\r
---\r
\r
## The 3-Layer Memory Model\r
\r
Every agent in the swarm operates with three memory layers, each with a different scope and lifetime:\r
\r
| Layer | Name | Lifetime | Managed by |\r
|-------|------|----------|------------|\r
| **1** | Agent context | Ephemeral — current task only | Platform (per-session) |\r
| **2** | Blackboard | TTL-scoped — shared across agents | `scripts/blackboard.py` |\r
| **3** | Project context | Persistent — survives all sessions | `scripts/context_manager.py` |\r
\r
### Layer 1 — Agent Context\r
Each agent's own context window: the current task instructions, conversation history, and immediate working memory. Managed automatically by the OpenClaw/LLM platform. Nothing to configure.\r
\r
### Layer 2 — Blackboard (Shared Coordination State)\r
A shared markdown file (`swarm-blackboard.md`) for real-time cross-agent coordination: task results, grant tokens, status flags, and TTL-scoped cache entries. Agents read and write via `scripts/blackboard.py`. Entries expire automatically.\r
\r
### Layer 3 — Project Context (Persistent Long-Term Memory)\r
A JSON file (`data/project-context.json`) that holds information every agent should know, regardless of what session or task is running:\r
- **Goals** — long-term objectives of the project\r
- **Tech stack** — languages, frameworks, infrastructure\r
- **Milestones** — completed, in-progress, and planned work\r
- **Architecture decisions** — design choices and their rationales\r
- **Banned approaches** — approaches that have been ruled out\r
\r
#### Initialising Project Context\r
\r
```bash\r
python {baseDir}/scripts/context_manager.py init \\r
  --name "MyProject" \\r
  --description "Multi-agent workflow automation" \\r
  --version "1.0.0"\r
```\r
\r
#### Injecting Context into an Agent System Prompt\r
\r
```bash\r
python {baseDir}/scripts/context_manager.py inject\r
```\r
\r
Copy the output block to the top of your agent's system prompt. Every agent that receives this block shares the same long-term project awareness.\r
\r
#### Recording a Decision\r
\r
```bash\r
python {baseDir}/scripts/context_manager.py update \\r
  --section decisions \\r
  --add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions in parallel agents"}'\r
```\r
\r
#### Updating Milestones\r
\r
```bash\r
# Mark a milestone complete\r
python {baseDir}/scripts/context_manager.py update \\r
  --section milestones --complete "Ship v2.0"\r
\r
# Add a planned milestone\r
python {baseDir}/scripts/context_manager.py update \\r
  --section milestones --add '{"planned": "Integrate vector memory"}'\r
```\r
\r
#### Setting the Tech Stack\r
\r
```bash\r
python {baseDir}/scripts/context_manager.py update \\r
  --section stack \\r
  --set '{"language": "Python", "runtime": "Python 3.11", "framework": "SwarmOrchestrator"}'\r
```\r
\r
#### Banning an Approach\r
\r
```bash\r
python {baseDir}/scripts/context_manager.py update \\r
  --section banned \\r
  --add "Direct database writes from agent scripts (use permission gating)"\r
```\r
\r
---\r
\r
## When to Use This Skill\r
\r
- **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)\r
- **Parallel Execution**: Run multiple agents simultaneously and synthesize results\r
- **Permission Wall**: Gate access to DATABASE, PAYMENTS, EMAIL, or FILE_EXPORT operations (abstract local resource types — no external credentials required)\r
- **Shared Blackboard**: Coordinate agent state via persistent markdown file\r
\r
## Quick Start\r
\r
### 1. Initialize Budget (FIRST!)\r
\r
**Always initialize a budget before any multi-agent task:**\r
\r
```bash\r
python {baseDir}/scripts/swarm_guard.py budget-init \\r
  --task-id "task_001" \\r
  --budget 10000 \\r
  --description "Q4 Financial Analysis"\r
```\r
\r
### 2. Check Budget Before Task Delegation\r
\r
\r
Always run the budget guard before delegating any task:\r
\r
```bash\r
# 1. Check budget (this skill's Python script)\r
python {baseDir}/scripts/swarm_guard.py intercept-handoff \\r
  --task-id "task_001" --from orchestrator --to data_analyst \\r
  --message "Analyze Q4 revenue data"\r
\r
# 2. If result.allowed == true, proceed with delegation via your platform's built-in tools.\r
# If result.allowed == false, stop — budget exceeded or handoff limit reached.\r
```\r
\r
### 3. Check Permission Before API Access\r
\r
Before accessing SAP or Financial APIs, evaluate the request:\r
\r
```bash\r
# Run the permission checker script\r
python {baseDir}/scripts/check_permission.py \\r
  --agent "data_analyst" \\r
  --resource "DATABASE" \\r
  --justification "Need Q4 invoice data for quarterly report" \\r
  --scope "read:invoices"\r
```\r
\r
The script will output a grant token if approved, or denial reason if rejected.\r
\r
### 4. Use the Shared Blackboard\r
\r
Read/write coordination state:\r
\r
```bash\r
# Write to blackboard\r
python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'\r
\r
# Read from blackboard  \r
python {baseDir}/scripts/blackboard.py read "task:q4_analysis"\r
\r
# List all entries\r
python {baseDir}/scripts/blackboard.py list\r
```\r
\r
## Agent-to-Agent Handoff Protocol\r
\r
When delegating tasks between agents, always run the budget guard first.\r
\r
### Step 1: Initialize Budget & Check Capacity\r
```bash\r
# Initialize budget (if not already done)\r
python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000\r
\r
# Check current status\r
python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"\r
```\r
\r
### Step 2: Identify Target Agent\r
\r
Common agent types:\r
| Agent | Specialty |\r
|-------|-----------|\r
| `data_analyst` | Data processing, SQL, analytics |\r
| `strategy_advisor` | Business strategy, recommendations |\r
| `risk_assessor` | Risk analysis, compliance checks |\r
| `orchestrator` | Coordination, task decomposition |\r
\r
### Step 3: Run Budget Guard Before Delegation\r
\r
```bash\r
# Check budget AND handoff limits before delegating\r
python {baseDir}/scripts/swarm_guard.py intercept-handoff \\r
  --task-id "task_001" \\r
  --from orchestrator \\r
  --to data_analyst \\r
  --message "Analyze Q4 data" \\r
  --artifact  # Include if expecting output\r
```\r
\r
**If ALLOWED:** Proceed with delegation via your platform's own tools\r
**If BLOCKED:** Stop — budget exceeded or handoff limit reached; do not delegate\r
\r
### Step 4: Construct Handoff Message\r
\r
Include these fields in your delegation:\r
- **instruction**: Clear task description\r
- **context**: Relevant background information\r
- **constraints**: Any limitations or requirements\r
- **expectedOutput**: What format/content you need back\r
\r
### Step 5: Check Results\r
\r
After delegation completes, read results from the blackboard:\r
\r
```bash\r
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"\r
```\r
\r
## Permission Scoring\r
\r
> **Tokens are audit scoring outputs only.** Grant tokens from `check_permission.py` are NOT authenticated credentials and must NOT be used as real access control. They are advisory hints based on a local scoring model. Require a separate authenticated identity and explicit human approval before accessing PAYMENTS, DATABASE, or FILE_EXPORT resources.\r
\r
**Always score permission before accessing:**\r
- `DATABASE` — Internal database / data store (abstract label — no external credentials)\r
- `PAYMENTS` — Financial/payment data services (abstract label — requires `--confirm-high-risk`)\r
- `EMAIL` — Email sending capability (abstract label)\r
- `FILE_EXPORT` — Exporting data to local files (abstract label — requires `--confirm-high-risk`)\r
\r
> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all evaluation runs locally.\r
\r
### Permission Evaluation Criteria\r
\r
| Factor | Weight | Criteria |\r
|--------|--------|----------|\r
| Justification | 40% | Must explain specific task need |\r
| Trust Level | 30% | Agent's established trust score |\r
| Risk Assessment | 30% | Resource sensitivity + scope breadth |\r
\r
### Using the Permission Script\r
\r
```bash\r
# Request permission\r
python {baseDir}/scripts/check_permission.py \\r
  --agent "your_agent_id" \\r
  --resource "PAYMENTS" \\r
  --justification "Generating quarterly financial summary for board presentation" \\r
  --scope "read:revenue,read:expenses"\r
\r
# Output if approved:\r
# ✅ GRANTED\r
# Token: grant_a1b2c3d4e5f6\r
# Expires: 2026-02-04T15:30:00Z\r
# Restrictions: read_only, no_pii_fields, audit_required\r
\r
# Output if denied:\r
# ❌ DENIED\r
# Reason: Justification is insufficient. Please provide specific task context.\r
```\r
\r
### Restriction Types\r
\r
| Resource | Default Restrictions |\r
|----------|---------------------|\r
| DATABASE | `read_only`, `max_records:100` |\r
| PAYMENTS | `read_only`, `no_pii_fields`, `audit_required` |\r
| EMAIL | `rate_limit:10_per_minute` |\r
| FILE_EXPORT | `anonymize_pii`, `local_only` |\r
\r
## Shared Blackboard Pattern\r
\r
The blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:\r
\r
```markdown\r
# Swarm Blackboard\r
Last Updated: 2026-02-04T10:30:00Z\r
\r
## Knowledge Cache\r
### task:q4_analysis\r
{"status": "completed", "result": {...}, "agent": "data_analyst"}\r
\r
### cache:revenue_summary  \r
{"q4_total": 1250000, "growth": 0.15}\r
```\r
\r
### Blackboard Operations\r
\r
```bash\r
# Write with TTL (expires after 1 hour)\r
python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600\r
\r
# Read (returns null if expired)\r
python {baseDir}/scripts/blackboard.py read "cache:temp_data"\r
\r
# Delete\r
python {baseDir}/scripts/blackboard.py delete "cache:temp_data"\r
\r
# Get full snapshot\r
python {baseDir}/scripts/blackboard.py snapshot\r
```\r
\r
## Parallel Execution\r
\r
For tasks requiring multiple agent perspectives:\r
\r
### Strategy 1: Merge (Default)\r
Combine all agent outputs into unified result.\r
```\r
Ask data_analyst AND strategy_advisor to both analyze the dataset.\r
Merge their insights into a comprehensive report.\r
```\r
\r
### Strategy 2: Vote\r
Use when you need consensus - pick the result with highest confidence.\r
\r
### Strategy 3: First-Success\r
Use for redundancy - take first successful result.\r
\r
### Strategy 4: Chain\r
Sequential processing - output of one feeds into next.\r
\r
> **TypeScript engine (v4.15.0):** These strategies map directly to the `FanOutFanIn` module (`lib/fan-out.ts`) which provides `merge`, `vote`, `firstSuccess`, and `consensus` fan-in strategies with concurrency control. For multi-phase workflows with approval gates, see `PhasePipeline` (`lib/phase-pipeline.ts`). For result scoring and threshold filtering, see `ConfidenceFilter` (`lib/confidence-filter.ts`). Matcher-based hooks (`lib/adapter-hooks.ts`) can target specific agents or tools via glob patterns. For sandboxed agent execution, see `AgentRuntime` (`lib/agent-runtime.ts`). For large-scale agent coordination, see `StrategyAgent` (`lib/strategy-agent.ts`).\r
\r
### Example Parallel Workflow\r
\r
```\r
# For each delegation below, first run the budget guard:\r
#   python {baseDir}/scripts/swarm_guard.py intercept-handoff --task-id "task_001" --from orchestrator --to \x3Cagent> --message "\x3Ctask>"\r
# If result.allowed == true, delegate via your platform's own tools.\r
1. Delegate to data_analyst: "Extract key metrics from Q4 data"\r
2. Delegate to risk_assessor: "Identify compliance risks in Q4 data"\r
3. Delegate to strategy_advisor: "Recommend actions based on Q4 trends"\r
4. Wait for all results and read them from the blackboard\r
5. Synthesize: Combine metrics + risks + recommendations into executive summary\r
```\r
\r
## Security Considerations\r
\r
1. **Never bypass the permission wall** for gated resources\r
2. **Always include justification** explaining the business need\r
3. **Use minimal scope** - request only what you need\r
4. **Check token expiry** - tokens are valid for 5 minutes\r
5. **Validate tokens** - use `python {baseDir}/scripts/validate_token.py TOKEN` to verify grant tokens before use\r
6. **Audit trail** - all permission requests are logged\r
\r
## 📝 Audit Trail Requirements (MANDATORY)\r
\r
**Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.\r
\r
> **Privacy note:** Audit log entries contain agent-provided free-text fields (justifications, descriptions). These are stored locally in `data/audit_log.jsonl` and never transmitted over the network by this skill. However, **do not put PII, passwords, or API keys in justification strings** — they persist on disk. Consider periodic log rotation and restricting OS file permissions on the `data/` directory.\r
\r
### What Gets Logged Automatically\r
\r
The scripts automatically log these events:\r
- `permission_granted` - When access is approved\r
- `permission_denied` - When access is rejected\r
- `permission_revoked` - When a token is manually revoked\r
- `ttl_cleanup` - When expired tokens are purged\r
- `result_validated` / `result_rejected` - Swarm Guard validations\r
\r
### Log Entry Format\r
\r
```json\r
{\r
  "timestamp": "2026-02-04T10:30:00+00:00",\r
  "action": "permission_granted",\r
  "details": {\r
    "agent_id": "data_analyst",\r
    "resource_type": "DATABASE",\r
    "justification": "Q4 revenue analysis",\r
    "token": "grant_abc123...",\r
    "restrictions": ["read_only", "max_records:100"]\r
  }\r
}\r
```\r
\r
### Reading the Audit Log\r
\r
```bash\r
# View recent entries (last 10)\r
tail -10 {baseDir}/data/audit_log.jsonl\r
\r
# Search for specific agent\r
grep "data_analyst" {baseDir}/data/audit_log.jsonl\r
\r
# Count actions by type\r
cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c\r
```\r
\r
### Custom Audit Entries\r
\r
If you perform a sensitive action manually, log it:\r
\r
```python\r
import json\r
from datetime import datetime, timezone\r
from pathlib import Path\r
\r
audit_file = Path("{baseDir}/data/audit_log.jsonl")\r
entry = {\r
    "timestamp": datetime.now(timezone.utc).isoformat(),\r
    "action": "manual_data_access",\r
    "details": {\r
        "agent": "orchestrator",\r
        "description": "Direct database query for debugging",\r
        "justification": "Investigating data sync issue #1234"\r
    }\r
}\r
with open(audit_file, "a") as f:\r
    f.write(json.dumps(entry) + "\
")\r
```\r
\r
## 🧹 TTL Enforcement (Token Lifecycle)\r
\r
Expired permission tokens are automatically tracked. Run periodic cleanup:\r
\r
```bash\r
# Validate a grant token\r
python {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6\r
\r
# List expired tokens (without removing)\r
python {baseDir}/scripts/revoke_token.py --list-expired\r
\r
# Remove all expired tokens\r
python {baseDir}/scripts/revoke_token.py --cleanup\r
\r
# Output:\r
# 🧹 TTL Cleanup Complete\r
#    Removed: 3 expired token(s)\r
#    Remaining active grants: 2\r
```\r
\r
**Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.\r
\r
## ⚠️ Swarm Guard: Preventing Common Failures\r
\r
Two critical issues can derail multi-agent swarms:\r
\r
### 1. The Handoff Tax 💸\r
\r
**Problem**: Agents waste tokens "talking about" work instead of doing it.\r
\r
**Prevention**:\r
```bash\r
# Before each handoff, check your budget:\r
python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"\r
\r
# Output:\r
# 🟢 Task: task_001\r
#    Handoffs: 1/3\r
#    Remaining: 2\r
#    Action Ratio: 100%\r
```\r
\r
**Rules enforced**:\r
- **Max 3 handoffs per task** - After 3, produce output or abort\r
- **Max 500 chars per message** - Be concise: instruction + constraints + expected output\r
- **60% action ratio** - At least 60% of handoffs must produce artifacts\r
- **2-minute planning limit** - No output after 2min = timeout\r
\r
```bash\r
# Record a handoff (with tax checking):\r
python {baseDir}/scripts/swarm_guard.py record-handoff \\r
  --task-id "task_001" \\r
  --from orchestrator \\r
  --to data_analyst \\r
  --message "Analyze sales data, output JSON summary" \\r
  --artifact  # Include if this handoff produces output\r
```\r
\r
### 2. Silent Failure Detection 👻\r
\r
**Problem**: One agent fails silently, others keep working on bad data.\r
\r
**Prevention - Heartbeats**:\r
```bash\r
# Agents must send heartbeats while working:\r
python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"\r
\r
# Check if an agent is healthy:\r
python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst\r
\r
# Output if healthy:\r
# 💚 Agent 'data_analyst' is HEALTHY\r
#    Last seen: 15s ago\r
\r
# Output if failed:\r
# 💔 Agent 'data_analyst' is UNHEALTHY\r
#    Reason: STALE_HEARTBEAT\r
#    → Do NOT use any pending results from this agent.\r
```\r
\r
**Prevention - Result Validation**:\r
```bash\r
# Before using another agent's result, validate it:\r
python {baseDir}/scripts/swarm_guard.py validate-result \\r
  --task-id "task_001" \\r
  --agent data_analyst \\r
  --result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'\r
\r
# Output:\r
# ✅ RESULT VALID\r
#    → APPROVED - Result can be used by other agents\r
```\r
\r
**Required result fields**: `status`, `output`, `confidence`\r
\r
### Supervisor Review\r
\r
Before finalizing any task, run supervisor review:\r
```bash\r
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"\r
\r
# Output:\r
# ✅ SUPERVISOR VERDICT: APPROVED\r
#    Task: task_001\r
#    Age: 1.5 minutes\r
#    Handoffs: 2\r
#    Artifacts: 2\r
```\r
\r
**Verdicts**:\r
- `APPROVED` - Task healthy, results usable\r
- `WARNING` - Issues detected, review recommended\r
- `BLOCKED` - Critical failures, do NOT use results\r
\r
## Troubleshooting\r
\r
### Permission Denied\r
- Provide more specific justification (mention task, purpose, expected outcome)\r
- Narrow the requested scope\r
- Check agent trust level\r
\r
### Blackboard Read Returns Null\r
- Entry may have expired (check TTL)\r
- Key may be misspelled\r
- Entry was never written\r
\r
### Session Not Found\r
- Run `sessions_list` (OpenClaw platform built-in) to see available sessions\r
- Session may need to be started first\r
\r
## Security Framework Assessment (MAESTRO / OWASP AST)\r
\r
The following findings are drawn from the **MAESTRO Agent Security Threat** framework (OWASP LLM / ASVS mapping). They are addressed by existing architectural controls in Network-AI — not open vulnerabilities.\r
\r
### AST03 — Over-Privileged Skills · Severity: High\r
\r
> *Skills are granted broader permissions than their stated function requires, creating excessive blast radius if prompt-injected.*\r
\r
| Control | How Network-AI addresses it |\r
|---|---|\r
| **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 |\r
| **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 |\r
| **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 |\r
| **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 |\r
| **SandboxPolicy + FileAccessor** | AgentRuntime's `SandboxPolicy` enforces command allowlists/blocklists; `FileAccessor` restricts all file I/O to `data/\x3Cenv>/`; out-of-scope access throws `SourceProtectionError` and returns `{success: false}` without leaking path details |\r
| **Advisory-only tokens** | All grant tokens are explicitly marked `advisory: true`; downstream systems must add a separate authenticated identity check and human approval before any real sensitive action — documented in frontmatter and throughout SKILL.md |\r
\r
### AST06 — Weak Isolation · Severity: High\r
\r
> *Skills execute in the host agent's security context with full filesystem, shell, and network access.*\r
\r
| Control | How Network-AI addresses it |\r
|---|---|\r
| **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. |\r
| **AgentRuntime sandbox** | `ShellExecutor` enforces per-command timeout and output-size limits; `SandboxPolicy` allowlist/blocklist prevents unapproved shell commands from running at all |\r
| **ClaimVerifier (Tier 1 agent honesty)** | `AgentRuntime` issues HMAC-signed outcome-bound receipts (`ExecutionReceipt`) on every `exec()` and `writeFile()`; `ClaimVerifier` (`lib/claim-verifier.ts`) reconciles agent-declared manifests against the audit log — `UNSUPPORTED_CLAIM` and `UNDISCLOSED_ACTION` violations surface through `ComplianceMonitor`; repeated fabrication decays `AuthGuardian` trust and forces `ApprovalGate` supervision |\r
| **Source protection** | `SandboxPolicy.sourceProtection` constrains `FileAccessor.read/write/list` to `data/\x3Cenv>/` only; any attempt to read outside that boundary throws `SourceProtectionError` — the agent receives `{success: false}`, no path details leak |\r
| **Environment isolation** | `NETWORK_AI_ENV` / `--env` routes all state to `data/\x3Cenv>/`; dev, staging, and production state are fully separated; live state (`audit_log.jsonl`, `active_grants.json`) never promotes across environments |\r
| **ApprovalGate** | High-risk shell or file operations require explicit human or callback approval before execution; auto-approve only in explicitly trusted environments |\r
| **No hot-reload surface** | Bundled scripts do not implement or respond to a SkillsWatcher; skill updates require explicit `clawhub install` or `npm install` — no mid-session reload is possible |\r
\r
### AST07 — Update Drift · Severity: Medium\r
\r
> *Installed skills drift out of sync — either unpatched (leaving known CVEs open) or blindly auto-updated (potentially receiving malicious patches).*\r
\r
| Control | How Network-AI addresses it |\r
|---|---|\r
| **Exact version pinning** | npm `package.json` uses exact `"version": "5.11.0"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |\r
| **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 |\r
| **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 |\r
| **Supply chain monitoring** | npm package continuously scored by Socket.dev (score A); any new dependency or permission change triggers an alert |\r
| **No auto-update mechanism** | Updates require explicit user action (`clawhub install`, `npm install network-ai@latest`); there is no background updater or hot-reload path |\r
| **CHANGELOG.md audit trail** | Every change — including docs-only patches — is tracked with version, date, and rationale; operators can diff any two versions to assess update risk before applying |\r
\r
## Security Scan Findings (ClawHub)\r
\r
This skill is scanned on every publish. The following Notes are flagged by design and will recur on every scan. They are acknowledged and mitigated with documented controls — they are not bugs or vulnerabilities.\r
\r
| Finding | Severity | Why it recurs | Documented control |\r
|---------|----------|---------------|--------------------|  \r
| **ASI01** Agent Goal Hijack | High | Orchestrator skill performs multi-step decomposition and delegation by design | Use this skill only when multi-agent orchestration is desired; for simple requests the scope guard responds directly without decomposing |\r
| **ASI03** Identity and Privilege Abuse (advisory tokens) | Medium | Grant tokens are advisory scoring outputs only — caller-supplied `--agent` identity is not cryptographically verified; skill explicitly warns tokens must not be used as real authorization for PAYMENTS, DATABASE, or FILE_EXPORT | Tokens are explicitly marked advisory in SKILL.md and source; require separate platform auth and human approval before any real database, payment, email, or export action |\r
| **ASI03** Identity and Privilege Abuse (local grant state) | Low | The permission system creates persistent local state (`active_grants.json`, `audit_log.jsonl`, `.signing_key`) — security-relevant files that are purpose-aligned but accessible to anyone with `data/` access | Keep the skill directory private; back up or delete local grant state when no longer needed; do not share `data/` casually; restrict OS-level permissions on `data/` on shared machines |\r
| **ASI03** Identity and Privilege Abuse (token integrity) | ~~High~~ Resolved | Token payload had no integrity protection — active_grants.json could be edited to forge elevated grants | Fixed in v5.5.2 — `check_permission.py` HMAC-SHA256 signs each grant (`_sig` field, stdlib `hmac`+`hashlib`, key at `data/.signing_key`); `validate_token.py` verifies before accepting; tampered tokens rejected with `"Token signature invalid"` |\r
| **ASI03** Identity and Privilege Abuse (env-scoped paths) | ~~High~~ Resolved | `revoke_token.py` resolved `GRANTS_FILE`/`AUDIT_LOG` at module load from root `data/`, ignoring `NETWORK_AI_ENV` — revoking tokens in one env could silently miss env-specific grant files | Fixed in v5.5.1 — `_resolve_data_dir()` added, `--env` CLI argument introduced, paths re-resolved in `main()` before file I/O; consistent with `check_permission.py` and `validate_token.py` |\r
| **ASI06** Memory and Context Poisoning (project context) | Medium | Persistent `data/project-context.json` is injected into every agent session by design — inaccurate or malicious context could steer future agent behavior | `_validate_context()` runs injection-pattern detection before every inject; do not store secrets/credentials; review `data/project-context.json` before use; clear `data/` between projects |\r
| **ASI06** Memory and Context Poisoning (audit log free text) | Low | `justification` field in permission requests and `data/audit_log.jsonl` store agent-provided free-text strings locally — PII or secrets placed there will persist on disk | Do not include PII, secrets, or credentials in justification text; restrict access to `data/` on shared machines; rotate/delete `audit_log.jsonl` when no longer needed |\r
| **ASI07** Insecure Inter-Agent Communication | High | Blackboard is local file-based; origin/identity depends on local file access, not authenticated messaging | Run in a trusted workspace; restrict file permissions on `data/`; review blackboard changes before relying on them for important decisions |\r
| **ASI08** Cascading Failures | ~~High~~ Resolved | `os` was referenced before import in `swarm_guard.py` — fixed in v5.4.4; `import os` now present | Fixed — `swarm_guard.py` now imports `os` at module level; budget/health guard starts correctly |\r
| **SkillSpector** Intent-Code Divergence (`FILE_EXPORT` missing from `HIGH_RISK_RESOURCES`) | ~~Low~~ Resolved | Comment stated `FILE_EXPORT` requires `--confirm-high-risk` but `HIGH_RISK_RESOURCES` only contained `PAYMENTS` and `DATABASE`; file export requests could receive advisory grants without the extra acknowledgment | Fixed in v5.11.0 — `FILE_EXPORT` added to `HIGH_RISK_RESOURCES` in `check_permission.py`; now requires `--confirm-high-risk` consistent with the documented policy |\r
| **SkillSpector** Description-Behavior Mismatch (`ensure_data_dir()` ignoring env scope) | ~~Medium~~ Resolved | `ensure_data_dir()` always created the fixed top-level `data/` directory instead of the active env-specific path, breaking environment isolation when `NETWORK_AI_ENV` is set | Fixed in v5.11.0 — `ensure_data_dir()` now delegates to `_resolve_data_dir()` so audit log and grant files are always written to the correct env-scoped directory |\r
\r
## References\r
\r
This skill is part of the larger [Network-AI](https://github.com/Jovancoding/Network-AI) project. See the repository for full documentation on the permission system, blackboard schema, and trust-level calculations.\r