Skip to content

22. Dispatcher: The Switchboard

Context and Problem Statement

Cognitive labor in a sovereign system requires abstract capabilities—text generation, visual analysis, vocal perception—but the physical infrastructure is fragmented across discrete local containers (Soulstones), remote APIs (Portals), and peer-to-peer nodes (The Legion).

A single provider often offers overlapping services, creating a complex many-to-many mapping between logical intent and physical substrate. Furthermore, on a single-node architecture, the availability of these capabilities is volatile; a vision model may be "sleeping" to save VRAM. The lack of an intelligent switchboard leads to resource contention, inefficient model loading, and a failure to maintain the Sovereignty Wall (09). The machine requires a Semantic Cortex to resolve abstract desire into executable power.

Requirements

  • Capability-Driven Discovery: Resolution of intents based on functional tags (e.g., text-gen, vision-analysis, stt) rather than hardcoded model identifiers.
  • The Animator Protocol: Mandatory implementation of the Animator interface to bind disparate providers (Local/Cloud/Swarm) to the Agents (20) runtime.
  • The Stasis Handshake: Mandatory coordination with the Orchestrator (23). The Dispatcher must query the physical state of the Rune (08) before binding logic. If the required hardware is "Cold," it must raise a HardwareTransitionRequired signal to trigger the Stasis Protocol.
  • Asynchronous Deferral: The mechanism must support "The Long Sleep." It must be capable of serializing the calling thread and suspending it until the physical body reconfigures itself.
  • Modality Zipping: Capability to "weave" deferred sensory tools into a text-only reasoning agent if the selected provider lacks native multimodal support.
  • Syntax Standardization (UTCP): Adoption of the Universal Tool Calling Protocol (UTCP) as the definitive grammar for all tool definitions, eliminating the "Middleware Tax" of legacy proxies.
  • Sigil-Based Filtering: Integration with The Ward (38) to physically hide privileged tools/models from an Agent based on the active identity's scope.
  • Economic Arbitration: Integration with The Toll (41) to select the most cost-effective provider (Local Power vs. Cloud Tokens) based on the ritual's priority.

Considered Options

Option 1: Static Model Registry

Utilizing a hardcoded mapping that binds reasoning tasks to specific model strings at agent construction.

  • Pros: Zero resolution latency; predictable behavior.
  • Cons: Functional Rigidity. Fails to account for hardware state. If a local model is not resident, the Agent crashes. It cannot autonomously switch to a Portal if the user is offline or if the GPU is occupied.

Option 2: Network-Layer Load Balancers (LiteLLM)

Deploying standard proxies to route traffic based on service name strings.

  • Pros: Broad compatibility with standard OpenAI SDKs.
  • Cons: Semantic Blindness. These tools operate at the network layer. They remain blind to VRAM pressure, model tiers, or functional capabilities. They cannot perform the Stasis Handshake, meaning a request to a cold model simply times out rather than triggering a state swap.

Option 3: The Switchboard (Semantic Resolution)

A two-stage resolution engine that treats hardware states as functional providers, utilizing a generic binding protocol and dynamic toolset composition.

  • Pros:
    • Dynamic Pathfinding: Resolves an abstract intent against available physical configurations in real-time.
    • Logical Parallelism: Enables the Stasis Protocol, allowing the mind to pause while the body changes.
    • Substrate Efficiency: Maximizes the utility of limited local silicon by preferring multimodal containers.

Decision Outcome

The Dispatcher is adopted as the system's Semantic Cortex. It functions as the switchboard that assembles the machine's "Mind" by resolving capabilities into Mind-Bundles.

1. The World Model (Capability Indexing)

At initialization, the Dispatcher constructs an in-memory index of the Sepulcher’s potential. It introspects every Soulstone and Portal in the Codex (12). It creates an inverted index mapping functional tags (e.g., VisionLLM, ReasoningTitan, SpeechCoven) to specific providers. This index is updated dynamically as the Orchestrator manifests or banishes hardware covens.

2. The Animator Handshake (The Stasis Protocol)

The Animator serves as the metaphysical bridge between the Code and the Model. However, an Animator cannot exist without a Body.

  • "The Substrate Check:" When an Agent requires a Capability (e.g., vision), the Dispatcher checks the Orchestrator. If the required Rune (08) is not in a "Warm" state, the Dispatcher invokes the Stasis Protocol. It issues a call_deferred signal, serializing the Agent's state to the Phylactery while the body reconfigures.
  • The Physical Check: Before granting the Animator, the Dispatcher queries the Orchestrator: "Is the vision.coven active?"
  • The Stasis Signal: If the answer is NO, the Dispatcher does not fail. It raises a HardwareTransitionRequired signal.
    • This signal propagates up to the Graph (24).
    • The Graph triggers the Stasis Protocol: the current thread is serialized and saved to the Phylactery (06).
    • Time effectively stops for the Agent while the Orchestrator performs the heavy lifting of swapping VRAM contents.
  • The Reanimation: Once the Orchestrator confirms the new Coven is "Warm," the Dispatcher releases the lock, and the Agent resumes execution as if no time had passed.

