<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3.7-agent-middleware-pipeline -->

# Agent Middleware Pipeline

- src/agent/middleware/cache.rs
- src/agent/middleware/compaction.rs
- src/agent/middleware/context_build.rs
- src/agent/middleware/feedback.rs
- src/agent/middleware/injection_scan.rs
- src/agent/middleware/memory_injection.rs
- src/agent/middleware/metrics.rs
- src/agent/middleware/mod.rs
- src/agent/middleware/provider_resolution.rs
- src/agent/middleware/session.rs
- src/agent/middleware/session_save.rs
- src/agent/middleware/token_budget.rs
- src/agent/pipeline.rs

The Agent Middleware Pipeline is a modular framework for processing inbound messages through a series of ordered, cross-cutting concerns before they reach the core LLM execution engine. This design allows ZeptoClaw to decouple complex logic—such as safety scanning, session management, and context compaction—from the primary agent loop.

## Overview

The pipeline is built around the `Middleware` trait [src/agent/middleware/mod.rs62-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L62-L78) A `Pipeline` [src/agent/pipeline.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/pipeline.rs) composes these middlewares into an ordered chain that wraps a `Terminal` executor.

### Data Flow

1. Inbound : A message arrives via the MessageBus .
2. Pipeline Construction : The AgentLoop builds a pipeline using a PipelineBuilder .
3. Context Initialization : A PipelineContext src/agent/middleware/mod.rs 110-140 is created, containing the inbound message and shared Subsystems .
4. Middleware Execution : The context flows through each middleware in insertion order.
5. Terminal Execution : The innermost "Terminal" (the Core Loop) executes the LLM and tool calls.
6. Wrap-up : Middlewares process the PipelineOutput in reverse order as the stack unwinds.

### Pipeline Composition Diagram

The following diagram illustrates the relationship between the middleware chain and the shared subsystems.

```

```

Sources: [src/agent/middleware/mod.rs1-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L1-L15) [src/agent/middleware/mod.rs181-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L181-L200) [src/agent/pipeline.rs1-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/pipeline.rs#L1-L50)

## The Middleware Trait

Every middleware must implement the `Middleware` trait, which defines its name and a `handle` method for asynchronous execution.

### Terminal Executor Pattern

The pipeline ends with a `Terminal` [src/agent/pipeline.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/pipeline.rs) Unlike middleware, a terminal does not have a "next" step; it is responsible for producing the final `PipelineOutput`. In production, the terminal is typically the `CoreLoop` which handles the actual LLM interaction and tool execution cycles.

Sources: [src/agent/middleware/mod.rs62-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L62-L78) [src/agent/middleware/metrics.rs35-40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/metrics.rs#L35-L40)

## Ordered Middleware Chain

ZeptoClaw uses a specific sequence of middlewares to ensure safety and efficiency.

### 1. Safety and Metrics (Outer Layers)

- MetricsMiddleware : Records execution timing and logs errors. It records token usage into the MetricsCollector src/agent/middleware/metrics.rs 40-75
- InjectionScanMiddleware : Scans ctx.inbound.content for prompt injection patterns src/agent/middleware/injection_scan.rs 46-51 It blocks messages from untrusted "webhook" channels while warning for others src/agent/middleware/injection_scan.rs 54-72

### 2. Session and Identity

- SessionMiddleware : Uses SessionManager to load or create a Session based on the session_key src/agent/middleware/session.rs 43-52 It appends the current user message to the session history src/agent/middleware/session.rs 61-62
- ProviderResolutionMiddleware : Resolves which LLMProvider and model to use, checking for overrides in message metadata (e.g., provider_override ) src/agent/middleware/provider_resolution.rs 48-64

### 3. Context Augmentation

- MemoryInjectionMiddleware : Searches LongTermMemory (LTM) for relevant facts and populates ctx.memory_override src/agent/middleware/memory_injection.rs 40-57
- CompactionMiddleware : Monitors context urgency via ContextMonitor . If thresholds are exceeded, it applies recovery tiers: truncation, tool result shrinking, or summarization src/agent/middleware/compaction.rs 45-90
- ContextBuildMiddleware : Assembles the final message list for the LLM, including the system prompt, session history, and memory overrides src/agent/middleware/context_build.rs 45-67

### 4. Execution Guards

- TokenBudgetMiddleware : Resets per-run counters for TokenBudget and ToolCallLimitTracker src/agent/middleware/token_budget.rs 41-44 It short-circuits if the budget is already depleted src/agent/middleware/token_budget.rs 49-54
- CacheMiddleware : Computes a cache key from the model, system prompt, and user content src/agent/middleware/cache.rs 57-71 On a hit, it returns the cached response immediately src/agent/middleware/cache.rs 77-83

### 5. Persistence (Post-Execution)

- SessionSaveMiddleware : An "outer-wrap" middleware that persists the Session to storage only if the pipeline execution was successful ( Ok ) src/agent/middleware/session_save.rs 43-68

Sources: [src/agent/middleware/mod.rs7-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L7-L17) [src/agent/middleware/metrics.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/metrics.rs#L1-L20) [src/agent/middleware/session.rs1-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/session.rs#L1-L22) [src/agent/middleware/compaction.rs1-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/compaction.rs#L1-L15)

## System Integration Diagram

This diagram maps Natural Language concepts to the specific Code Entities used in the pipeline.

```

```

Sources: [src/agent/middleware/mod.rs110-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/mod.rs#L110-L140) [src/agent/middleware/session.rs48-52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/session.rs#L48-L52) [src/agent/middleware/memory_injection.rs48-52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/memory_injection.rs#L48-L52) [src/agent/middleware/token_budget.rs43-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/middleware/token_budget.rs#L43-L44)
