Semantic Model, Tool & Gradient Routing Subsystem Operational Architecture Guide

Comprehensive architectural, operational, and protocol reference for the pkg/router subsystem in ZQK Core.


1. Architectural Overview

In the ZQK autonomous agent architecture, multi-agent swarms, background daemons, and interactive CLI commands interact continuously with diverse Large Language Model (LLM) providers and system-level tools. Disconnected, hardcoded model calls and uncontained tool execution introduce severe failure modes: runaway API costs, latency spikes, cascading timeout failures, and unauthorized filesystem or shell access.

The Semantic Model, Tool & Gradient Routing Subsystem (pkg/router) provides a unified, hardened routing and governance membrane across two foundational operational planes:

  1. Model Gradient Routing: Resolves, budgets, and executes LLM requests across a tiered performance and capability spectrum (fast, standard, heavy, local), with adaptive timeout budgeting and multi-stage fallback escalation.
  2. Tool Scope Enforcement: Intercepts, inspects, and validates tool invocations against strict workspace boundaries, blocked path patterns, and read-only operational modes prior to filesystem or shell execution.
flowchart TD
    subgraph ClientLayer["Upstream Callers"]
        CLI["CLI Commands"]
        Agent["Autonomous Agent Swarm"]
        Daemon["Scheduler / Ambient Daemon"]
    end

    subgraph RouterCore["pkg/router Membrane"]
        GR["GradientRouter (Facade)"]
        MR["ModelRouter (Model Plane)"]
        TR["ToolRouter (Tool Plane)"]
        TE["TimeoutEnvelope (Adaptive Budgets)"]
        TS["ToolScope (Security & Boundaries)"]
    end

    subgraph ModelEndpoints["Model Providers & Tiers"]
        TierFast["TierFast (Flash / Haiku / Mini)"]
        TierStd["TierStandard (Pro / Sonnet / GPT-4o)"]
        TierHvy["TierHeavy (o1 / o3 / Opus / Thinking)"]
        TierLoc["TierLocal (Ollama / vLLM / Air-Gapped)"]
    end

    subgraph ToolExecution["System Tools & Passthrough"]
        FS["Filesystem Operations (read, write, delete)"]
        CMD["Shell Commands & Generation"]
        PT["Passthrough Handlers"]
    end

    ClientLayer -->|"RouteModel(req)"| GR
    ClientLayer -->|"RouteTool(call)"| GR

    GR --> MR
    GR --> TR

    MR --> TE
    MR -->|"Primary / Fallback"| TierFast
    MR -->|"Primary / Fallback"| TierStd
    MR -->|"Primary / Fallback"| TierHvy
    MR -->|"Primary / Fallback"| TierLoc

    TR --> TS
    TR -->|"Validated Execution"| FS
    TR -->|"Validated Execution"| CMD
    TR -->|"Unregistered Fallback"| PT

Core Subsystem Invariants

  1. Statement Test Coverage Invariant (>= 85.0% Floor): The subsystem maintains strict statement test coverage exceeding the 85.0% floor (targeting 100.0%) across all routing logic, timeout calculations, scope validators, and concurrency paths.

  2. Deterministic Tier Classification & Fail-Safe Fallbacks: Every model identifier resolves deterministically to a canonical ModelTier (fast, standard, heavy, local). Unrecognized models fall back cleanly to TierStandard. Fallback execution chains progress sequentially through user-specified or gradient tiers without infinite loops or duplicate evaluations.

  3. Adaptive Timeout Envelope Clamping: Timeout allocations scale adaptively based on base tier durations, requested output token headroom (tokenHeadroom), and input prompt length (byteHeadroom), strictly clamped within configurable minimum and maximum runtime bounds (minTimeout, maxTimeout).

  4. Fail-Closed Workspace Containment & Traversal Prevention: Tool invocations targeting filesystem paths are inspected for traversal tokens (..), path escaping, and sensitive file patterns (.git/config, id_rsa, .env). Mutating operations in read-only scopes are rejected before handler invocation.

  5. Thread-Safe Concurrent Dispatch: All router registrations, scope mutations, metric aggregations, and concurrent route requests are protected by granular sync.RWMutex locks and atomic counters (sync/atomic), ensuring zero race conditions under high-throughput parallel agent swarms.


