fix: consolidated protocol robustness improvements

[echobt]

Summary

This PR consolidates 2 protocol robustness improvements.

Included PRs:

• fix(streaming): add buffer size limit to StreamProcessor #84: Add buffer size limit to StreamProcessor
• fix(protocol): add ToolState transition validation #85: Add ToolState transition validation

Key Changes:

• Added MAX_BUFFER_SIZE constant (10,000 events) for StreamProcessor
• Modified process() to drop oldest events when buffer is full
• Pre-allocated buffer capacity in new() for better performance
• Added can_transition_to() method to ToolState enum
• Updated update_tool_state to log warnings on invalid transitions
• Documented valid state machine transitions

State Machine

Pending -> Running -> Completed
    |         |
    |         +-> Error
    +-> Completed
    +-> Error

Files Modified:

• src/cortex-engine/src/streaming.rs
• src/cortex-protocol/src/protocol/message_parts.rs
• Cargo.lock
• src/cortex-protocol/Cargo.toml

Closes #84, #85

[greptile-apps]

Greptile Overview

Greptile Summary

This PR consolidates two protocol robustness improvements by adding buffer management and state transition validation.

Key Changes

StreamProcessor Buffer Management (src/cortex-engine/src/streaming.rs):

• Added MAX_BUFFER_SIZE constant (10,000 events) to prevent unbounded memory growth
• When buffer reaches capacity, oldest event is dropped via pop_front()
• Pre-allocated buffer capacity of 1,024 events for performance optimization

ToolState Transition Validation (src/cortex-protocol/src/protocol/message_parts.rs):

• Implemented can_transition_to() method with documented state machine transitions
• Added validation in update_tool_state() to log warnings on invalid transitions
• State machine: Pending → Running/Completed/Error, Running → Completed/Error (terminal states cannot transition)
• Added tracing dependency to cortex-protocol for logging

Notes

The ToolState validation is currently non-blocking - invalid transitions are logged but still applied. This maintains backward compatibility but may allow unintended state changes from terminal states.

Confidence Score: 4/5

• This PR is safe to merge with low risk - implements defensive programming patterns
• The changes add robustness protections (buffer limits and state validation) without breaking existing functionality. The buffer size limit properly prevents memory exhaustion, and the state validation provides helpful logging. Minor consideration: state transitions log but don't block invalid changes, which is intentional for backward compatibility.
• No files require special attention - changes are straightforward defensive improvements

Important Files Changed

Filename	Overview
src/cortex-engine/src/streaming.rs	Added MAX_BUFFER_SIZE limit (10,000 events) with pop_front() when buffer is full, pre-allocated capacity of 1,024
src/cortex-protocol/src/protocol/message_parts.rs	Added can_transition_to() method with state machine validation and warning logs for invalid transitions

Sequence Diagram

sequenceDiagram
    participant Client
    participant MessageWithParts
    participant ToolState
    
    Note over ToolState: Initial State: Pending
    
    Client->>MessageWithParts: update_tool_state(call_id, Running)
    MessageWithParts->>ToolState: can_transition_to(Running)?
    ToolState-->>MessageWithParts: true (Pending → Running valid)
    MessageWithParts->>ToolState: Update state to Running
    MessageWithParts-->>Client: true
    
    Note over ToolState: Current State: Running
    
    Client->>MessageWithParts: update_tool_state(call_id, Completed)
    MessageWithParts->>ToolState: can_transition_to(Completed)?
    ToolState-->>MessageWithParts: true (Running → Completed valid)
    MessageWithParts->>ToolState: Update state to Completed
    MessageWithParts-->>Client: true
    
    Note over ToolState: Current State: Completed (Terminal)
    
    Client->>MessageWithParts: update_tool_state(call_id, Running)
    MessageWithParts->>ToolState: can_transition_to(Running)?
    ToolState-->>MessageWithParts: false (Completed is terminal)
    MessageWithParts->>MessageWithParts: Log warning
    MessageWithParts->>ToolState: Update state anyway
    MessageWithParts-->>Client: true
    
    Note over MessageWithParts,ToolState: Invalid transition logged but state still updated

Loading

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

The state transition validation logs a warning but still updates the state. This means invalid transitions (e.g., from terminal states) are allowed at runtime. Consider whether invalid transitions should be rejected instead of just logged.

Suggested change

	if !state.can_transition_to(&new_state) {
	tracing::warn!(
	"Invalid ToolState transition from {:?} to {:?} for call_id {}",
	state,
	new_state,
	call_id
	);
	}
	*state = new_state;
	if cid == call_id {
	if !state.can_transition_to(&new_state) {
	tracing::warn!(
	"Invalid ToolState transition from {:?} to {:?} for call_id {}",
	state,
	new_state,
	call_id
	);
	return false;
	}
	*state = new_state;
	return true;
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/cortex-protocol/src/protocol/message_parts.rs
Line: 605:613

Comment:
The state transition validation logs a warning but still updates the state. This means invalid transitions (e.g., from terminal states) are allowed at runtime. Consider whether invalid transitions should be rejected instead of just logged.

```suggestion
                if cid == call_id {
                    if !state.can_transition_to(&new_state) {
                        tracing::warn!(
                            "Invalid ToolState transition from {:?} to {:?} for call_id {}",
                            state,
                            new_state,
                            call_id
                        );
                        return false;
                    }
                    *state = new_state;
                    return true;
                }
```

How can I resolve this? If you propose a fix, please make it concise.

[echobt]

Closing this PR to consolidate into a single mega-PR combining all bug fixes. The changes will be included in a new consolidated PR.