session-mesh

Purpose

This skill manages session topologies in distributed communication systems. It enables discovery of active sessions, maintains a specialization registry, allows steering or terminating sub-agents, and handles session keys for secure interactions. Use it to build resilient mesh networks where agents communicate dynamically.

When to Use

• When monitoring or managing distributed sessions in real-time, such as in IoT fleets or multi-agent AI systems.
• For tasks involving sub-agent control, like rerouting traffic or scaling resources in a mesh topology.
• In scenarios requiring session key management for authentication, e.g., secure data exchange between agents.
• Avoid if you're working with isolated, non-distributed systems; this is optimized for interconnected environments.

Key Capabilities

• Discover alive sessions: Query active sessions using GET /api/session-mesh/alive with query parameters like ?filter=active.
• Specialization registry: Register sub-agent specializations via POST /api/session-mesh/registry with a JSON body, e.g., {"specialization": "image-processing", "agent_id": "123"}.
• Steer sub-agents: Redirect agents using CLI flag --direction (e.g., north/south) or API endpoint POST /api/session-mesh/steer with payload {"agent_id": "456", "direction": "east"}.
• Kill sub-agents: Terminate agents via CLI command session-mesh kill --agent-id 789 or API DELETE /api/session-mesh/agents/789.
• Session keys: Generate keys with POST /api/session-mesh/keys, returning a secure token for authentication.

Usage Patterns

• Basic workflow: First, discover sessions with a GET request, then use the response to steer or kill agents as needed. Always check for alive status before actions.
• Registry pattern: Register specializations during setup, then query the registry before assigning tasks to ensure compatibility.
• Error-resilient pattern: Wrap API calls in try-catch blocks and retry on transient errors; use session keys in every authenticated request.
• Sub-agent management: For mesh networks, periodically poll alive sessions and steer agents based on load, e.g., every 30 seconds via a scheduled script.
• Key handling: Always generate a new session key per interaction and store it securely; use it in headers for subsequent API calls.

Common Commands/API

• CLI Commands:
  • List alive sessions: session-mesh list --filter alive --output json. Requires $SESSION_API_KEY set in environment.
  • Steer an agent: session-mesh steer --agent-id 123 --direction west. Example: First run export SESSION_API_KEY=your_key then execute.
  • Kill an agent: session-mesh kill --agent-id 456 --force. Use --force for immediate termination without confirmation.
  • Register specialization: session-mesh register --spec "data-analysis" --agent-id 789. Config format: YAML file with key-value pairs, e.g., spec: data-analysis.
• API Endpoints:
  • Discover sessions: GET https://api.example.com/api/session-mesh/alive?filter=active. Headers: {'Authorization': 'Bearer $SESSION_API_KEY'}.
  • Code snippet (Python):

    import requests; import os
    response = requests.get('https://api.example.com/api/session-mesh/alive', headers={'Authorization': f'Bearer {os.environ.get("SESSION_API_KEY")}'})
    print(response.json())

  • Steer agent: POST https://api.example.com/api/session-mesh/steer with body {"agent_id": "123", "direction": "north"}. Response includes status code 200 on success.
  • Code snippet (curl):

    curl -X POST https://api.example.com/api/session-mesh/steer \
    -H "Authorization: Bearer $SESSION_API_KEY" \
    -d '{"agent_id": "123", "direction": "north"}'

  • Config format: JSON payloads for API, e.g., {"session_key": "abc123", "ttl": 3600} for key generation.

Integration Notes

• Authentication: All commands and APIs require a session key. Set it via environment variable: export SESSION_API_KEY=your_secure_key. Never hardcode keys; use secure vaults.
• Dependencies: Integrate with distributed-comms cluster by including the skill ID "session-mesh" in your AI agent's config file, e.g., JSON: {"skills": ["session-mesh"], "cluster": "distributed-comms"}.
• Configuration: Use a YAML config for multi-session setups, e.g.:

  sessions:
    - id: 123
    - filter: alive

  Load it with session-mesh load-config path/to/config.yaml.

• Testing: Run integration tests in a sandbox environment; mock API responses for endpoints like /api/session-mesh/alive to simulate failures.

Error Handling

• Common errors: HTTP 404 for non-existent agents (e.g., when killing an invalid ID); handle by checking response.status_code == 404 and logging the error.
• Authentication failures: If $SESSION_API_KEY is invalid, expect 401 Unauthorized; resolve by regenerating the key via POST /api/session-mesh/keys and retry.
• Prescriptive steps: Always validate inputs before commands, e.g., check if agent_id exists via a prior GET request. For CLI, use --verbose flag to debug, e.g., session-mesh list --filter alive --verbose. In code, wrap calls like this:

  try:
      response = requests.post(url, headers=headers)
      response.raise_for_status()
  except requests.exceptions.HTTPError as e:
      print(f"Error: {e.response.status_code} - {e.response.text}")

• Retry logic: Implement exponential backoff for network errors; limit retries to 3 attempts.

Graph Relationships

• Related to cluster: "distributed-comms" for interconnected agent management.
• Connects with tags: "sessions" (shares data with session-based skills), "topology" (links to network mapping tools), "mesh" (integrates with peer-to-peer systems), "subagents" (depends on sub-agent control skills like agent-lifecycle).