2. Component Topology

The subsystem is modularized into distinct routing, classification, budgeting, and scoping components:

Component Source File Responsibility
GradientRouter gradient_router.go Unified facade combining model gradient dispatch with scope-aware tool routing, ambient telemetry tracking, and fluent builder construction.
ModelRouter model_router.go Resolves model handlers by exact key or tier, orchestrates multi-stage fallback escalation, and enforces adaptive execution contexts.
ToolRouter tool_router.go Orchestrates tool execution pipelines, manages ordered interceptor chains, auto-extracts target paths, and provides fallback passthrough.
TimeoutEnvelope timeout_envelope.go Computes dynamic, adaptive execution deadlines based on model tier, prompt size, token limits, and configurable bounds.
ModelTier model_tier.go Enumerates model capability tiers, maintains thread-safe explicit tier overrides, and provides regex-free heuristic model classification.
ToolScope tool_router.go Defines filesystem boundaries (AllowedRoots), enforcement modes (strict, permissive, read_only), and forbidden path patterns.

3. Routing & Dispatch Lifecycle

The routing lifecycle enforces structured, sequential verification across both model and tool execution requests.

sequenceDiagram
    autonumber
    actor Agent as Autonomous Agent
    participant GR as GradientRouter
    participant MR as ModelRouter
    participant TE as TimeoutEnvelope
    participant Provider as Model Provider / Handler
    participant TR as ToolRouter
    participant TS as ToolScope
    participant Tool as Tool Handler

    rect rgb(240, 248, 255)
        note over Agent, Provider: Model Routing & Fallback Escalation
        Agent->>GR: RouteModel(ModelRequest)
        GR->>MR: RouteModel(ctx, req)
        MR->>MR: Classify primary tier & deduplicate fallback chain
        loop For Each Tier in Gradient
            MR->>TE: WithTimeoutContext(ctx, tier, req)
            TE-->>MR: (subCtx, cancel, dur)
            MR->>Provider: Invoke handler(subCtx, req)
            alt Handler Success
                Provider-->>MR: ModelResponse
                MR-->>GR: ModelResponse (Attempts, Latency)
                GR->>GR: Update telemetry (RequestsByTier, FallbackEvents)
                GR-->>Agent: ModelResponse
            else Timeout or Error
                Provider-->>MR: Error / DeadlineExceeded
                MR->>MR: Record lastErr & continue to next fallback tier
            end
        end
    end

    rect rgb(245, 255, 245)
        note over Agent, Tool: Tool Scoping & Execution Pipeline
        Agent->>GR: RouteTool(ToolCall)
        GR->>TR: RouteTool(ctx, call)
        TR->>TR: Auto-extract TargetPaths from Arguments
        TR->>TS: ScopeVerificationInterceptor(call)
        alt Path Traversal / Pattern Blocked / ReadOnly Violation
            TS-->>TR: ErrOutOfScope / ErrPermissionDenied
            TR-->>GR: ToolResult(Intercepted=true, Error)
            GR->>GR: Increment ToolCallsIntercepted
            GR-->>Agent: Intercepted Error
        else Path Validated
            TR->>Tool: Invoke handler(ctx, call)
            Tool-->>TR: ToolResult
            TR-->>GR: ToolResult (Duration, Output)
            GR->>GR: Increment ToolCallsTotal
            GR-->>Agent: ToolResult
        end
    end

4. Model Gradient Evaluation & Dynamic Escalation

Model Tiers and Heuristics

