network-ai 3.2.2 → 3.2.3

package/README.md

@@ -2,7 +2,7 @@
 
 **The plug-and-play AI agent orchestrator for TypeScript/Node.js -- connect 12 agent frameworks with zero glue code**
 
-[![Release](https://img.shields.io/badge/release-v3.2.2-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v3.2.3-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![ClawHub](https://img.shields.io/badge/ClawHub-network--ai-orange.svg)](https://clawhub.ai/skills/network-ai)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://typescriptlang.org)
@@ -15,12 +15,13 @@
 
 > **Legacy Users:** This skill works with **Clawdbot** and **Moltbot** (now OpenClaw). If you're searching for *Moltbot Security*, *Clawdbot Swarm*, or *Moltbot multi-agent* -- you're in the right place!
 
-Network-AI is a framework-agnostic multi-agent orchestrator that connects LLM agents across **12 frameworks** -- LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and custom adapters. It provides shared blackboard coordination, built-in security (AES-256, HMAC tokens, rate limiting), content quality gates with hallucination detection, and agentic workflow patterns (parallel execution, voting, chaining). Zero dependencies per adapter -- bring your own framework SDK and start building multi-agent systems in minutes.
+Network-AI is a framework-agnostic multi-agent orchestrator and **behavioral control plane** that connects LLM agents across **12 frameworks** -- LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and custom adapters. It provides shared blackboard coordination with atomic commits, built-in security (AES-256, HMAC tokens, rate limiting), content quality gates with hallucination detection, compliance enforcement, and agentic workflow patterns (parallel fan-out/fan-in, voting, chaining). Zero dependencies per adapter -- bring your own framework SDK and start building governed multi-agent systems in minutes.
 
 **Why Network-AI?**
 - **Framework-agnostic** -- Not locked to one LLM provider or agent SDK
-- **Production security** -- Encryption, audit trails, rate limiting built in
-- **Swarm intelligence** -- Parallel execution, voting, chain-of-agents patterns
+- **Governance layer** -- Permission gating, audit trails, budget ceilings, and compliance enforcement across all agents
+- **Shared state** -- Atomic blackboard with conflict resolution for safe parallel agent coordination (fan-out/fan-in)
+- **Production security** -- AES-256 encryption, HMAC audit logs, rate limiting, input sanitization
 - **Zero config** -- Works out of the box with `createSwarmOrchestrator()`
 
 ## Hello World -- Get Running in 60 Seconds
@@ -131,12 +132,15 @@ Network-AI wraps your agent swarm with **file-system mutexes**, **atomic commits
 - **Cryptographic Audit Logs** -- Tamper-evident signed audit trail with chain continuation
 - **Secure Gateway** -- Integrated security layer wrapping all operations
 
-### Operational Safety
+### Operational Safety & Governance
 - **Swarm Guard** -- Prevents "Handoff Tax" (wasted tokens) and detects silent agent failures
 - **Atomic Commits** -- File-system mutexes prevent split-brain in concurrent writes
 - **Priority-Based Preemption** -- Higher-priority agents preempt lower-priority writes on same-key conflicts (`priority-wins` strategy)
 - **Cost Awareness** -- Token budget tracking with automatic SafetyShutdown
 - **Budget-Aware Handoffs** -- `intercept-handoff` command wraps `sessions_send` with budget checks
+- **`--active-grants` Observability** -- Real-time view of which agents hold access to which APIs, with TTL countdown
+- **`--audit-summary` Observability** -- Per-agent and per-resource breakdown of permission requests, grants, and denials
+- **Justification Hardening** -- 16-pattern prompt-injection detector, keyword-stuffing defense, structural coherence scoring
 
 ## Project Structure
 
@@ -190,6 +194,7 @@ Network-AI/
 |-- test-standalone.ts        # Core orchestrator tests (79 tests)
 |-- test-security.ts          # Security module tests (33 tests)
 |-- test-adapters.ts          # Adapter system tests (139 tests)
+|-- test-priority.ts          # Priority & preemption tests (64 tests)
 |-- test-ai-quality.ts        # AI quality gate demo
 |-- test.ts                   # Full integration test suite
 ```
@@ -341,6 +346,65 @@ Expires: 2026-02-04T15:30:00Z
 Restrictions: read_only, max_records:100
 ```
 
+#### 3a. View Active Grants
+
+See which agents currently hold access to which APIs:
+
+```bash
+# Human-readable
+python scripts/check_permission.py --active-grants
+
+# Filter by agent
+python scripts/check_permission.py --active-grants --agent data_analyst
+
+# Machine-readable JSON
+python scripts/check_permission.py --active-grants --json
+```
+
+Output:
+```
+Active Grants:
+======================================================================
+  Agent:       data_analyst
+  Resource:    DATABASE
+  Scope:       read:orders
+  Token:       grant_c1ea828897...
+  Remaining:   4.4 min
+  Restrictions: read_only, max_records:100
+  ------------------------------------------------------------------
+
+Total: 1 active, 0 expired
+```
+
+#### 3b. Audit Summary
+
+Summarize permission activity across all agents:
+
+```bash
+# Human-readable
+python scripts/check_permission.py --audit-summary
+
+# Last 50 entries, JSON output
+python scripts/check_permission.py --audit-summary --last 50 --json
+```
+
+Output:
+```
+Audit Summary
+======================================================================
+  Requests:     12
+  Grants:        9
+  Denials:       3
+  Grant Rate:   75%
+
+  By Agent:
+  --------------------------------------------------
+  Agent                  Requests     Grants    Denials
+  data_analyst                  4          3          1
+  orchestrator                  5          4          1
+  strategy_advisor              3          2          1
+```
+
 #### 4. Use the Blackboard
 
 ```bash
@@ -359,7 +423,44 @@ python scripts/blackboard.py commit "chg_001"
 python scripts/blackboard.py list
 ```
 
-#### 5. Priority-Based Conflict Resolution (Phase 3)
+#### 5. Fan-Out / Fan-In with Shared Blackboard
+
+Coordinate multiple specialized agents working on independent subtasks, then merge results:
+
+```typescript
+import { LockedBlackboard } from 'network-ai';
+import { Logger } from 'network-ai';
+
+const logger = Logger.create('fan-out');
+const board = new LockedBlackboard('.', logger, { conflictResolution: 'first-commit-wins' });
+
+// Fan-out: each agent writes to its own section
+const agents = ['reliability', 'security', 'cost', 'operations', 'performance'];
+
+for (const pillar of agents) {
+  // Each agent evaluates independently, writes to its own key
+  const id = board.propose(`eval:${pillar}`, { score: Math.random(), findings: [] }, pillar);
+  board.validate(id, 'orchestrator');
+  board.commit(id);
+}
+
+// Fan-in: orchestrator reads all results and merges
+const results = agents.map(pillar => ({
+  pillar,
+  ...board.read(`eval:${pillar}`)
+}));
+
+const summary = board.propose('eval:summary', {
+  overall: results.reduce((sum, r) => sum + r.score, 0) / results.length,
+  pillars: results
+}, 'orchestrator');
+board.validate(summary, 'orchestrator');
+board.commit(summary);
+```
+
+This pattern works with any framework adapter -- LangChain agents, AutoGen agents, CrewAI crews, or any mix. The blackboard ensures no agent overwrites another's results.
+
+#### 6. Priority-Based Conflict Resolution (Phase 3)
 
 ```typescript
 import { LockedBlackboard } from 'network-ai';
@@ -384,7 +485,7 @@ board.commit(highId);                   // success
 board.read('shared:config'); // { mode: 'final' } -- supervisor wins
 ```
 
-#### 6. Check Budget Status
+#### 7. Check Budget Status
 
 ```bash
 python scripts/swarm_guard.py budget-check --task-id "task_001"
@@ -628,18 +729,43 @@ If you find Network-AI useful, **give it a star** -- it helps others discover th
 
 **Compatible with 12 agent frameworks: OpenClaw, LangChain, AutoGen, CrewAI, MCP, LlamaIndex, Semantic Kernel, OpenAI Assistants, Haystack, DSPy, Agno, and any custom adapter**
 
+## Competitive Comparison
+
+How Network-AI compares to other multi-agent frameworks:
+
+| Capability | Network-AI | LangChain/LangGraph | AutoGen/AG2 | CrewAI | Claude SDK |
+|---|---|---|---|---|---|
+| **Multi-framework support** | 12 adapters | LangChain only | AutoGen only | CrewAI only | Claude only |
+| **Shared state (blackboard)** | Atomic commits, TTL, priority | LangGraph state | Shared context | Shared memory | Project memory |
+| **Conflict resolution** | Priority preemption, last-write-wins | None | None | None | None |
+| **Fan-out / fan-in** | Native (parallel + merge) | LangGraph branches | Group chat | Parallel tasks | Subagents |
+| **Permission gating** | AuthGuardian (weighted scoring) | None | None | None | None |
+| **Budget tracking** | Token ceiling + per-task budgets | Callbacks only | None | None | None |
+| **Audit trail** | HMAC-signed, tamper-evident | None | None | None | None |
+| **Encryption at rest** | AES-256-GCM | None | None | None | None |
+| **Observability** | `--active-grants`, `--audit-summary` | LangSmith (SaaS) | None | None | None |
+| **Rate limiting** | Per-agent with lockout | None | None | None | None |
+| **Justification hardening** | 16-pattern injection defense | None | None | None | None |
+| **Language** | TypeScript/Node.js | Python | Python | Python | Python |
+| **Dependencies** | Zero (per adapter) | Heavy | Heavy | Heavy | Moderate |
+| **License** | MIT | MIT | CC-BY-4.0 | MIT | MIT |
+
+**Key differentiator:** Network-AI is the only framework that combines multi-framework orchestration with a governance layer (permissions, audit, encryption, budget enforcement). Other frameworks focus on one LLM provider; Network-AI wraps all of them.
+
 ## Related Concepts
 
 Network-AI fits into the broader AI agent ecosystem:
 
 - **Multi-Agent Systems** -- Coordinate multiple AI agents working together on complex tasks
 - **Agentic AI** -- Build autonomous agents that reason, plan, and execute using LLMs
-- **Swarm Intelligence** -- Parallel execution patterns with voting, merging, and chain strategies
+- **Behavioral Control Plane** -- Govern agent behavior with permission gating, compliance enforcement, and audit trails
+- **Swarm Intelligence** -- Parallel fan-out/fan-in patterns with voting, merging, and chain strategies
 - **Model Context Protocol (MCP)** -- Standard protocol support for LLM tool integration
 - **Agent-to-Agent (A2A)** -- Inter-agent communication via shared blackboard and handoff protocol
 - **Context Engineering** -- Manage and share context across agent boundaries
 - **Agentic Workflows** -- Task decomposition, parallel processing, and synthesis pipelines
 - **LLM Orchestration** -- Route tasks to the right agent framework automatically
+- **Agent Governance** -- Permission gating, budget enforcement, audit logging, and compliance monitoring
 
 If you're using LangGraph, Dify, Flowise, PraisonAI, AutoGen/AG2, CrewAI, or any other agent framework, Network-AI can integrate with it through the adapter system.
 
@@ -648,6 +774,6 @@ If you're using LangGraph, Dify, Flowise, PraisonAI, AutoGen/AG2, CrewAI, or any
 <details>
 <summary>Keywords (for search)</summary>
 
-ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, ClawHub, clawhub, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
+ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, behavioral-control-plane, governance-layer, compliance-enforcement, fan-out-fan-in, agent-observability, permission-gating, audit-trail, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, ClawHub, clawhub, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
 
 </details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "AI agent orchestration framework for TypeScript/Node.js - plug-and-play multi-agent coordination with 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw). Built-in security, swarm intelligence, and agentic workflow patterns.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/check_permission.py

@@ -8,11 +8,17 @@ Evaluates permission requests for accessing sensitive resources
 Usage:
     python check_permission.py --agent AGENT_ID --resource RESOURCE_TYPE \
         --justification "REASON" [--scope SCOPE]
+    python check_permission.py --active-grants [--agent AGENT_ID] [--json]
+    python check_permission.py --audit-summary [--last N] [--json]
 
-Example:
+Examples:
     python check_permission.py --agent data_analyst --resource DATABASE \
         --justification "Need customer order history for sales report" \
         --scope "read:orders"
+
+    python check_permission.py --active-grants
+    python check_permission.py --active-grants --agent data_analyst --json
+    python check_permission.py --audit-summary --last 20 --json
 """
 
 import argparse
@@ -355,35 +361,277 @@ def evaluate_permission(agent_id: str, resource_type: str,
     }
 
 
+def list_active_grants(agent_filter: Optional[str] = None, as_json: bool = False) -> int:
+    """
+    Show which agents currently hold access to which APIs with expiry times.
+
+    Reads data/active_grants.json, filters out expired grants,
+    and displays remaining grants with TTL.
+    """
+    if not GRANTS_FILE.exists():
+        if as_json:
+            print(json.dumps({"grants": [], "total": 0, "expired_cleaned": 0}))
+        else:
+            print("No active grants. (No grants file found.)")
+        return 0
+
+    try:
+        grants = json.loads(GRANTS_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        if as_json:
+            print(json.dumps({"error": "Could not read grants file"}))
+        else:
+            print("Error: Could not read grants file.")
+        return 1
+
+    now = datetime.now(timezone.utc)
+    active: list[dict[str, Any]] = []
+    expired_count = 0
+
+    for token, grant in grants.items():
+        try:
+            expires_at = datetime.fromisoformat(grant["expires_at"])
+        except (KeyError, ValueError):
+            expired_count += 1
+            continue
+
+        if expires_at <= now:
+            expired_count += 1
+            continue
+
+        if agent_filter and grant.get("agent_id") != agent_filter:
+            continue
+
+        remaining = expires_at - now
+        minutes_left = remaining.total_seconds() / 60
+
+        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"),
+            "granted_at": grant.get("granted_at", "unknown"),
+            "expires_at": grant["expires_at"],
+            "minutes_remaining": round(minutes_left, 1),
+            "restrictions": grant.get("restrictions", []),
+        })
+
+    # Sort by expiry (soonest first)
+    active.sort(key=lambda g: g["expires_at"])
+
+    if as_json:
+        # In JSON mode, include full tokens
+        output: dict[str, Any] = {
+            "grants": active,
+            "total": len(active),
+            "expired_cleaned": expired_count,
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        if not active:
+            filter_msg = f" for agent '{agent_filter}'" if agent_filter else ""
+            print(f"No active grants{filter_msg}. ({expired_count} expired.)")
+        else:
+            filter_msg = f" (agent: {agent_filter})" if agent_filter else ""
+            print(f"Active Grants{filter_msg}:")
+            print(f"{'='*70}")
+            for g in active:
+                print(f"  Agent:       {g['agent_id']}")
+                print(f"  Resource:    {g['resource_type']}")
+                if g["scope"]:
+                    print(f"  Scope:       {g['scope']}")
+                print(f"  Token:       {g['token']}")
+                print(f"  Granted:     {g['granted_at']}")
+                print(f"  Expires:     {g['expires_at']}")
+                print(f"  Remaining:   {g['minutes_remaining']} min")
+                if g["restrictions"]:
+                    print(f"  Restrictions: {', '.join(g['restrictions'])}")
+                print(f"  {'-'*66}")
+            print(f"\nTotal: {len(active)} active, {expired_count} expired")
+
+    return 0
+
+
+def audit_summary(last_n: int = 20, as_json: bool = False) -> int:
+    """
+    Summarize recent permission requests, grants, and denials.
+
+    Parses data/audit_log.jsonl and produces per-agent and per-resource
+    breakdowns plus recent activity.
+    """
+    if not AUDIT_LOG.exists():
+        if as_json:
+            print(json.dumps({"entries": 0, "summary": {}, "recent": []}))
+        else:
+            print("No audit log found. (No permission requests recorded yet.)")
+        return 0
+
+    entries: list[dict[str, Any]] = []
+    try:
+        with open(AUDIT_LOG, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        entries.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+    except OSError:
+        if as_json:
+            print(json.dumps({"error": "Could not read audit log"}))
+        else:
+            print("Error: Could not read audit log.")
+        return 1
+
+    if not entries:
+        if as_json:
+            print(json.dumps({"entries": 0, "summary": {}, "recent": []}))
+        else:
+            print("Audit log is empty.")
+        return 0
+
+    # Aggregate stats
+    total_requests = 0
+    total_grants = 0
+    by_agent: dict[str, dict[str, int]] = {}
+    by_resource: dict[str, dict[str, int]] = {}
+
+    for entry in entries:
+        action = entry.get("action", "")
+        details = entry.get("details", {})
+        agent_id = details.get("agent_id", "unknown")
+        resource_type = details.get("resource_type", "unknown")
+
+        if action == "permission_request":
+            total_requests += 1
+            by_agent.setdefault(agent_id, {"requests": 0, "grants": 0})
+            by_agent[agent_id]["requests"] += 1
+            by_resource.setdefault(resource_type, {"requests": 0, "grants": 0})
+            by_resource[resource_type]["requests"] += 1
+        elif action == "permission_granted":
+            total_grants += 1
+            by_agent.setdefault(agent_id, {"requests": 0, "grants": 0})
+            by_agent[agent_id]["grants"] += 1
+            by_resource.setdefault(resource_type, {"requests": 0, "grants": 0})
+            by_resource[resource_type]["grants"] += 1
+
+    total_denials = total_requests - total_grants
+
+    # Recent entries (last N)
+    recent = entries[-last_n:]
+
+    # Time range
+    first_ts = entries[0].get("timestamp", "unknown")
+    last_ts = entries[-1].get("timestamp", "unknown")
+
+    if as_json:
+        output: dict[str, Any] = {
+            "total_entries": len(entries),
+            "total_requests": total_requests,
+            "total_grants": total_grants,
+            "total_denials": total_denials,
+            "time_range": {"first": first_ts, "last": last_ts},
+            "by_agent": by_agent,
+            "by_resource": by_resource,
+            "recent": recent[-last_n:],
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        print("Audit Summary")
+        print(f"{'='*70}")
+        print(f"  Log entries:  {len(entries)}")
+        print(f"  Time range:   {first_ts}")
+        print(f"                {last_ts}")
+        print(f"")
+        print(f"  Requests:     {total_requests}")
+        print(f"  Grants:       {total_grants}")
+        print(f"  Denials:      {total_denials}")
+        grant_rate = (total_grants / total_requests * 100) if total_requests > 0 else 0
+        print(f"  Grant Rate:   {grant_rate:.0f}%")
+
+        if by_agent:
+            print(f"\n  By Agent:")
+            print(f"  {'-'*50}")
+            print(f"  {'Agent':<20} {'Requests':>10} {'Grants':>10} {'Denials':>10}")
+            print(f"  {'-'*50}")
+            for agent_id, stats in sorted(by_agent.items()):
+                denials = stats["requests"] - stats["grants"]
+                print(f"  {agent_id:<20} {stats['requests']:>10} {stats['grants']:>10} {denials:>10}")
+
+        if by_resource:
+            print(f"\n  By Resource:")
+            print(f"  {'-'*50}")
+            print(f"  {'Resource':<20} {'Requests':>10} {'Grants':>10} {'Denials':>10}")
+            print(f"  {'-'*50}")
+            for resource_type, stats in sorted(by_resource.items()):
+                denials = stats["requests"] - stats["grants"]
+                print(f"  {resource_type:<20} {stats['requests']:>10} {stats['grants']:>10} {denials:>10}")
+
+        print(f"\n  Recent Activity (last {min(last_n, len(recent))}):")
+        print(f"  {'-'*66}")
+        for entry in recent:
+            ts = entry.get("timestamp", "?")[:19]
+            action = entry.get("action", "?")
+            details = entry.get("details", {})
+            agent_id = details.get("agent_id", "?")
+            resource_type = details.get("resource_type", "?")
+            symbol = "GRANT" if action == "permission_granted" else "REQ" if action == "permission_request" else action.upper()
+            print(f"  {ts}  [{symbol:>5}]  {agent_id} -> {resource_type}")
+
+    return 0
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="AuthGuardian Permission Checker",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  %(prog)s --agent data_analyst --resource SAP_API \\
-      --justification "Need Q4 invoice data for quarterly report"
-  
-  %(prog)s --agent orchestrator --resource FINANCIAL_API \\
-      --justification "Generating board presentation financials" \\
-      --scope "read:revenue,read:expenses"
+  Check permission:
+    %(prog)s --agent data_analyst --resource DATABASE \\
+        --justification "Need Q4 invoice data for quarterly report"
+
+  List active grants:
+    %(prog)s --active-grants
+    %(prog)s --active-grants --agent data_analyst --json
+
+  View audit summary:
+    %(prog)s --audit-summary
+    %(prog)s --audit-summary --last 50 --json
 """
     )
-    
+
+    # Action flags
+    parser.add_argument(
+        "--active-grants",
+        action="store_true",
+        help="List all active (non-expired) permission grants"
+    )
+    parser.add_argument(
+        "--audit-summary",
+        action="store_true",
+        help="Show audit log summary with per-agent and per-resource breakdowns"
+    )
+    parser.add_argument(
+        "--last",
+        type=int,
+        default=20,
+        help="Number of recent audit entries to show (default: 20)"
+    )
+
+    # Permission check args (required only for check mode)
     parser.add_argument(
         "--agent", "-a",
-        required=True,
-        help="Agent ID requesting permission"
+        help="Agent ID requesting permission (required for check; optional filter for --active-grants)"
     )
     parser.add_argument(
         "--resource", "-r",
-        required=True,
         choices=["DATABASE", "PAYMENTS", "EMAIL", "FILE_EXPORT"],
         help="Resource type to access"
     )
     parser.add_argument(
         "--justification", "-j",
-        required=True,
         help="Business justification for the request"
     )
     parser.add_argument(
@@ -395,29 +643,45 @@ Examples:
         action="store_true",
         help="Output result as JSON"
     )
-    
+
     args = parser.parse_args()
-    
+
+    # --- Action: --active-grants ---
+    if args.active_grants:
+        sys.exit(list_active_grants(agent_filter=args.agent, as_json=args.json))
+
+    # --- Action: --audit-summary ---
+    if args.audit_summary:
+        sys.exit(audit_summary(last_n=args.last, as_json=args.json))
+
+    # --- Default action: permission check ---
+    if not args.agent:
+        parser.error("--agent is required for permission checks")
+    if not args.resource:
+        parser.error("--resource is required for permission checks")
+    if not args.justification:
+        parser.error("--justification is required for permission checks")
+
     result = evaluate_permission(
         agent_id=args.agent,
         resource_type=args.resource,
         justification=args.justification,
         scope=args.scope
     )
-    
+
     if args.json:
         print(json.dumps(result, indent=2))
     else:
         if result["granted"]:
-            print("✅ GRANTED")
+            print("GRANTED")
             print(f"Token: {result['token']}")
             print(f"Expires: {result['expires_at']}")
             print(f"Restrictions: {', '.join(result['restrictions'])}")
         else:
-            print("❌ DENIED")
+            print("DENIED")
             print(f"Reason: {result['reason']}")
-        
-        print("\n📊 Evaluation Scores:")
+
+        print("\nEvaluation Scores:")
         scores = result["scores"]
         if scores.get("justification") is not None:
             print(f"  Justification: {scores['justification']:.2f}")
@@ -427,7 +691,7 @@ Examples:
             print(f"  Risk Score:    {scores['risk']:.2f}")
         if scores.get("weighted") is not None:
             print(f"  Weighted:      {scores['weighted']:.2f}")
-    
+
     sys.exit(0 if result["granted"] else 1)