2026-03-26-session-context-hints

Ship Log: Session Context Hints

Date: 2026-03-26 Phase: 080-session-context-hints Author: Builder (automated)

What Shipped

Session context hints via X-BR-Session-Context header. Clients send task classification tags (e.g., code-generation,typescript,tools-heavy) on the first request, and BrainstormRouter stores them in Redis for the session. All subsequent requests use the stored hints to pre-seed the auto-selector's complexity classification — eliminating cold-start routing mistakes.

How It Works

1. Client sends X-BR-Session-Context: code-generation,typescript,15-tools header
2. Middleware stores hints in Redis: session-ctx:{api_key_id}:{session_id} with 1hr TTL
3. Subsequent requests look up stored hints automatically (no header needed)
4. Auto-selector uses hints as prior signal for complexity assessment:

• code-generation → +1 (bias toward capable models)
• tools-heavy / N-tools → +2 (needs strong tool calling)
• long-context → +1 (prefer larger context windows)
• simple → -2 (override toward cheap)
• complex → +3 (override toward capable)

1. Response includes X-BR-Session-Context-Active: true when hints are in effect

Lockstep Checklist

Surface	Status	Notes
API	Implemented	New middleware + wired into completions
Docs	Implemented	This ship log
SDK-TS	N/A	Header set via standard extraHeaders
SDK-PY	N/A	Header set via standard extra_headers
MCP	N/A	MCP requests don't use session context
Tests	Implemented	10 middleware tests + 6 auto-selector tests
CLI	N/A	No CLI changes
GTM	N/A	Internal routing optimization
Dashboard	N/A	No dashboard changes

Files Changed

• src/api/middleware/session-context.ts (new) — middleware
• src/api/middleware/session-context.test.ts (new) — 10 tests
• src/api/server.ts (modified) — wire middleware
• src/api/routes/completions.ts (modified) — pass hints to router
• src/router/model-auto-selector.ts (modified) — accept + apply hints
• src/router/model-auto-selector.test.ts (modified) — 6 new tests
• src/router/model-router.ts (modified) — pass hints through
• docs/ship-log/2026-03-26-session-context-hints.md (new)

Design Decisions

• Separate middleware (not in guardian.ts): Guardian handles cost/anomaly, session context is routing intelligence. Clean separation of concerns.
• Fail-open: Redis errors never block request processing. Hints are best-effort enhancement.
• Free-form tags: No fixed vocabulary — forward-compatible. Unknown tags stored but ignored.
• 1hr TTL: Balances session persistence vs. stale context accumulation.
• Overwrite on re-send: Allows mid-session correction without manual cache eviction.