ModelTier categorizes LLM capabilities into four distinct performance envelopes:

  • TierFast (fast): Sub-second to low-latency models suitable for triage, classification, summarization, and lightweight tool selection (e.g., Flash, Haiku, GPT-4o-Mini, Turbo variants). Default timeout: 15s.
  • TierStandard (standard): General-purpose reasoning and code generation models balancing latency, intelligence, and token cost (e.g., Pro, Sonnet, GPT-4o). Default timeout: 45s.
  • TierHeavy (heavy): High-order reasoning, deep chain-of-thought, and formal architectural verification models (e.g., o1, o3, Opus, R1, QwQ, Thinking variants). Default timeout: 120s.
  • TierLocal (local): On-premise, self-hosted, or air-gapped endpoints executing via Ollama, vLLM, or local runtimes (e.g., Llama, DeepSeek-Local, Qwen-Local, Mistral-Local). Default timeout: 180s.

Classification Algorithm

Classification resolves in prioritized stages:

  1. Explicit Custom Override: Checks customTierMap under read lock for direct model name matches registered via RegisterModelTier.
  2. Prefix Heuristics: Matches ollama/ or local/ to TierLocal.
  3. High-Priority Fast Identifiers: Substrings turbo, flash, or haiku resolve immediately to TierFast.
  4. Heavy Reasoning Substrings: Substrings o1, o3, opus, reasoning, thinking, r1, qwq resolve to TierHeavy.
  5. Local Family Substrings: Substrings ollama, local, llama, deepseek-local, qwen-local, mistral-local, phi resolve to TierLocal.
  6. Subordinate Fast Heuristics: Substrings 4o-mini, small, fast, or mini (excluding Gemini Pro variants) resolve to TierFast.
  7. Default Fallback: Resolves to TierStandard.

Fallback Execution Chain

When executing a ModelRequest, the ModelRouter constructs a clean, deduplicated gradient list: [PrimaryTier, FallbackTier1, FallbackTier2, ...]

Each tier is evaluated sequentially:

  • A fresh timeout context is derived via TimeoutEnvelope.WithTimeoutContext.
  • If the handler succeeds, execution returns immediately with latency, attempts count, and resolved model tier.
  • If the tier times out or returns an error, the error is recorded, and the router advances to the next tier in the chain.
  • If all tiers fail, the router returns ErrAllTiersFailed wrapping the last recorded error and total attempt count.

5. Tool Routing & Capability Matching Mechanics

Tool Argument & Path Extraction

When a ToolCall does not declare explicit TargetPaths, the router automatically inspects known parameter keys:

  • path
  • file_path
  • target_file
  • absolute_path
  • cwd

Non-string or empty arguments are discarded. The extracted paths are attached to the call for interceptor inspection.

Scope Enforcement Modes

ToolScope supports three operational security postures:

  1. ScopeModeStrict (Default Production Mode): - Traversal tokens (..) trigger immediate ErrPathTraversalDetected. - Paths must reside inside WorkspaceRoot or explicit AllowedRoots. Escaping returns ErrOutOfScope. - Access to blocked patterns (.git/config, .git/hooks, id_rsa, id_ed25519, .env) returns ErrPermissionDenied. - Mutating operations in read-only scopes return ErrReadOnlyViolation.
  2. ScopeModeReadOnly: - Permits read operations across valid roots. - Strictly prohibits write, delete, and mutation tools (write_file, replace_file_content, delete_file, generate_code, or tools containing write, delete, remove, create).
  3. ScopeModePermissive: - Traversal tokens and blocked patterns remain strictly enforced. - Filesystem root containment checks are relaxed to accommodate external tool paths or shared temporary directories.

Interceptor Pipeline Composition

Tool routing uses a recursive wrapper pipeline. Handlers and interceptors execute in FIFO order:

start := time.Now()
chain := handler
for i := len(interceptors) - 1; i >= 0; i-- {
    currentInterceptor := interceptors[i]
    nextHandler := chain
    chain = func(subCtx context.Context, c *ToolCall) (*ToolResult, error) {
        return currentInterceptor(subCtx, c, nextHandler)
    }
}
res, err := chain(ctx, call)

