docs/architecture/adr-001-middleware-refactor.md

ADR-001: Middleware Architecture Refactor

Status: ACCEPTED Date: 2025-12-06 Decision Makers: Development Team

---

Context

The current src/middleware/ folder is misleadingly named. It contains SubIterationMiddleware, which implements a workflow pattern (team→judge loop), not the interceptor middleware pattern used by Microsoft Agent Framework.

Additionally, we're missing proper middleware implementations for:

• Retry logic on transient errors (429, 500, 502, 503, 504)
• Token usage tracking for cost monitoring

---

Decision

1. Rename src/middleware/ to src/workflows/ to accurately reflect what it contains
2. Create new src/middleware/ with proper MS-pattern middleware:
   • RetryMiddleware(ChatMiddleware) - exponential backoff retry
   • TokenTrackingMiddleware(ChatMiddleware) - token usage logging

---

Consequences

Positive

• Clearer codebase organization
• Proper use of MS Agent Framework patterns
• HuggingFace 429 crashes will be handled gracefully
• Token usage will be visible for cost monitoring

Negative

• Requires updating imports in src/orchestrators/hierarchical.py
• One-time migration effort

Neutral

• Aligns with Microsoft Agent Framework conventions

---

Implementation

See SPEC-21: Middleware Architecture Refactor for detailed implementation steps.

---

References

• Microsoft Agent Framework _middleware.py
• P2 Hardening Issues Issue 2 & 3