With the session store in place (2.4.2), the proxy needs to wire session lifecycle into the request handler — after authentication and before LLM forwarding for session creation, and after the LLM response for checkpoint creation. Session writes are non-blocking (async after response) to avoid adding to proxy overhead.
Milestone 2.4.3 — Proxy Session Lifecycle Management
Status: Planned
Goal: 2.4 — Session tracking infrastructure
Phase: 2 — Single Provider End-to-End
Estimated effort: 2–3 days
Why This Milestone Exists
With the session store in place (2.4.2), the proxy needs to wire session lifecycle into the request handler — after authentication and before LLM forwarding for session creation, and after the LLM response for checkpoint creation. Session writes are non-blocking (async after response) to avoid adding to proxy overhead.
Branch
feature/m2-4-3-proxy-session-lifecycle
PR Title
feat(proxy): session lifecycle management in LLM request handler (m2.4.3)
Session ID propagation
The client optionally sends X-IBEX-Session-ID to associate a request with an existing session. The proxy also returns X-IBEX-Session-ID in every response so the client can track it.
Client → Proxy: X-IBEX-Session-ID: <uuid> (optional)
Proxy → Client: X-IBEX-Session-ID: <uuid> (always; the session UUID for this turn)The non-blocking session write pattern
1. [Hot path] Resolve session (cache: Redis session state, miss: Postgres GetOrCreate)
2. [Hot path] Forward request to LLM provider
3. [Hot path] Stream/return response to client — session ID in response header
4. [Async, after response] AppendCheckpoint (Postgres write — does NOT block client)
5. [Async, after response] Update session statsThe async post-response processing is done in a goroutine launched after the response writer is closed. It has its own context with a 5-second deadline (not the request context, which is cancelled when the response is sent).
Acceptance Criteria
-
X-IBEX-Session-IDreturned in every LLM response header - Checkpoint written after every completed turn (both streaming and non-streaming)
- Checkpoint write failure does NOT affect LLM response (async)
- Session created automatically when
X-IBEX-Session-IDabsent from request - Session reused when
X-IBEX-Session-IDmatches existing session in same org/agent - Cross-org session ID reuse is impossible (session lookup always includes org_id)
Last updated on