network-ai 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/QUICKSTART.md +260 -0
  3. package/README.md +604 -0
  4. package/SKILL.md +568 -0
  5. package/dist/adapters/adapter-registry.d.ts +94 -0
  6. package/dist/adapters/adapter-registry.d.ts.map +1 -0
  7. package/dist/adapters/adapter-registry.js +355 -0
  8. package/dist/adapters/adapter-registry.js.map +1 -0
  9. package/dist/adapters/agno-adapter.d.ts +112 -0
  10. package/dist/adapters/agno-adapter.d.ts.map +1 -0
  11. package/dist/adapters/agno-adapter.js +140 -0
  12. package/dist/adapters/agno-adapter.js.map +1 -0
  13. package/dist/adapters/autogen-adapter.d.ts +67 -0
  14. package/dist/adapters/autogen-adapter.d.ts.map +1 -0
  15. package/dist/adapters/autogen-adapter.js +141 -0
  16. package/dist/adapters/autogen-adapter.js.map +1 -0
  17. package/dist/adapters/base-adapter.d.ts +51 -0
  18. package/dist/adapters/base-adapter.d.ts.map +1 -0
  19. package/dist/adapters/base-adapter.js +103 -0
  20. package/dist/adapters/base-adapter.js.map +1 -0
  21. package/dist/adapters/crewai-adapter.d.ts +72 -0
  22. package/dist/adapters/crewai-adapter.d.ts.map +1 -0
  23. package/dist/adapters/crewai-adapter.js +148 -0
  24. package/dist/adapters/crewai-adapter.js.map +1 -0
  25. package/dist/adapters/custom-adapter.d.ts +74 -0
  26. package/dist/adapters/custom-adapter.d.ts.map +1 -0
  27. package/dist/adapters/custom-adapter.js +142 -0
  28. package/dist/adapters/custom-adapter.js.map +1 -0
  29. package/dist/adapters/dspy-adapter.d.ts +70 -0
  30. package/dist/adapters/dspy-adapter.d.ts.map +1 -0
  31. package/dist/adapters/dspy-adapter.js +127 -0
  32. package/dist/adapters/dspy-adapter.js.map +1 -0
  33. package/dist/adapters/haystack-adapter.d.ts +83 -0
  34. package/dist/adapters/haystack-adapter.d.ts.map +1 -0
  35. package/dist/adapters/haystack-adapter.js +149 -0
  36. package/dist/adapters/haystack-adapter.js.map +1 -0
  37. package/dist/adapters/index.d.ts +47 -0
  38. package/dist/adapters/index.d.ts.map +1 -0
  39. package/dist/adapters/index.js +56 -0
  40. package/dist/adapters/index.js.map +1 -0
  41. package/dist/adapters/langchain-adapter.d.ts +51 -0
  42. package/dist/adapters/langchain-adapter.d.ts.map +1 -0
  43. package/dist/adapters/langchain-adapter.js +134 -0
  44. package/dist/adapters/langchain-adapter.js.map +1 -0
  45. package/dist/adapters/llamaindex-adapter.d.ts +89 -0
  46. package/dist/adapters/llamaindex-adapter.d.ts.map +1 -0
  47. package/dist/adapters/llamaindex-adapter.js +135 -0
  48. package/dist/adapters/llamaindex-adapter.js.map +1 -0
  49. package/dist/adapters/mcp-adapter.d.ts +90 -0
  50. package/dist/adapters/mcp-adapter.d.ts.map +1 -0
  51. package/dist/adapters/mcp-adapter.js +200 -0
  52. package/dist/adapters/mcp-adapter.js.map +1 -0
  53. package/dist/adapters/openai-assistants-adapter.d.ts +94 -0
  54. package/dist/adapters/openai-assistants-adapter.d.ts.map +1 -0
  55. package/dist/adapters/openai-assistants-adapter.js +130 -0
  56. package/dist/adapters/openai-assistants-adapter.js.map +1 -0
  57. package/dist/adapters/openclaw-adapter.d.ts +21 -0
  58. package/dist/adapters/openclaw-adapter.d.ts.map +1 -0
  59. package/dist/adapters/openclaw-adapter.js +140 -0
  60. package/dist/adapters/openclaw-adapter.js.map +1 -0
  61. package/dist/adapters/semantic-kernel-adapter.d.ts +73 -0
  62. package/dist/adapters/semantic-kernel-adapter.d.ts.map +1 -0
  63. package/dist/adapters/semantic-kernel-adapter.js +123 -0
  64. package/dist/adapters/semantic-kernel-adapter.js.map +1 -0
  65. package/dist/index.d.ts +379 -0
  66. package/dist/index.d.ts.map +1 -0
  67. package/dist/index.js +1428 -0
  68. package/dist/index.js.map +1 -0
  69. package/dist/lib/blackboard-validator.d.ts +205 -0
  70. package/dist/lib/blackboard-validator.d.ts.map +1 -0
  71. package/dist/lib/blackboard-validator.js +756 -0
  72. package/dist/lib/blackboard-validator.js.map +1 -0
  73. package/dist/lib/locked-blackboard.d.ts +174 -0
  74. package/dist/lib/locked-blackboard.d.ts.map +1 -0
  75. package/dist/lib/locked-blackboard.js +654 -0
  76. package/dist/lib/locked-blackboard.js.map +1 -0
  77. package/dist/lib/swarm-utils.d.ts +136 -0
  78. package/dist/lib/swarm-utils.d.ts.map +1 -0
  79. package/dist/lib/swarm-utils.js +510 -0
  80. package/dist/lib/swarm-utils.js.map +1 -0
  81. package/dist/security.d.ts +269 -0
  82. package/dist/security.d.ts.map +1 -0
  83. package/dist/security.js +713 -0
  84. package/dist/security.js.map +1 -0
  85. package/package.json +84 -0
  86. package/scripts/blackboard.py +819 -0
  87. package/scripts/check_permission.py +331 -0
  88. package/scripts/revoke_token.py +243 -0
  89. package/scripts/swarm_guard.py +1140 -0
  90. package/scripts/validate_token.py +97 -0
  91. package/types/agent-adapter.d.ts +244 -0
  92. package/types/openclaw-core.d.ts +52 -0
