feat: Context reset with structured handoff artifacts for long-running sessions

[ryaneggz]

Summary

Orchestra's CompactingMiddleware summarizes history in-place, but this is insufficient for models exhibiting "context anxiety" — agents start wrapping up prematurely as the context window fills. Full context resets with structured handoff artifacts give the next agent a clean slate.

This feature introduces:

• ContextResetMiddleware — monitors context utilization and triggers resets when a configurable threshold (default 80%) is exceeded
• HandoffArtifact schema — standardized structured output capturing completed work, in-progress tasks, remaining tasks, key decisions, files modified, and a state summary
• Per-assistant context_strategy — configurable as compact, reset, or auto (model-aware default: compact for Opus-class, reset for Sonnet-class)
• Session tracking — threads track session boundaries with metadata for UI rendering
• Frontend UX — visual dividers at reset boundaries, expandable handoff summaries, session navigator for long threads
• Planner/evaluator integration — plan files, evaluator configs, and sprint contract state persist through resets

Key Files

File	Status	Description
backend/src/schemas/entities/handoff.py	New	HandoffArtifact Pydantic schema
backend/src/utils/context_reset.py	New	ContextResetMiddleware implementation
backend/src/schemas/entities/llm.py	Modify	Add context_strategy field to Assistant schema
backend/src/utils/middleware.py	Modify	Register ContextResetMiddleware
frontend/src/components/chat/SessionDivider.tsx	New	Visual divider at session boundaries
frontend/src/components/chat/HandoffSummary.tsx	New	Expandable handoff artifact display

Spec & Plan

• Spec: /.claude/specs/context-reset-handoff.md
• Plan: /.claude/plans/context-reset-handoff.md

Risks

• Handoff quality: If the agent produces a poor summary, the next session starts with bad context. Mitigation: structured schema forces completeness; add validation.
• Token overhead: Producing the handoff costs tokens. Mitigation: handoff prompt is short and structured.
• Race conditions: User message during reset could be lost. Mitigation: queue incoming messages during reset, deliver to new session.

[ryaneggz]

Frontend Session UX Analysis

1. Current Message Rendering Architecture

Message list rendering lives in frontend/src/components/lists/ChatMessages.tsx. Messages are rendered using @tanstack/react-virtual (useVirtualizer) for performance — each message is absolutely positioned via translateY() inside a container whose height equals virtualizer.getTotalSize(). This is important because:

• The virtualizer operates on messages.length — it has no concept of non-message items (like dividers).
• Inserting session dividers requires either (a) treating them as items in the messages array (synthetic entries with a special type), or (b) overlaying them via a separate mechanism keyed to virtualizer row positions.

Option (a) is the recommended approach — inject synthetic { type: "session_divider", session_number, handoff, timestamp } entries into the messages array inside formatMessages() (in frontend/src/lib/utils/format.ts). The Message component in ChatMessages.tsx already switches on message.type (human, user, tool_input, tool, ai, assistant), so adding a session_divider branch is a natural extension.

Message flow:

1. useThread.loadThread() fetches checkpoints via searchThreads("list_checkpoints", { thread_id }) → extracts .values.messages
2. formatMessages() normalizes raw messages into renderable items (splitting tool_calls into tool_input entries, propagating agent_name, etc.)
3. ChatMessages receives the flat array and renders via virtualizer
4. During streaming, useChat.handleMessages() processes SSE payloads and appends/updates messages in in_mem_messages

2. Where Session Boundary Data Would Come From

The spec says session boundaries are stored in thread metadata (session_boundaries array with session_number, handoff_artifact_path, timestamp, trigger_reason). This data would arrive via:

• On thread load: useThread.loadThread() already reads latestCheckpoint.metadata — session boundary data would be available here as threadData.session_boundaries.
• During streaming: A new SSE event type (e.g., "context_reset") would need to be added to the StreamEvent union in frontend/src/lib/entities/stream.ts and handled in useChat.handleMessages() / convertEventToLegacy(). This would allow real-time insertion of session dividers mid-stream.

Gap identified: The spec does not detail the real-time streaming protocol for context resets. During a long-running stream, when the backend triggers a reset, the frontend needs to:

1. Receive a context_reset event with the handoff artifact
2. Insert the session divider into the message list
3. Continue receiving messages from the new session seamlessly

This should be added to the spec as a streaming protocol requirement.

3. SessionDivider Component — Design Approach

