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).