3. The Resolution Algorithm (Matchmaking)

When a reasoning step submits a requirement, the Dispatcher executes a multi-stage resolution:

  1. Candidate Selection: All physical (Soulstone) and logical (Portal) entities providing the requested capability are identified.
  2. Context Filtering: The Ward (38) verifies the Sigil's scopes. Providers not visible to the user are pruned.
  3. Economic Arbitration: If multiple candidates exist, The Toll (41) calculates the cost. It prefers "Free" (Local) over "Paid" (Cloud) unless the ritual is marked high_fidelity.
  4. Sovereignty Gate: If LYCHD_SECURE_MODE is active, all Cloud Portals are physically purged from the list.

4. The Mind-Bundle (The Grant)

The Dispatcher does not return a raw model; it returns a Mind-Bundle. This is a configuration package containing:

  • The Animator: The selected model implementation.
  • The Arsenal: A CombinedToolset containing all permitted functions and sensory tools.
  • The Limits: Strictly defined UsageLimits derived from the system's economic laws.
  • "The Late-Bound Mind-Bundle:" The Dispatcher does not return a static agent. It returns a Mind-Bundle—a temporary, situational hydration of a Persona. It binds the Animator (provided by a Rune) to a specific Arsenal of tools (provided by the current Coven's capabilities). This ensures the mind is always a perfect reflection of the body's current physical potential.

5. The Modality Zip (Joint Intelligence)

To resolve the complexity of multi-modal capabilities on disparate hardware, the Dispatcher implements the Modality Zip.

  • Native Pass: If the Animator is a multimodal VisionLLM, the image data is passed directly in the prompt.
  • Decomposed Pass: If the Animator is text-only (e.g., Llama-3), the Dispatcher injects a Deferred Sensory Tool (e.g., call_ocr_container).
  • The Trigger: When the text model calls this tool, it triggers the Stasis Protocol, causing the text model to sleep while the OCR container is summoned.

6. The Pydantic Covenant (The Internal Law)

The Dispatcher rejects intermediate translation protocols (UTCP). It adopts Python Type Hints and Pydantic AI Generics as the definitive contract for all cognitive labor.

  • Type-Safe Sovereignty: Tools are defined as standard Python functions. The Dispatcher uses the model's native schema generation to present these to the Animator.
  • Zero Translation: By using Pydantic models as the "Word," the system eliminates the CPU tax and hallucination risk associated with converting between disparate JSON schemas.

7. The Agent Registry & Emissary Protocol

The Dispatcher functions as the sole keeper of the Agent Registry—a system-wide directory of all manifest minds.

  • The Registry: An in-memory index mapping functional capabilities (e.g., code-assimilation) to specific provider IDs. Extensions register their agents here during the boot sequence.
  • The Emissary Pattern: Remote agents are represented in the registry as Emissaries.
  • The Handover: When the Dispatcher resolves an intent to an Emissary, it does not execute code. It serializes the Pydantic intent and hands it to the A2A Intercom (ADR 25) for external transport. This triggers the Stasis Protocol, allowing the local mind to sleep while the remote iron labors.

8. Health and Pulse

Before granting a Mind-Bundle, the Dispatcher performs a Stateless Pulse. It pings the assigned provider endpoint (/v1/models). If the pulse fails (timeout/error), the Dispatcher triggers an Autonomous Repair Signal to the Orchestrator to investigate or restart the container, protecting the Agent from "Zombie" providers.

Consequences

Positive

  • Hardware Resonance: The system maximizes the utility of limited local VRAM by intelligently selecting multimodal animators or zipping text-models with Sensory Soulstones.
  • Logical Parallelism: The "Stasis Signal" allows logical parallelism in the Graph (multiple branches waiting for different hardware) without violating the physical seriality of the single GPU.
  • Late-Binding Security: Logic never possesses permanent access to tools; it is granted a temporary Mind-Bundle filtered by the user's Sigil at the moment of thought.

Negative

  • Resolution Latency: The calculation of the optimal Mind-Bundle adds a small overhead (10-50ms) to the initiation of every step.
  • Registry Complexity: Maintaining a synchronized map of providers, capabilities, and hardware states requires robust handling of extension registration edge-cases.