Model after: The ToolTimeline + ToolTimelineItem pattern (in frontend/src/components/timeline/). These components already implement:

• A vertical timeline line with dots (status indicators)
• Expandable/collapsible content via useState(isExpanded) with chevron toggle
• Compact header with preview text, full content on expand

Recommended design for SessionDivider.tsx:

┌─────────── Session 2 started · 2 min ago ──────────┐
│  ▸ Handoff summary: "Completed API routes, moving   │
│    to frontend integration..."                       │
└─────────────────────────────────────────────────────┘

• Use the existing Separator component (frontend/src/components/ui/separator.tsx — Radix UI) as the horizontal line
• Wrap the expandable content with the existing Collapsible / CollapsibleTrigger / CollapsibleContent from @radix-ui/react-collapsible (frontend/src/components/ui/collapsible.tsx) — this is already installed but lightly used
• Could also use the Accordion component (frontend/src/components/ui/accordion.tsx) which has built-in animation (animate-accordion-up/down)

4. HandoffSummary Component — Expandable Pattern

The ToolTimelineItem component is the best existing analog for HandoffSummary.tsx:

• Has a clickable header row with icon, status badge, and preview text
• Toggles isExpanded state to show/hide detailed content
• Uses ChevronDown / ChevronUp icons for expand affordance
• Content area has max-h-[400px] overflow-auto for large payloads

The handoff artifact fields map well to a structured card:

Field	Display
completed_work	Checkmark list (green)
in_progress	Spinner/dot indicator
remaining_tasks	Bullet list
key_decisions	Collapsible sub-section
files_modified	Monospace file paths
current_state_summary	Bold summary text

5. Gaps & Recommendations

Gap 1 — Virtualizer integration: The spec says "insert SessionDivider + HandoffSummary between messages" but doesn't address that ChatMessages uses useVirtualizer with count: messages.length. Session dividers must be injected as items in the messages array (not as separate DOM elements) or the virtualizer's row count and measurement will be incorrect. Recommendation: Add synthetic session_divider entries in formatMessages(), gated on the presence of session_boundaries metadata passed alongside messages.

Gap 2 — Session navigation for long threads: The spec mentions a "session navigator for long threads with many resets" as a stretch goal but provides no design detail. For threads with 5+ sessions, a floating pill/chip bar (similar to the ChatUtilityRow pattern in the composer area) would work:

[Session 1] [Session 2] [Session 3 ← current]

Each chip would call virtualizer.scrollToIndex(sessionStartIndex) to jump. This requires maintaining a sessionStartIndices map built during formatMessages().

Gap 3 — Streaming protocol for real-time resets: The SSE event types in frontend/src/lib/entities/stream.ts currently support metadata, messages, values, error, aborted, and done. A new context_reset event type is needed. The convertEventToLegacy() function in useChat.ts and handleMessages() would need to handle this event by:

1. Injecting a session divider into in_mem_messages
2. Updating thread metadata with the new session boundary
3. Optionally showing a toast notification ("Session 2 started — context was reset")

Gap 4 — Shared thread page: SharedThreadPage.tsx also uses ChatMessages to render messages. Session dividers should work there too. Since shared threads load messages via formatMessages(data.thread.messages), the same synthetic-entry approach in formatMessages() would cover this automatically if session boundary data is included in the shared thread response.

Gap 5 — displayModel across sessions: When a context reset changes the underlying model (e.g., auto strategy switching from Sonnet to Opus), the model attribution shown below AI messages (message.model || displayModel) should reflect the model used in that specific session. The handoff artifact should carry the model used so the SessionDivider can display it.

6. Implementation Order Recommendation

1. Backend first: Define session_boundaries in thread metadata, expose via checkpoint/thread API, add context_reset SSE event type
2. formatMessages() extension: Accept optional sessionBoundaries param, inject synthetic session_divider entries at correct positions
3. SessionDivider.tsx: Simple horizontal divider with session label, using Separator + styled text
4. HandoffSummary.tsx: Expandable card using Collapsible pattern, nested inside SessionDivider
5. ChatMessages.tsx: Add session_divider type branch in the Message component's render switch
6. Streaming integration: Handle context_reset event in useChat.handleMessages()
7. Session navigator (stretch): Floating chip bar with scrollToIndex support

Files Referenced