package/SKILL.md ADDED
@@ -0,0 +1,568 @@
1
+ ---
2
+ name: swarm-orchestrator
3
+ description: Multi-agent swarm orchestration for complex workflows. Use when coordinating multiple agents, delegating tasks between sessions, managing shared state via blackboard, or enforcing permission walls for DATABASE/PAYMENTS/EMAIL access. Triggers on: agent coordination, task delegation, parallel execution, permission requests, blackboard state management.
4
+ metadata: { "openclaw": { "emoji": "🐝", "homepage": "https://github.com/jovanSAPFIONEER/Network-AI" } }
5
+ ---
6
+
7
+ # Swarm Orchestrator Skill
8
+
9
+ Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.
10
+
11
+ ## 🎯 Orchestrator System Instructions
12
+
13
+ **You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:
14
+
15
+ ### Core Responsibilities
16
+
17
+ 1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks
18
+ 2. **DELEGATE** using the budget-aware handoff protocol
19
+ 3. **VERIFY** results on the blackboard before committing
20
+ 4. **SYNTHESIZE** final output only after all validations pass
21
+
22
+ ### Task Decomposition Protocol
23
+
24
+ When you receive a complex request, decompose it into exactly **3 sub-tasks**:
25
+
26
+ ```
27
+ ┌─────────────────────────────────────────────────────────────────┐
28
+ │ COMPLEX USER REQUEST │
29
+ └─────────────────────────────────────────────────────────────────┘
30
+
31
+
32
+ ┌─────────────────────┼─────────────────────┐
33
+ │ │ │
34
+ ▼ ▼ ▼
35
+ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
36
+ │ SUB-TASK 1 │ │ SUB-TASK 2 │ │ SUB-TASK 3 │
37
+ │ data_analyst │ │ risk_assessor │ │strategy_advisor│
38
+ │ (DATA) │ │ (VERIFY) │ │ (RECOMMEND) │
39
+ └───────────────┘ └───────────────┘ └───────────────┘
40
+ │ │ │
41
+ └─────────────────────┼─────────────────────┘
42
+
43
+ ┌───────────────┐
44
+ │ SYNTHESIZE │
45
+ │ orchestrator │
46
+ └───────────────┘
47
+ ```
48
+
49
+ **Decomposition Template:**
50
+ ```
51
+ TASK DECOMPOSITION for: "{user_request}"
52
+
53
+ Sub-Task 1 (DATA): [data_analyst]
54
+ - Objective: Extract/process raw data
55
+ - Output: Structured JSON with metrics
56
+
57
+ Sub-Task 2 (VERIFY): [risk_assessor]
58
+ - Objective: Validate data quality & compliance
59
+ - Output: Validation report with confidence score
60
+
61
+ Sub-Task 3 (RECOMMEND): [strategy_advisor]
62
+ - Objective: Generate actionable insights
63
+ - Output: Recommendations with rationale
64
+ ```
65
+
66
+ ### Budget-Aware Handoff Protocol
67
+
68
+ **CRITICAL:** Before EVERY `sessions_send`, call the handoff interceptor:
69
+
70
+ ```bash
71
+ # ALWAYS run this BEFORE sessions_send
72
+ python {baseDir}/scripts/swarm_guard.py intercept-handoff \
73
+ --task-id "task_001" \
74
+ --from orchestrator \
75
+ --to data_analyst \
76
+ --message "Analyze Q4 revenue data"
77
+ ```
78
+
79
+ **Decision Logic:**
80
+ ```
81
+ IF result.allowed == true:
82
+ → Proceed with sessions_send
83
+ → Note tokens_spent and remaining_budget
84
+ ELSE:
85
+ → STOP - Do NOT call sessions_send
86
+ → Report blocked reason to user
87
+ → Consider: reduce scope or abort task
88
+ ```
89
+
90
+ ### Pre-Commit Verification Workflow
91
+
92
+ Before returning final results to the user:
93
+
94
+ ```bash
95
+ # Step 1: Check all sub-task results on blackboard
96
+ python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
97
+ python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"
98
+ python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"
99
+
100
+ # Step 2: Validate each result
101
+ python {baseDir}/scripts/swarm_guard.py validate-result \
102
+ --task-id "task_001" \
103
+ --agent data_analyst \
104
+ --result '{"status":"success","output":{...},"confidence":0.85}'
105
+
106
+ # Step 3: Supervisor review (checks all issues)
107
+ python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
108
+
109
+ # Step 4: Only if APPROVED, commit final state
110
+ python {baseDir}/scripts/blackboard.py write "task:001:final" \
111
+ '{"status":"SUCCESS","output":{...}}'
112
+ ```
113
+
114
+ **Verdict Handling:**
115
+ | Verdict | Action |
116
+ |---------|--------|
117
+ | `APPROVED` | Commit and return results to user |
118
+ | `WARNING` | Review issues, fix if possible, then commit |
119
+ | `BLOCKED` | Do NOT return results. Report failure. |
120
+
121
+ ---
122
+
123
+ ## When to Use This Skill
124
+
125
+ - **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)
126
+ - **Parallel Execution**: Run multiple agents simultaneously and synthesize results
127
+ - **Permission Wall**: Gate access to SAP_API, FINANCIAL_API, or DATA_EXPORT operations
128
+ - **Shared Blackboard**: Coordinate agent state via persistent markdown file
129
+
130
+ ## Quick Start
131
+
132
+ ### 1. Initialize Budget (FIRST!)
133
+
134
+ **Always initialize a budget before any multi-agent task:**
135
+
136
+ ```bash
137
+ python {baseDir}/scripts/swarm_guard.py budget-init \
138
+ --task-id "task_001" \
139
+ --budget 10000 \
140
+ --description "Q4 Financial Analysis"
141
+ ```
142
+
143
+ ### 2. Delegate a Task to Another Session
144
+
145
+ Use OpenClaw's built-in session tools to delegate work:
146
+
147
+ ```
148
+ sessions_list # See available sessions/agents
149
+ sessions_send # Send task to another session
150
+ sessions_history # Check results from delegated work
151
+ ```
152
+
153
+ **Example delegation prompt:**
154
+ ```
155
+ Use sessions_send to ask the data_analyst session to:
156
+ "Analyze Q4 revenue trends from the SAP export data and summarize key insights"
157
+ ```
158
+
159
+ ### 3. Check Permission Before API Access
160
+
161
+ Before accessing SAP or Financial APIs, evaluate the request:
162
+
163
+ ```bash
164
+ # Run the permission checker script
165
+ python {baseDir}/scripts/check_permission.py \
166
+ --agent "data_analyst" \
167
+ --resource "SAP_API" \
168
+ --justification "Need Q4 invoice data for quarterly report" \
169
+ --scope "read:invoices"
170
+ ```
171
+
172
+ The script will output a grant token if approved, or denial reason if rejected.
173
+
174
+ ### 4. Use the Shared Blackboard
175
+
176
+ Read/write coordination state:
177
+
178
+ ```bash
179
+ # Write to blackboard
180
+ python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'
181
+
182
+ # Read from blackboard
183
+ python {baseDir}/scripts/blackboard.py read "task:q4_analysis"
184
+
185
+ # List all entries
186
+ python {baseDir}/scripts/blackboard.py list
187
+ ```
188
+
189
+ ## Agent-to-Agent Handoff Protocol
190
+
191
+ When delegating tasks between agents/sessions:
192
+
193
+ ### Step 1: Initialize Budget & Check Capacity
194
+ ```bash
195
+ # Initialize budget (if not already done)
196
+ python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000
197
+
198
+ # Check current status
199
+ python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"
200
+ ```
201
+
202
+ ### Step 2: Identify Target Agent
203
+ ```
204
+ sessions_list # Find available agents
205
+ ```
206
+
207
+ Common agent types:
208
+ | Agent | Specialty |
209
+ |-------|-----------|
210
+ | `data_analyst` | Data processing, SQL, analytics |
211
+ | `strategy_advisor` | Business strategy, recommendations |
212
+ | `risk_assessor` | Risk analysis, compliance checks |
213
+ | `orchestrator` | Coordination, task decomposition |
214
+
215
+ ### Step 3: Intercept Before Handoff (REQUIRED)
216
+
217
+ ```bash
218
+ # This checks budget AND handoff limits before allowing the call
219
+ python {baseDir}/scripts/swarm_guard.py intercept-handoff \
220
+ --task-id "task_001" \
221
+ --from orchestrator \
222
+ --to data_analyst \
223
+ --message "Analyze Q4 data" \
224
+ --artifact # Include if expecting output
225
+ ```
226
+
227
+ **If ALLOWED:** Proceed to Step 4
228
+ **If BLOCKED:** Stop - do not call sessions_send
229
+
230
+ ### Step 4: Construct Handoff Message
231
+
232
+ Include these fields in your delegation:
233
+ - **instruction**: Clear task description
234
+ - **context**: Relevant background information
235
+ - **constraints**: Any limitations or requirements
236
+ - **expectedOutput**: What format/content you need back
237
+
238
+ ### Step 5: Send via sessions_send
239
+
240
+ ```
241
+ sessions_send to data_analyst:
242
+ "[HANDOFF]
243
+ Instruction: Analyze Q4 revenue by product category
244
+ Context: Using SAP export from ./data/q4_export.csv
245
+ Constraints: Focus on top 5 categories only
246
+ Expected Output: JSON summary with category, revenue, growth_pct
247
+ [/HANDOFF]"
248
+ ```
249
+
250
+ ### Step 4: Check Results
251
+
252
+ ```
253
+ sessions_history data_analyst # Get the response
254
+ ```
255
+
256
+ ## Permission Wall (AuthGuardian)
257
+
258
+ **CRITICAL**: Always check permissions before accessing:
259
+ - `SAP_API` - SAP system connections
260
+ - `FINANCIAL_API` - Financial data services
261
+ - `EXTERNAL_SERVICE` - Third-party APIs
262
+ - `DATA_EXPORT` - Exporting sensitive data
263
+
264
+ ### Permission Evaluation Criteria
265
+
266
+ | Factor | Weight | Criteria |
267
+ |--------|--------|----------|
268
+ | Justification | 40% | Must explain specific task need |
269
+ | Trust Level | 30% | Agent's established trust score |
270
+ | Risk Assessment | 30% | Resource sensitivity + scope breadth |
271
+
272
+ ### Using the Permission Script
273
+
274
+ ```bash
275
+ # Request permission
276
+ python {baseDir}/scripts/check_permission.py \
277
+ --agent "your_agent_id" \
278
+ --resource "FINANCIAL_API" \
279
+ --justification "Generating quarterly financial summary for board presentation" \
280
+ --scope "read:revenue,read:expenses"
281
+
282
+ # Output if approved:
283
+ # ✅ GRANTED
284
+ # Token: grant_a1b2c3d4e5f6
285
+ # Expires: 2026-02-04T15:30:00Z
286
+ # Restrictions: read_only, no_pii_fields, audit_required
287
+
288
+ # Output if denied:
289
+ # ❌ DENIED
290
+ # Reason: Justification is insufficient. Please provide specific task context.
291
+ ```
292
+
293
+ ### Restriction Types
294
+
295
+ | Resource | Default Restrictions |
296
+ |----------|---------------------|
297
+ | SAP_API | `read_only`, `max_records:100` |
298
+ | FINANCIAL_API | `read_only`, `no_pii_fields`, `audit_required` |
299
+ | EXTERNAL_SERVICE | `rate_limit:10_per_minute` |
300
+ | DATA_EXPORT | `anonymize_pii`, `local_only` |
301
+
302
+ ## Shared Blackboard Pattern
303
+
304
+ The blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:
305
+
306
+ ```markdown
307
+ # Swarm Blackboard
308
+ Last Updated: 2026-02-04T10:30:00Z
309
+
310
+ ## Knowledge Cache
311
+ ### task:q4_analysis
312
+ {"status": "completed", "result": {...}, "agent": "data_analyst"}
313
+
314
+ ### cache:revenue_summary
315
+ {"q4_total": 1250000, "growth": 0.15}
316
+ ```
317
+
318
+ ### Blackboard Operations
319
+
320
+ ```bash
321
+ # Write with TTL (expires after 1 hour)
322
+ python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600
323
+
324
+ # Read (returns null if expired)
325
+ python {baseDir}/scripts/blackboard.py read "cache:temp_data"
326
+
327
+ # Delete
328
+ python {baseDir}/scripts/blackboard.py delete "cache:temp_data"
329
+
330
+ # Get full snapshot
331
+ python {baseDir}/scripts/blackboard.py snapshot
332
+ ```
333
+
334
+ ## Parallel Execution
335
+
336
+ For tasks requiring multiple agent perspectives:
337
+
338
+ ### Strategy 1: Merge (Default)
339
+ Combine all agent outputs into unified result.
340
+ ```
341
+ Ask data_analyst AND strategy_advisor to both analyze the dataset.
342
+ Merge their insights into a comprehensive report.
343
+ ```
344
+
345
+ ### Strategy 2: Vote
346
+ Use when you need consensus - pick the result with highest confidence.
347
+
348
+ ### Strategy 3: First-Success
349
+ Use for redundancy - take first successful result.
350
+
351
+ ### Strategy 4: Chain
352
+ Sequential processing - output of one feeds into next.
353
+
354
+ ### Example Parallel Workflow
355
+
356
+ ```
357
+ 1. sessions_send to data_analyst: "Extract key metrics from Q4 data"
358
+ 2. sessions_send to risk_assessor: "Identify compliance risks in Q4 data"
359
+ 3. sessions_send to strategy_advisor: "Recommend actions based on Q4 trends"
360
+ 4. Wait for all responses via sessions_history
361
+ 5. Synthesize: Combine metrics + risks + recommendations into executive summary
362
+ ```
363
+
364
+ ## Security Considerations
365
+
366
+ 1. **Never bypass the permission wall** for DATABASE/PAYMENTS APIs
367
+ 2. **Always include justification** explaining the business need
368
+ 3. **Use minimal scope** - request only what you need
369
+ 4. **Check token expiry** - tokens are valid for 5 minutes
370
+ 5. **Audit trail** - all permission requests are logged
371
+
372
+ ## 📝 Audit Trail Requirements (MANDATORY)
373
+
374
+ **Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.
375
+
376
+ ### What Gets Logged Automatically
377
+
378
+ The scripts automatically log these events:
379
+ - `permission_granted` - When access is approved
380
+ - `permission_denied` - When access is rejected
381
+ - `permission_revoked` - When a token is manually revoked
382
+ - `ttl_cleanup` - When expired tokens are purged
383
+ - `result_validated` / `result_rejected` - Swarm Guard validations
384
+
385
+ ### Log Entry Format
386
+
387
+ ```json
388
+ {
389
+ "timestamp": "2026-02-04T10:30:00+00:00",
390
+ "action": "permission_granted",
391
+ "details": {
392
+ "agent_id": "data_analyst",
393
+ "resource_type": "DATABASE",
394
+ "justification": "Q4 revenue analysis",
395
+ "token": "grant_abc123...",
396
+ "restrictions": ["read_only", "max_records:100"]
397
+ }
398
+ }
399
+ ```
400
+
401
+ ### Reading the Audit Log
402
+
403
+ ```bash
404
+ # View recent entries (last 10)
405
+ tail -10 {baseDir}/data/audit_log.jsonl
406
+
407
+ # Search for specific agent
408
+ grep "data_analyst" {baseDir}/data/audit_log.jsonl
409
+
410
+ # Count actions by type
411
+ cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c
412
+ ```
413
+
414
+ ### Custom Audit Entries
415
+
416
+ If you perform a sensitive action manually, log it:
417
+
418
+ ```python
419
+ import json
420
+ from datetime import datetime, timezone
421
+ from pathlib import Path
422
+
423
+ audit_file = Path("{baseDir}/data/audit_log.jsonl")
424
+ entry = {
425
+ "timestamp": datetime.now(timezone.utc).isoformat(),
426
+ "action": "manual_data_access",
427
+ "details": {
428
+ "agent": "orchestrator",
429
+ "description": "Direct database query for debugging",
430
+ "justification": "Investigating data sync issue #1234"
431
+ }
432
+ }
433
+ with open(audit_file, "a") as f:
434
+ f.write(json.dumps(entry) + "\n")
435
+ ```
436
+
437
+ ## 🧹 TTL Enforcement (Token Lifecycle)
438
+
439
+ Expired permission tokens are automatically tracked. Run periodic cleanup:
440
+
441
+ ```bash
442
+ # List expired tokens (without removing)
443
+ python {baseDir}/scripts/revoke_token.py --list-expired
444
+
445
+ # Remove all expired tokens
446
+ python {baseDir}/scripts/revoke_token.py --cleanup
447
+
448
+ # Output:
449
+ # 🧹 TTL Cleanup Complete
450
+ # Removed: 3 expired token(s)
451
+ # Remaining active grants: 2
452
+ ```
453
+
454
+ **Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.
455
+
456
+ ## ⚠️ Swarm Guard: Preventing Common Failures
457
+
458
+ Two critical issues can derail multi-agent swarms:
459
+
460
+ ### 1. The Handoff Tax 💸
461
+
462
+ **Problem**: Agents waste tokens "talking about" work instead of doing it.
463
+
464
+ **Prevention**:
465
+ ```bash
466
+ # Before each handoff, check your budget:
467
+ python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"
468
+
469
+ # Output:
470
+ # 🟢 Task: task_001
471
+ # Handoffs: 1/3
472
+ # Remaining: 2
473
+ # Action Ratio: 100%
474
+ ```
475
+
476
+ **Rules enforced**:
477
+ - **Max 3 handoffs per task** - After 3, produce output or abort
478
+ - **Max 500 chars per message** - Be concise: instruction + constraints + expected output
479
+ - **60% action ratio** - At least 60% of handoffs must produce artifacts
480
+ - **2-minute planning limit** - No output after 2min = timeout
481
+
482
+ ```bash
483
+ # Record a handoff (with tax checking):
484
+ python {baseDir}/scripts/swarm_guard.py record-handoff \
485
+ --task-id "task_001" \
486
+ --from orchestrator \
487
+ --to data_analyst \
488
+ --message "Analyze sales data, output JSON summary" \
489
+ --artifact # Include if this handoff produces output
490
+ ```
491
+
492
+ ### 2. Silent Failure Detection 👻
493
+
494
+ **Problem**: One agent fails silently, others keep working on bad data.
495
+
496
+ **Prevention - Heartbeats**:
497
+ ```bash
498
+ # Agents must send heartbeats while working:
499
+ python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"
500
+
501
+ # Check if an agent is healthy:
502
+ python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst
503
+
504
+ # Output if healthy:
505
+ # 💚 Agent 'data_analyst' is HEALTHY
506
+ # Last seen: 15s ago
507
+
508
+ # Output if failed:
509
+ # 💔 Agent 'data_analyst' is UNHEALTHY
510
+ # Reason: STALE_HEARTBEAT
511
+ # → Do NOT use any pending results from this agent.
512
+ ```
513
+
514
+ **Prevention - Result Validation**:
515
+ ```bash
516
+ # Before using another agent's result, validate it:
517
+ python {baseDir}/scripts/swarm_guard.py validate-result \
518
+ --task-id "task_001" \
519
+ --agent data_analyst \
520
+ --result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'
521
+
522
+ # Output:
523
+ # ✅ RESULT VALID
524
+ # → APPROVED - Result can be used by other agents
525
+ ```
526
+
527
+ **Required result fields**: `status`, `output`, `confidence`
528
+
529
+ ### Supervisor Review
530
+
531
+ Before finalizing any task, run supervisor review:
532
+ ```bash
533
+ python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
534
+
535
+ # Output:
536
+ # ✅ SUPERVISOR VERDICT: APPROVED
537
+ # Task: task_001
538
+ # Age: 1.5 minutes
539
+ # Handoffs: 2
540
+ # Artifacts: 2
541
+ ```
542
+
543
+ **Verdicts**:
544
+ - `APPROVED` - Task healthy, results usable
545
+ - `WARNING` - Issues detected, review recommended
546
+ - `BLOCKED` - Critical failures, do NOT use results
547
+
548
+ ## Troubleshooting
549
+
550
+ ### Permission Denied
551
+ - Provide more specific justification (mention task, purpose, expected outcome)
552
+ - Narrow the requested scope
553
+ - Check agent trust level
554
+
555
+ ### Blackboard Read Returns Null
556
+ - Entry may have expired (check TTL)
557
+ - Key may be misspelled
558
+ - Entry was never written
559
+
560
+ ### Session Not Found
561
+ - Run `sessions_list` to see available sessions
562
+ - Session may need to be started first
563
+
564
+ ## References
565
+
566
+ - [AuthGuardian Details](references/auth-guardian.md) - Full permission system documentation
567
+ - [Blackboard Schema](references/blackboard-schema.md) - Data structure specifications
568
+ - [Agent Trust Levels](references/trust-levels.md) - How trust is calculated
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Adapter Registry -- Routes agent requests to the correct adapter
3
+ *
4
+ * The registry is the single entry point the SwarmOrchestrator uses.
5
+ * It manages multiple adapters, routes requests based on agent ID patterns,
6
+ * and provides unified agent discovery across all registered adapters.
7
+ *
8
+ * @module AdapterRegistry
9
+ * @version 1.0.0
10
+ */
11
+ import type { IAgentAdapter, AdapterConfig, AdapterRoute, RegistryConfig, AgentPayload, AgentContext, AgentResult, AgentInfo, AdapterEventHandler, AdapterEventType } from '../types/agent-adapter';
12
+ export declare class AdapterRegistry {
13
+ private adapters;
14
+ private routes;
15
+ private defaultAdapterName;
16
+ private eventHandlers;
17
+ private agentCache;
18
+ constructor(config?: RegistryConfig);
19
+ /**
20
+ * Register an adapter with the registry.
21
+ * Call this for each agent framework you want to support.
22
+ */
23
+ registerAdapter(adapter: IAgentAdapter): void;
24
+ /**
25
+ * Initialize a registered adapter with its configuration
26
+ */
27
+ initializeAdapter(adapterName: string, config?: AdapterConfig): Promise<void>;
28
+ /**
29
+ * Register + initialize in one call (convenience)
30
+ */
31
+ addAdapter(adapter: IAgentAdapter, config?: AdapterConfig): Promise<void>;
32
+ /**
33
+ * Remove an adapter and shut it down
34
+ */
35
+ removeAdapter(adapterName: string): Promise<void>;
36
+ /**
37
+ * Get a registered adapter by name
38
+ */
39
+ getAdapter(adapterName: string): IAgentAdapter | undefined;
40
+ /**
41
+ * List all registered adapters
42
+ */
43
+ listAdapters(): Array<{
44
+ name: string;
45
+ version: string;
46
+ ready: boolean;
47
+ }>;
48
+ /**
49
+ * Set the default adapter for unrouted requests
50
+ */
51
+ setDefaultAdapter(adapterName: string): void;
52
+ /**
53
+ * Add a routing rule: agent IDs matching the pattern go to the specified adapter.
54
+ *
55
+ * Patterns:
56
+ * "lc:*" -> all agents prefixed with "lc:" go to the LangChain adapter
57
+ * "autogen:*" -> AutoGen agents
58
+ * "crew:*" -> CrewAI agents
59
+ * "*" -> catch-all
60
+ * "data_analyst" -> exact match
61
+ */
62
+ addRoute(route: AdapterRoute): void;
63
+ /**
64
+ * Resolve which adapter should handle a given agent ID
65
+ */
66
+ resolveAdapter(agentId: string): IAgentAdapter | null;
67
+ private matchPattern;
68
+ /**
69
+ * Execute an agent task, automatically routing to the correct adapter.
70
+ * This is the primary method the SwarmOrchestrator calls.
71
+ */
72
+ executeAgent(agentId: string, payload: AgentPayload, context: AgentContext): Promise<AgentResult>;
73
+ /**
74
+ * Discover all agents across all registered adapters
75
+ */
76
+ discoverAgents(): Promise<AgentInfo[]>;
77
+ /**
78
+ * Check if any adapter can handle a specific agent
79
+ */
80
+ isAgentAvailable(agentId: string): Promise<boolean>;
81
+ healthCheck(): Promise<Record<string, {
82
+ healthy: boolean;
83
+ details?: string;
84
+ }>>;
85
+ on(event: AdapterEventType, handler: AdapterEventHandler): void;
86
+ off(event: AdapterEventType, handler: AdapterEventHandler): void;
87
+ private emit;
88
+ /**
89
+ * Shut down all adapters and clear the registry
90
+ */
91
+ shutdownAll(): Promise<void>;
92
+ }
93
+ export declare function getRegistry(config?: RegistryConfig): AdapterRegistry;
94
+ //# sourceMappingURL=adapter-registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../adapters/adapter-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EAET,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,aAAa,CAA2D;IAChF,OAAO,CAAC,UAAU,CAAkC;gBAExC,MAAM,CAAC,EAAE,cAAc;IAWnC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAQ7C;;OAEG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IASvF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnF;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI1D;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAQxE;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAW5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAMnC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IA8CrD,OAAO,CAAC,YAAY;IA0BpB;;;OAGG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC;IAyDvB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB5C;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBnD,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqBpF,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAM/D,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAKhE,OAAO,CAAC,IAAI;IAsBZ;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAanC;AAKD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,eAAe,CAKpE"}