The default interceptor, ScopeVerificationInterceptor, inspects all target paths before any tool handler is invoked.


6. Concurrency & Thread-Safety Guarantees

The pkg/router subsystem guarantees full thread safety across concurrent agent execution:

  1. State Isolation: - ModelRouter: mu sync.RWMutex guards handler registries (modelHandlers, tierHandlers, defaultHandler). - ToolRouter: mu sync.RWMutex guards tool handlers, interceptor slices, and active scopes. - TimeoutEnvelope: mu sync.RWMutex protects base durations, bounds, and headroom values.
  2. Lockless Telemetry Counters: All metrics in GradientRouter use sync/atomic 64-bit unsigned integers:
  • modelRequestsTotal (atomic.Uint64)
  • modelRequestsByTier (map of ModelTier to *atomic.Uint64)
  • toolCallsTotal (atomic.Uint64)
  • toolIntercepted (atomic.Uint64)
  • toolPassthrough (atomic.Uint64)
  • fallbackEvents (atomic.Uint64) Point-in-time snapshots are retrieved via gr.Stats() without blocking active request dispatch.
  1. Goroutine Labeling: Stress testing and concurrent routing utilize github.com/zqk-os/zqk/pkg/goroutinelabels to ensure clean stack traces and runtime categorization.

7. Verification & Three-Fold Proof

In accordance with the ZQK Quality & Verification Invariants, the subsystem adheres to the Three-Fold Proof standard:

Proof Dimension Invariant Verified Implementation Test Vector
Static Floor Invariant Package statement test coverage strictly >= 85.0% floor (measured >= 97.0%). Comprehensive unit test suite covering all branches, edge cases, and sentinel errors.
Operational Dynamic Proof Multi-tier model routing, tool scoping, dynamic headroom calculations, and fallback chain escalation. Direct validation across simulated providers, multi-stage failure cascades, and telemetry counter verification.
Negative Adversarial Boundary Rejection of path traversal sequences, unauthorized writes in read-only scopes, blocked security files, and nil parameters. Explicit negative tests verifying ErrPathTraversalDetected, ErrReadOnlyViolation, ErrOutOfScope, ErrPermissionDenied, ErrNilRequest, and ErrNilToolCall.

Running Subsystem Tests

# Execute targeted router unit test suite with statement coverage profiling
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/router

8. Summary of API Recipes

Creating a GradientRouter via Builder

gr := router.NewGradientRouterBuilder().
    WithFastTimeout(10 * time.Second).
    WithStandardTimeout(30 * time.Second).
    WithHeavyTimeout(90 * time.Second).
    WithLocalTimeout(120 * time.Second).
    WithWorkspaceRoot("/workspace/project").
    WithAllowedRoots("/workspace/shared_cache").
    WithScopeMode(router.ScopeModeStrict).
    WithDefaultModelHandler(func(ctx context.Context, req *router.ModelRequest) (*router.ModelResponse, error) {
        return &router.ModelResponse{Content: "processed"}, nil
    }).
    WithDefaultToolHandler(func(ctx context.Context, call *router.ToolCall) (*router.ToolResult, error) {
        return &router.ToolResult{ToolName: call.ToolName, Output: "executed"}, nil
    }).
    Build()

Executing Model Requests with Fallbacks

resp, err := gr.RouteModel(ctx, &router.ModelRequest{
    Model:         "claude-3-5-sonnet",
    Prompt:        "Synthesize kernel architecture report",
    MaxTokens:     2048,
    PreferredTier: router.TierStandard,
    FallbackChain: []router.ModelTier{router.TierHeavy, router.TierLocal},
})
if err != nil {
    // Handle routing exhaustion
}

Executing Guarded Tool Calls

res, err := gr.RouteTool(ctx, &router.ToolCall{
    ToolName: router.ToolReadFile,
    Arguments: map[string]any{
        router.ArgPath: "/workspace/project/README.md",
    },
})
if err != nil {
    // Scope violation, path traversal, or execution error intercepted
}