network-ai 3.0.0

package/scripts/validate_token.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Validate Grant Token
+
+Check if a permission grant token is valid and not expired.
+
+Usage:
+    python validate_token.py TOKEN
+
+Example:
+    python validate_token.py grant_a1b2c3d4e5f6
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+GRANTS_FILE = Path(__file__).parent.parent / "data" / "active_grants.json"
+
+
+def validate_token(token: str) -> dict[str, Any]:
+    """Validate a grant token and return its details."""
+    if not GRANTS_FILE.exists():
+        return {
+            "valid": False,
+            "reason": "No grants file found"
+        }
+    
+    try:
+        grants = json.loads(GRANTS_FILE.read_text())
+    except json.JSONDecodeError:
+        return {
+            "valid": False,
+            "reason": "Invalid grants file"
+        }
+    
+    if token not in grants:
+        return {
+            "valid": False,
+            "reason": "Token not found"
+        }
+    
+    grant = grants[token]
+    
+    # Check expiration
+    expires_at = grant.get("expires_at")
+    if expires_at:
+        try:
+            expiry = datetime.fromisoformat(str(expires_at).replace("Z", "+00:00"))
+            now = datetime.now(timezone.utc)
+            
+            if now > expiry:
+                return {
+                    "valid": False,
+                    "reason": "Token has expired",
+                    "expired_at": expires_at
+                }
+        except Exception:
+            pass
+    
+    return {
+        "valid": True,
+        "grant": grant
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate a permission grant token")
+    parser.add_argument("token", help="Grant token to validate")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    
+    args = parser.parse_args()
+    result = validate_token(args.token)
+    
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if result["valid"]:
+            grant = result["grant"]
+            print("✅ Token is VALID")
+            print(f"   Agent: {grant.get('agent_id')}")
+            print(f"   Resource: {grant.get('resource_type')}")
+            print(f"   Scope: {grant.get('scope', 'N/A')}")
+            print(f"   Expires: {grant.get('expires_at')}")
+            print(f"   Restrictions: {', '.join(grant.get('restrictions', []))}")
+        else:
+            print("❌ Token is INVALID")
+            print(f"   Reason: {result.get('reason')}")
+    
+    sys.exit(0 if result["valid"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/types/agent-adapter.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Universal Agent Adapter Interface
+ * 
+ * This is the core contract that makes the SwarmOrchestrator plug-and-play
+ * with ANY agent system. Each framework (OpenClaw, LangChain, AutoGen, CrewAI,
+ * MCP, or custom agents) implements this interface via an adapter.
+ * 
+ * The SwarmOrchestrator never talks to a specific framework directly —
+ * it talks through this universal interface.
+ * 
+ * @module AgentAdapter
+ * @version 1.0.0
+ */
+
+// ============================================================================
+// CORE TYPES — The universal language all adapters speak
+// ============================================================================
+
+/**
+ * Payload sent to an agent for execution.
+ * Framework adapters translate this into their native format.
+ */
+export interface AgentPayload {
+  /** The action or task to perform */
+  action: string;
+  /** Parameters for the action */
+  params: Record<string, unknown>;
+  /** Optional handoff context from the orchestrator */
+  handoff?: {
+    handoffId: string;
+    sourceAgent: string;
+    targetAgent: string;
+    taskType: 'delegate' | 'collaborate' | 'validate';
+    instruction: string;
+    context?: Record<string, unknown>;
+    constraints?: string[];
+    expectedOutput?: string;
+    metadata?: Record<string, unknown>;
+  };
+  /** Shared state snapshot from the blackboard */
+  blackboardSnapshot?: Record<string, unknown>;
+}
+
+/**
+ * Universal execution context for agent operations
+ */
+export interface AgentContext {
+  /** The agent initiating the request */
+  agentId: string;
+  /** Unique task identifier */
+  taskId?: string;
+  /** Session identifier for multi-turn interactions */
+  sessionId?: string;
+  /** Arbitrary metadata from the host system */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Universal result returned from agent execution.
+ * Framework adapters normalize their native results into this shape.
+ */
+export interface AgentResult {
+  /** Whether execution succeeded */
+  success: boolean;
+  /** Result data (any shape — adapters normalize this) */
+  data?: unknown;
+  /** Error information if execution failed */
+  error?: {
+    code: string;
+    message: string;
+    recoverable: boolean;
+    suggestedAction?: string;
+    /** Framework-specific error details */
+    nativeError?: unknown;
+  };
+  /** Execution metadata */
+  metadata?: {
+    /** Time taken in milliseconds */
+    executionTimeMs?: number;
+    /** Which adapter handled this */
+    adapter?: string;
+    /** Framework-specific trace data */
+    trace?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Information about a discoverable agent
+ */
+export interface AgentInfo {
+  /** Unique agent identifier */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Agent description */
+  description?: string;
+  /** Which adapter provides this agent */
+  adapter: string;
+  /** What the agent can do */
+  capabilities?: string[];
+  /** Current availability */
+  status: 'available' | 'busy' | 'offline' | 'unknown';
+  /** Framework-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Configuration passed to an adapter during initialization
+ */
+export interface AdapterConfig {
+  /** Working directory for file-based operations */
+  workspacePath?: string;
+  /** Framework-specific connection/API settings */
+  connection?: {
+    url?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+  };
+  /** Adapter-specific options */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Capabilities an adapter can declare support for
+ */
+export interface AdapterCapabilities {
+  /** Can stream partial results */
+  streaming: boolean;
+  /** Can run multiple agents concurrently */
+  parallel: boolean;
+  /** Supports two-way agent communication */
+  bidirectional: boolean;
+  /** Can discover agents at runtime */
+  discovery: boolean;
+  /** Supports authentication/trust levels */
+  authentication: boolean;
+  /** Supports stateful multi-turn sessions */
+  statefulSessions: boolean;
+}
+
+// ============================================================================
+// ADAPTER INTERFACE — The contract every adapter must implement
+// ============================================================================
+
+/**
+ * The core adapter interface. Every agent system (OpenClaw, LangChain, etc.)
+ * implements this to plug into the SwarmOrchestrator.
+ * 
+ * Minimal implementation requires: name, version, initialize, executeAgent
+ * Everything else has sensible defaults in BaseAdapter.
+ */
+export interface IAgentAdapter {
+  /** Unique adapter identifier (e.g., "openclaw", "langchain", "autogen") */
+  readonly name: string;
+  /** Adapter version */
+  readonly version: string;
+  /** What this adapter can do */
+  readonly capabilities: AdapterCapabilities;
+
+  // --- Lifecycle ---
+
+  /** Initialize the adapter with configuration */
+  initialize(config: AdapterConfig): Promise<void>;
+  /** Gracefully shut down the adapter */
+  shutdown(): Promise<void>;
+  /** Check if the adapter is ready */
+  isReady(): boolean;
+
+  // --- Agent Execution (REQUIRED) ---
+
+  /** Execute a task on an agent — this is the core operation */
+  executeAgent(
+    agentId: string,
+    payload: AgentPayload,
+    context: AgentContext
+  ): Promise<AgentResult>;
+
+  // --- Agent Discovery (optional) ---
+
+  /** List all agents available through this adapter */
+  listAgents(): Promise<AgentInfo[]>;
+  /** Check if a specific agent is available */
+  isAgentAvailable(agentId: string): Promise<boolean>;
+
+  // --- Health ---
+
+  /** Health check for the adapter and its backing system */
+  healthCheck(): Promise<{ healthy: boolean; details?: string }>;
+}
+
+// ============================================================================
+// REGISTRY TYPES — Managing multiple adapters
+// ============================================================================
+
+/**
+ * Route a request to the right adapter based on agent ID patterns
+ */
+export interface AdapterRoute {
+  /** Glob or regex pattern to match agent IDs (e.g., "lc:*", "autogen:*") */
+  pattern: string;
+  /** Which adapter handles matching agents */
+  adapterName: string;
+  /** Priority if multiple routes match (higher = preferred) */
+  priority?: number;
+}
+
+/**
+ * Configuration for the adapter registry
+ */
+export interface RegistryConfig {
+  /** Default adapter to use when no route matches */
+  defaultAdapter?: string;
+  /** Routing rules to map agent IDs to adapters */
+  routes?: AdapterRoute[];
+  /** Enable automatic agent discovery across all adapters */
+  enableDiscovery?: boolean;
+  /** How often to refresh agent discovery (ms) */
+  discoveryIntervalMs?: number;
+}
+
+// ============================================================================
+// EVENT TYPES — For adapter lifecycle hooks
+// ============================================================================
+
+export type AdapterEventType =
+  | 'adapter:registered'
+  | 'adapter:initialized'
+  | 'adapter:shutdown'
+  | 'adapter:error'
+  | 'agent:execution:start'
+  | 'agent:execution:complete'
+  | 'agent:execution:error'
+  | 'agent:discovered'
+  | 'agent:unavailable';
+
+export interface AdapterEvent {
+  type: AdapterEventType;
+  adapter: string;
+  timestamp: string;
+  data?: unknown;
+}
+
+export type AdapterEventHandler = (event: AdapterEvent) => void;

package/types/openclaw-core.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Type declarations for openclaw-core
+ * This is a stub module for the OpenClaw framework
+ */
+
+declare module 'openclaw-core' {
+  /**
+   * Base interface for all OpenClaw skills
+   */
+  export interface OpenClawSkill {
+    name: string;
+    version: string;
+    execute(
+      action: string,
+      params: Record<string, unknown>,
+      context: SkillContext
+    ): Promise<SkillResult>;
+  }
+
+  /**
+   * Context provided to skill execution
+   */
+  export interface SkillContext {
+    agentId: string;
+    taskId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+  }
+
+  /**
+   * Result returned from skill execution
+   */
+  export interface SkillResult {
+    success: boolean;
+    data?: unknown;
+    error?: {
+      code: string;
+      message: string;
+      recoverable: boolean;
+      suggestedAction?: string;
+      trace?: Record<string, unknown>;
+    };
+  }
+
+  /**
+   * Call another skill within the OpenClaw ecosystem
+   */
+  export function callSkill(
+    skillName: string,
+    params: Record<string, unknown>
+  ): Promise<SkillResult>;
+}