Dispatcher & Security

The Dispatcher is ContextRouter’s gRPC service layer — it receives incoming requests, validates tokens, and routes them to the appropriate LangGraph agent.

gRPC Service

The Dispatcher exposes the core operations of the Router. The primary methods take a ContextUnit and return one or stream them back.

service RouterService {
    rpc ExecuteAgent(ContextUnit) returns (ContextUnit);
    rpc StreamAgent(ContextUnit) returns (stream ContextUnit);
    rpc ExecuteDispatcher(ContextUnit) returns (ContextUnit);
    rpc StreamDispatcher(ContextUnit) returns (stream ContextUnit);
    rpc RegisterTools(ContextUnit) returns (ContextUnit);
    rpc DeregisterTools(ContextUnit) returns (ContextUnit);
    rpc ToolExecutorStream(stream ContextUnit) returns (stream ContextUnit);
}

ExecuteAgent / StreamAgent

Used when you force the execution of a specific graph (e.g., you explicitly want the gardener or matcher agent to run, bypassing intent detection).

ExecuteDispatcher / StreamDispatcher

Used for open-ended interactions. Passes the request to a central routing graph. The detect_intent node will analyze the user’s prompt and automatically decide which sub-agent is best suited to handle it.

RegisterTools / DeregisterTools

Register and deregister external tools for LLM function calling.

ToolExecutorStream

Bi-directional streaming for external tool execution. External projects connect to Router via persistent bidi-streams, allowing the agent to invoke tools on the client side (e.g., SQL queries on a local database) without exposing credentials.

Security Flow

Token Validation & Shield

Before any gRPC request reaches the logic layer, it must survive the Interceptor chain.

As detailed in the Security Integration guide, the Router verifies the ContextToken mathematically.

1. Extract authorization header from metadata
2. Verify token (Ed25519 signature or Shield delegation)
3. Check is_expired()
4. Validate can_access_tenant(tenant_id)
5. Inject validated token into the request context

AI Firewall (Enterprise / Pro Module)

When ContextShield is configured as the Enterprise AI Firewall, Router delegates security checks via a gRPC Scan call in service/shield_check.py. In the Open Source version, this module fails-open and permits request execution directly.

from contextunity.router.service.shield_check import check_user_input

# Scan input for prompt injection and jailbreaks via ContextShield
scan_result = await check_user_input(
    user_input=text,
    request_id=request_id,
    tenant=tenant_id
)

if scan_result.blocked:
    raise SecurityError(f"Blocked by Shield (Pro): {scan_result.reason}")

Note: The Router uses a Token as Single Point of Truth (SPOT) pattern, meaning the caller’s JWT is forwarded to Shield to attribute the security scan correctly. For this to succeed, tokens possessing router:execute implicitly inherit the shield:check authority necessary to be scanned.