• frontend/src/components/lists/ChatMessages.tsx — main message renderer (virtualizer)
• frontend/src/lib/utils/format.ts — formatMessages() normalization pipeline
• frontend/src/lib/utils/message.ts — StreamMessageHandler for SSE processing
• frontend/src/hooks/useChat.ts — chat hook with SSE handling
• frontend/src/hooks/useThread.ts — thread loading, checkpoint fetching
• frontend/src/context/ChatContext.tsx — context provider composing all hooks
• frontend/src/lib/entities/stream.ts — SSE event type definitions
• frontend/src/components/timeline/ToolTimelineItem.tsx — expandable tool card (best pattern analog)
• frontend/src/components/ui/collapsible.tsx — Radix collapsible (available, underused)
• frontend/src/components/ui/accordion.tsx — Radix accordion with animation
• frontend/src/components/ui/separator.tsx — horizontal/vertical separator
• frontend/src/pages/chat/ChatPanel.tsx — chat page layout
• frontend/src/pages/share/SharedThreadPage.tsx — shared thread rendering

[ryaneggz]

Middleware Extension & Architecture Analysis

1. Context Utilization Tracking — Current State & Gaps

Current CompactingMiddleware approach:

• Token estimation uses a len(content) // 4 heuristic (line 59 in compacting.py). This is a rough character-to-token approximation, not model-aware — it does not account for BPE differences between tokenizers (Anthropic cl100k vs. OpenAI tiktoken vs. Gemini).
• should_compact() compares estimated tokens against a flat threshold (DEFAULT_COMPACTION_TOKEN_THRESHOLD = 170,000 tokens from env COMPACTION_TOKEN_THRESHOLD).
• There is no concept of context window utilization percentage today. The threshold is an absolute number, not relative to the model's context window size. This means the same threshold applies to a 200K Sonnet model and a 1M Opus model identically, which is exactly the gap the spec identifies.

What ContextResetMiddleware needs differently:

• It needs a model-to-context-window mapping to compute utilization = estimated_tokens / model_context_window. No such mapping exists anywhere in the codebase today. The ChatModels enum in backend/src/constants/llm.py lists model identifiers but stores no context window sizes.
• Recommendation: Add a MODEL_CONTEXT_WINDOWS: dict[str, int] mapping in backend/src/constants/llm.py (or a new backend/src/constants/context_windows.py) keyed by model prefix patterns. The "auto" strategy also needs this to distinguish Opus-class vs. Sonnet-class models for strategy selection.

2. Mid-Stream Agent Spawning — Architecture Constraint

Can a context reset "spawn a new agent" mid-stream?

No — not with the current architecture. Here's why:

• The Orchestra class (line 460, agents/__init__.py) wraps a CompiledStateGraph created once via init_graph() → create_deep_agent(). The graph is compiled at construction time with a fixed model, tools, subagents, middleware, and backend. There is no mechanism to replace or restart the graph mid-execution.
• In stream_generator() (stream.py, line 323), the agent is constructed once, then agent.astream() is iterated to completion. The SSE generator yields chunks until the stream finishes, then _persist_final_state() saves the checkpoint. There is no re-entry point.
• The @wrap_model_call decorator pattern (used by both compaction_middleware and the proposed ContextResetMiddleware) intercepts individual model calls within the agent loop. It can modify request.state["messages"] before the model sees them (as compaction does), but it cannot terminate the current graph execution and start a new one.

Viable implementation approaches (in order of recommendation):

1. Post-response reset (recommended): The middleware detects threshold breach after a model call, injects a "produce handoff" instruction, lets the agent produce the handoff in its next turn, then the response handler (in stream_generator) detects the handoff signal, persists state, constructs a new agent, and continues streaming from the new agent. This aligns with the existing fallback pattern where stream_generator already reconstructs agents on Daytona/MCP errors (lines 427-444).

2. Two-request pattern: When the middleware detects threshold breach, it emits a special SSE event (context_reset) to the frontend. The frontend then automatically dispatches a new /llm/stream request with the handoff artifact as context. This is simpler but requires frontend coordination.

3. Graph-level interrupt: Use LangGraph's interrupt/checkpoint mechanism to pause the graph, save state, and resume with a new graph instance reading from the same checkpoint. This is theoretically cleaner but would require deep integration with the AsyncPostgresSaver checkpointer and may introduce complexity around checkpoint format compatibility.

3. Session Boundary Persistence

Thread metadata in the store:

• Threads are stored via ThreadRepo → BaseStore.aput() with namespace (user_id, "threads"). The Thread entity (store.py) has a generic metadata: Optional[dict] field, which can hold session boundary data without schema changes.
• _persist_final_state() in stream.py already updates thread data at the end of every stream with thread_id, checkpoint_id, assistant_id, messages, files, todos. Adding session_boundaries to this update dict is straightforward.
• Important constraint: ThreadRepo.update() (line 75, thread_repo.py) truncates messages to THREAD_SNAPSHOT_MESSAGE_COUNT = 20. If a handoff artifact is stored as a message, it could be truncated in long threads. Handoff artifacts should be stored separately — either in thread metadata or as files in the StateBackend (as the spec suggests: /HANDOFF-{session_number}.md).

4. Race Condition: User Messages During Reset

The spec acknowledges this risk but the current architecture provides a natural mitigation:

• In the streaming path, stream_generator() holds a single async for loop over agent.astream(). The SSE connection is the serialization boundary — no new user messages can be injected into the current agent execution because FastAPI processes one request per SSE connection.
• A race condition only occurs if the user sends a new HTTP request (new message) while the previous stream is still processing the reset. This is handled by the LangGraph checkpointer — the new request will wait for the checkpoint to be released (Postgres row-level locking via AsyncPostgresSaver).
• If using approach (1) above (post-response reset within the same stream), there is no race condition because the entire reset happens within a single HTTP request's lifetime.

5. should_compact() vs. Reset Trigger Relationship

The current should_compact() (line 62) returns True when estimated tokens >= threshold. For the "auto" strategy:

• Compaction fires first (it's earlier in the middleware stack). If compaction reduces tokens below the reset threshold, no reset occurs.
• Reset fires if compaction is insufficient — i.e., even after summarization, the context is still too large (or compaction is disabled for this assistant).
• The reset threshold should be configured higher than the compaction threshold (e.g., compaction at 50% utilization, reset at 80%) so compaction gets multiple chances before a hard reset occurs.
• With context_strategy: "reset", compaction middleware should be skipped entirely for that assistant, and only the reset middleware runs. The init_default_middleware() function would need to accept a strategy parameter or the middleware itself would need to check the assistant's strategy from the runtime context.

6. Auto Strategy: Model-Specific Context Window Sizes

Where should model context windows live?

There are no model-specific context window sizes anywhere in the codebase today. The dynamic_model_selection middleware (middleware.py, line 146) selects models based on conversation depth and query complexity keywords, but never references context window limits.

Recommended location: backend/src/constants/llm.py alongside the ChatModels enum. Example structure:

MODEL_CONTEXT_WINDOWS: dict[str, int] = {
    "anthropic:claude-opus": 1_000_000,
    "anthropic:claude-sonnet": 200_000,
    "anthropic:claude-haiku": 200_000,
    "openai:gpt-5": 200_000,
    "openai:gpt-4.1": 1_000_000,
    "google_genai:gemini-2.5": 1_000_000,
    # ... prefix-matched
}

MODEL_STRATEGY_DEFAULTS: dict[str, str] = {
    "anthropic:claude-opus": "compact",
    "anthropic:claude-sonnet": "reset",
    "anthropic:claude-haiku": "reset",
    # default: "compact" for unknown models
}

Prefix matching (longest match wins) would allow new model versions to inherit defaults without code changes.

Summary of Key Findings

Question	Finding
Token estimation accuracy	Rough len//4 heuristic, not model-aware. Adequate for threshold detection, not precise.
Mid-stream agent spawning	Not possible in current graph architecture. Post-response reset within stream_generator is the viable path.
Session boundary storage	Thread metadata dict or StateBackend files. Must avoid message truncation in ThreadRepo.update().
Race conditions	Naturally mitigated by single-connection SSE model and Postgres checkpoint locking.
should_compact() vs. reset	Two-tier system: compaction first (lower threshold), reset if insufficient (higher threshold). Strategy field controls which fires.
Model context windows	No mapping exists today. Must be added to constants/llm.py for both utilization % and auto strategy.

Recommended Implementation Order

1. MODEL_CONTEXT_WINDOWS + MODEL_STRATEGY_DEFAULTS in constants
2. HandoffArtifact schema in schemas/entities/handoff.py
3. ContextResetMiddleware as @wrap_model_call in utils/context_reset.py
4. context_strategy field on Assistant schema
5. Post-response reset logic in stream_generator() (detect handoff → reconstruct agent → continue streaming)
6. Session boundary tracking in thread metadata
7. Frontend: SessionDivider + HandoffSummary components
8. Tests throughout

[ryaneggz]

Middleware Stack Ordering Analysis for Context Reset

Current Stack Context

Orchestra's init_default_middleware returns middleware that is appended after deepagents' internal stack inside create_deep_agent. The internal deepagents stack already includes its own SummarizationMiddleware (via create_summarization_middleware). Orchestra's compaction_middleware is a separate, additional compaction layer at position 1 of the Orchestra-specific list.

The framework composes middleware with first in list = outermost layer.

Where ContextResetMiddleware Should Go

The ContextResetMiddleware monitors context utilization (input tokens / model context window) and triggers a full context reset when a threshold (default 80%) is hit. This is fundamentally different from compaction -- it does not summarize in-place; it produces a HandoffArtifact and spawns a fresh agent session.

Recommended position: immediately before compaction_middleware (new position 1), making it the outermost Orchestra middleware.

stack = [
    context_reset_middleware,    # 1. NEW: Check context utilization, trigger reset if >80%
    compaction_middleware,       # 2. Summarize old messages (runs only if no reset triggered)
    add_ai_message_metadata,    # 3. Tag AI messages
    cache_metrics_middleware,    # 4. Log cache hit ratios
    retry_model,                # 5. Retry on failure
    *pii_middleware(),           # 6-7. PII filtering
    AutoEvictMiddleware(...),    # 8. Evict large tool results
]

Rationale:

1. Must run before compaction: If context is at 85% utilization, you want to decide "reset or compact?" before compaction runs. If compaction runs first and shrinks the context, context reset might never trigger because the post-compaction size is under threshold. The context_strategy field determines which path to take:

   • "reset" mode: ContextResetMiddleware triggers, compaction is skipped (the handler it calls will still invoke inner middleware, but messages are already replaced with the handoff artifact).
   • "compact" mode: ContextResetMiddleware passes through, compaction runs as usual.
   • "auto" mode: Middleware checks model class (Opus = compact, Sonnet = reset) and decides.

2. Interaction with deepagents' internal SummarizationMiddleware: The internal deepagents SummarizationMiddleware runs as part of the deepagents stack (before Orchestra's middleware in the composition chain, meaning it's "inner" to Orchestra's middleware). When context reset triggers:

   • Orchestra's ContextResetMiddleware (outermost) intercepts the call
   • It produces a handoff, replaces messages with a clean slate
   • The clean slate then passes through deepagents' internal summarization (which will be a no-op since the context is small)
   • This is the correct behavior -- reset produces a small context that doesn't need further summarization.

3. Race condition with user messages: The spec mentions queuing incoming messages during reset. Since the middleware is outermost, it can intercept all incoming requests during the reset window and buffer them. If it were deeper in the stack, earlier middleware might process the message before the reset handler can catch it.

Potential Conflicts

• With compaction_middleware: If both are set to "auto" mode, you need clear precedence. The recommendation above gives reset priority (it runs first). If reset doesn't trigger, compaction gets its chance. They should never both run on the same turn.
• With cost tracking (feat: Per-run cost tracking, phase-level metering, and budget caps #905): Context reset triggers an extra LLM call to generate the handoff artifact. This call should be metered by cost tracking. Since cost tracking is deeper in the stack (inner), it will naturally capture the handoff LLM call. No conflict.
• With agent observability (feat: Agent phase observability — structured traces with frontend timeline #904): The reset should be a traceable phase (handoff). If tracing middleware wraps the entire call, it will capture the reset as part of the trace. The handoff LLM call should be a child span. No ordering conflict as long as tracing is outermost (see feat: Agent phase observability — structured traces with frontend timeline #904 comment).

Per-Assistant Configuration

The context_strategy field on the Assistant schema means the middleware needs access to runtime context to read the assistant's configuration. This is available via request.runtime.context in a wrap_model_call handler, or via the runtime parameter in before_model/after_model hooks. Use wrap_model_call since the middleware needs to conditionally short-circuit the normal model call flow to inject the handoff prompt.

[ryaneggz]

Migration Strategy Note

Schema Changes Required

• context_strategy field (Literal["compact", "reset", "auto"]) added to Assistant Pydantic model.
• HandoffArtifact is a new Pydantic schema for structured handoff data.
• Session boundaries are tracked in thread metadata.

Migration Needs

• None. All data for this feature lives in schemaless stores:
  • context_strategy is a field on Assistant, which is stored in LangGraph Store (JSON document store). Adding an optional field with a default value requires no migration.
  • HandoffArtifact is persisted to StateBackend as /HANDOFF-{session_number}.md files (LangGraph graph state), not a SQL table.
  • Session boundaries are stored as thread metadata (also LangGraph Store).

Parallel Development Safety

• No Alembic files touched, so zero migration conflict risk.
• Will have a merge conflict in backend/src/schemas/entities/llm.py with feat: Planner Agent — auto-expand short prompts into full product specs #898 (planner) and feat: Evaluator Agent — GAN-inspired generator/evaluator feedback loop #899 (evaluator), since all three add optional fields to Assistant. Resolution is trivial -- all are additive optional fields that don't interfere with each other.

Integration Note

• The spec mentions that planner plans and evaluator configs should persist through context resets. This means this feature should be aware of the planner and evaluator fields on Assistant (from feat: Planner Agent — auto-expand short prompts into full product specs #898 and feat: Evaluator Agent — GAN-inspired generator/evaluator feedback loop #899), but does not depend on them being merged first. If they aren't present, context reset simply has nothing to carry forward for those phases.
• No shared database tables or columns with any other spec.

Recommendation

• Implement HandoffArtifact in backend/src/schemas/entities/handoff.py.
• Add context_strategy: Literal["compact", "reset", "auto"] = "auto" to Assistant in llm.py.
• No migration file needed. This can land independently of all other specs.

[ryaneggz]

SSE Streaming Design — Context Reset Boundaries

Context

When ContextResetMiddleware triggers a context reset, the current session ends and a new session begins with a structured HandoffArtifact. The frontend needs to display visual session dividers and expandable handoff summaries in real-time as the reset happens.

Recommended Approach

Use "custom" stream mode with "context_reset" sub-type. Same extension mechanism as cost (#905), evaluation (#899), and planning (#898).

Backend — emit context reset events:

# Step 1: Context utilization threshold reached, reset starting
stream_writer(("custom", {
    "type": "context_reset",
    "data": {
        "event": "reset_starting",
        "session_id": "session-uuid-old",
        "context_utilization": 0.82,
        "threshold": 0.80,
    }
}))

# Step 2: Handoff artifact generated, new session beginning
stream_writer(("custom", {
    "type": "context_reset",
    "data": {
        "event": "reset_complete",
        "old_session_id": "session-uuid-old",
        "new_session_id": "session-uuid-new",
        "handoff": {
            "completed_tasks": ["Set up project structure", "Implemented auth"],
            "in_progress_tasks": ["Building dashboard"],
            "remaining_tasks": ["Testing", "Deployment"],
            "key_decisions": ["Using React + Tailwind", "PostgreSQL for storage"],
            "files_modified": ["/src/auth.ts", "/src/routes.ts"],
            "state_summary": "Core infrastructure complete, moving to feature work."
        }
    }
}))

Frontend consumption:

1. Handle custom events where payload.type === "context_reset" in useChat.ts
2. On event: "reset_starting":
   • Insert a visual divider marker into the messages array (a synthetic message with type: "session_divider")
   • Show a brief "Resetting context..." loading state
3. On event: "reset_complete":
   • Update the divider marker with the handoff artifact data
   • SessionDivider.tsx renders: horizontal rule with "Session N -> Session N+1", expandable HandoffSummary.tsx showing completed/remaining tasks
4. Subsequent "messages" mode events continue as normal — they belong to the new session

Message queuing during reset:

Per the issue's risk section, incoming user messages during reset should be queued. This is a backend concern — the middleware should buffer incoming messages and deliver them to the new session. The SSE stream can emit a custom event to tell the frontend that input is temporarily blocked:

stream_writer(("custom", {
    "type": "context_reset",
    "data": {"event": "input_blocked", "reason": "Context reset in progress"}
}))

The frontend disables the input textarea until reset_complete arrives.

Session navigator: The frontend can build a session index from accumulated reset_complete events, enabling a sidebar navigator for long threads with multiple sessions.

Distributed mode: Works automatically via existing Redis stream passthrough.

[ryaneggz]

Dependency Graph Validation

Position in Dependency Graph

Sprint Contracts (#906) — DEPENDENT (Layer 1)
  └─ HARD dep on: Evaluator (#899) — negotiation + grading
  └─ SOFT dep on: Planner (#898) — generates specs that contracts break down
  └─ depended upon by: Harness Templates (#910) — "Full Harness" template uses contracts

Declared Dependencies

• "Requires evaluator-agent (hard dependency for negotiation and grading)"
• "Best used with planner-agent (soft dependency for generating high-level specs)"

Validated Dependencies

Correct and well-documented. The spec accurately distinguishes hard vs soft dependencies.

The hard dependency is real: the contract negotiation flow requires a configured EvaluatorConfig on the assistant. The evaluator reviews proposed contracts and grades against agreed criteria. Without the evaluator, Sprint Contracts has no grading mechanism.

Implicit Dependencies Found

1. StateBackend / file-based communication — The spec uses file-based communication for contracts:

   /contracts/sprint-1.md
   /contracts/sprint-2.md
   /contracts/sprint-1-evaluation.md
   

   This references the same "StateBackend" concept as Planner (feat: Planner Agent — auto-expand short prompts into full product specs #898) with /PLAN.md. Neither spec defines what "StateBackend" actually maps to in the codebase. Looking at the existing code, the closest thing is assistant.files (a Dict[str, str] on Assistant), thread checkpoint state, or the storage service at backend/src/services/storage.py. All three specs using "StateBackend" need to agree on the actual implementation.

2. LLMController orchestration ordering — Sprint Contracts adds a negotiation phase between planning and generation. The full pipeline becomes: planner → contract proposal → evaluator review → negotiation → generator → evaluator grading. This is the most complex modification to LLMController across all specs, and it depends on both Planner and Evaluator already being integrated into the controller. Sprint Contracts should be built LAST among controller-modifying specs.

3. Context Reset (feat: Agent phase observability — structured traces with frontend timeline #904) interaction — For long-running sessions with multiple sprints, context resets may occur mid-sprint. The spec mentions "Sprint contract state persists through resets" but Sprint Contracts (feat: Context reset with structured handoff artifacts for long-running sessions #906) doesn't address this directly. Context Reset (feat: Agent phase observability — structured traces with frontend timeline #904) mentions "sprint contract state... persists through resets" — but the actual persistence mechanism is undefined. What happens when a context reset triggers mid-sprint-negotiation? Is the contract re-loaded from /contracts/sprint-N.md? Does the evaluator re-read it? This cross-cutting concern needs explicit design.

Interface Contracts Needed

1. SprintContract → EvaluatorConfig integration — The spec assumes the evaluator can grade against TestCriterion entries from the sprint contract. But EvaluatorConfig.criteria uses EvaluationCriterion (different schema). How does the evaluator switch from its configured EvaluationCriterion list to the sprint's TestCriterion list? Options:

   • TestCriterion extends EvaluationCriterion
   • Evaluator accepts criteria as runtime input (overriding config)
   • TestCriterion is converted to EvaluationCriterion before grading

   This interface is undefined and must be resolved.

2. File path conventions — All three specs using file-based state need a shared path convention:

   Spec	Path	Purpose
   Planner (feat: Planner Agent — auto-expand short prompts into full product specs #898)	/PLAN.md	Product specification
   Sprint Contracts (feat: Context reset with structured handoff artifacts for long-running sessions #906)	/contracts/sprint-N.md	Sprint scope + criteria
   Sprint Contracts (feat: Context reset with structured handoff artifacts for long-running sessions #906)	/contracts/sprint-N-evaluation.md	Grading results
   Context Reset (feat: Agent phase observability — structured traces with frontend timeline #904)	/HANDOFF-{session}.md	Handoff artifacts

3. Sprint lifecycle events — Observability (feat: Agent phase observability — structured traces with frontend timeline #904) needs to know about sprint boundaries for tracing. Should Sprint Contracts emit events that Observability can observe?

Schema Conflict Risk

• Medium. No direct schema conflicts, but the TestCriterion vs EvaluationCriterion type mismatch needs resolution.

Critical Path Assessment

Not on critical path for v0.9.0. Correctly placed at v0.10.0 milestone. Depends on Evaluator (#899) which is v0.9.0. Can only be built after Evaluator is merged. Recommended: Wave 2 or Wave 3.

[ryaneggz]

Testing Strategy Recommendations

Infrastructure Context

Context reset extends the existing middleware stack (tested in test_middleware_integration.py). The SummarizationMiddleware tests in test_compacting.py provide the exact pattern to follow — token estimation, threshold checks, message splitting, and mocked LLM calls for summary generation. The AutoEvictMiddleware coexistence test pattern shows how to verify middleware ordering.

Recommended Tests

Unit Tests (tests/unit/schemas/test_handoff.py)

• HandoffArtifact Pydantic validation: all required fields, completed_work is list[str], optional fields nullable
• HandoffArtifact from structured markdown parsing: verify round-trip (schema → markdown → schema)
• context_strategy field on Assistant: accepts "compact", "reset", "auto", rejects other values

Unit Tests (tests/unit/utils/test_context_reset.py) — CRITICAL

Threshold detection:

• ContextResetMiddleware triggers at configurable threshold (default 80%) — mock token estimator to return known utilization
• Below threshold: middleware is a no-op (passes through to handler unchanged)
• At exactly threshold: triggers reset (boundary condition)
• Verify token estimation uses model-specific context window sizes (128k for gpt-4o, 200k for Claude, etc.)

Auto strategy (model-aware):

• auto selects compact for Opus-class models (e.g., anthropic:claude-opus-4-20250514)
• auto selects reset for Sonnet-class models (e.g., anthropic:claude-sonnet-4-20250514)
• auto selects compact for unknown models (safe default)
• Test with model name variations (with/without provider prefix)

Handoff generation:

• When reset triggers, middleware injects handoff instruction to agent and parses the structured response
• Verify handoff artifact includes all required fields (completed_work, remaining_tasks, etc.)
• Test with malformed agent response — middleware should handle gracefully (extract what it can, log warning)

New session spawn:

• After handoff, verify new agent receives: system prompt + handoff artifact + relevant files ONLY (not full history)
• Session counter increments (session 1 → session 2)
• Session boundary metadata is persisted on thread

How to test handoff continuity without expensive LLM calls:

@patch("src.utils.context_reset.init_chat_model")
async def test_handoff_continuity(mock_init):
    # Mock the agent producing a handoff artifact
    mock_llm = AsyncMock()
    mock_llm.ainvoke.return_value = AIMessage(content='''
    ## Completed Work
    - Built user authentication
    - Created database schema
    ## In Progress
    - Building API endpoints for /users
    ## Remaining Tasks
    - Frontend components
    - Tests
    ## Key Decisions
    - Using JWT for auth tokens
    ## Files Modified
    - backend/src/routes/auth.py
    ## State Summary
    Auth system is functional, API layer is 50% complete.
    ''')
    mock_init.return_value = mock_llm
    # ... verify handoff parsed correctly, new session gets correct context

Middleware Stack Tests (tests/unit/utils/test_middleware_integration.py — extend existing)

• ContextResetMiddleware is registered in correct position in middleware stack
• Both CompactingMiddleware and ContextResetMiddleware coexist
• context_strategy="compact" skips ContextResetMiddleware, only uses compaction
• context_strategy="reset" skips CompactingMiddleware, only uses reset
• Middleware stack length is correct with new middleware added

Integration Tests (tests/integration/test_context_reset.py)

• Multi-turn conversation that exceeds threshold → verify reset occurs and next response includes handoff context
• Plan file (/PLAN.md) persists through resets — verify it is included in new session's context
• Message sent during reset is queued and delivered to new session (race condition test)

Frontend Tests

• SessionDivider.tsx: renders "Session 2 started" divider with correct session number
• HandoffSummary.tsx: renders expandable summary, shows completed/remaining tasks
• Session navigator: renders clickable session list for threads with multiple resets

Gaps in Spec's Test Section

• Missing: Test for evaluator config carrying across resets (spec mentions it but no test specified)
• Missing: Test for sprint contract state persisting through resets
• Missing: Performance test — reset + handoff overhead should be measured (could be expensive with long context)
• Missing: Test for multiple consecutive resets (session 1→2→3) — verify all handoff artifacts are chained correctly
• Missing: Test for user-initiated reset (not just automatic threshold-based)
• Missing: Test that recent messages from the OLD session are NOT carried into the new session (clean slate guarantee)

Shared Fixtures Needed

• mock_handoff_artifact: pre-built HandoffArtifact with realistic data
• high_utilization_messages: factory creating message lists that exceed token thresholds for various models
• context_reset_assistant: Assistant fixture with context_strategy="reset" configured