[Bug] Long Conversation Triggers "tool message without toolcalls" Error

[Clawiee]

🐛 Bug: Long Conversation Triggers "tool message without toolcalls" Error

Description

When a conversation exceeds a certain length threshold, it triggers an LLM API error:

Messages with role 'tool' must be a response to a preceding message with 'toolcalls'

Starting a new conversation fixes the issue, confirming it's related to message history length.

Steps to Reproduce

1. Have a conversation with multiple tool/function calls
2. Continue the conversation past a certain message count or token threshold
3. Attempt another tool call
4. Error: invalidrequesterror - tool message without preceding toolcalls

Root Cause Analysis

The issue is likely caused by message history truncation in one of these scenarios:

Scenario 1: Truncation cuts at tool_calls boundary

[正常历史]
Assistant: has tool_calls: [search]
User (tool): "search results..."
Assistant: has tool_calls: [write_file]
User (tool): "file written..."

[截断后]
User (tool): "file written..."  ← 没有前面的 tool_calls，API 报错！

Scenario 2: Inconsistent message pairing
The message history has a role: 'tool' message that doesn't correspond to any preceding tool_calls message, possibly due to:

• Incomplete truncation logic
• Race condition in message processing
• Message deduplication removing the tool_calls parent

Suggested Fix

Option 1: Smarter Truncation

# Before truncating, ensure we don't cut in the middle of a tool/tool_calls pair
def truncate_history(messages, max_tokens):
    # Find safe truncation points (before tool_calls messages)
    safe_points = [i for i, m in enumerate(messages) 
                   if m.get('role') == 'assistant' and 'tool_calls' in m]
    # Truncate before the oldest safe point that leaves room
    ...

Option 2: Validate Message Chain Before API Call

def validate_message_chain(messages):
    tool_calls_seen = set()
    for msg in messages:
        if msg.get('role') == 'tool':
            # Check if this tool message has a valid parent
            if msg.get('tool_call_id') not in tool_calls_seen:
                raise ValueError("Tool message without preceding tool_calls")
        if 'tool_calls' in msg:
            for tc in msg['tool_calls']:
                tool_calls_seen.add(tc.get('id'))

Option 3: Automatic Repair

def repair_message_history(messages):
    # Remove orphan tool messages
    valid_tool_ids = set()
    for msg in messages:
        if 'tool_calls' in msg:
            for tc in msg['tool_calls']:
                valid_tool_ids.add(tc.get('id'))
    
    return [m for m in messages 
            if m.get('role') != 'tool' or m.get('tool_call_id') in valid_tool_ids]

Affected Components

• LLM caller / message history management
• Conversation truncation logic

Labels

• bug
• llm
• conversation-management

Priority

High - This blocks users from having longer conversations

[Clawiee]

🔍 Technical Analysis

Thank you for the detailed bug report! I've analyzed the codebase and confirmed this is a valid issue.

Root Cause Identified

The problem is in backend/app/api/websocket.py:

# Line ~320: Simple truncation without considering tool/tool_calls pairing
conversation.append({"role": "user", "content": content})
# ...
conversation[-ctx_size:]  # ← Problem: cuts at arbitrary boundaries

When the conversation exceeds context_window_size messages, the system uses simple slicing conversation[-ctx_size:]. This can cut between an assistant message with tool_calls and its corresponding tool response message.

Scenarios Where This Breaks

Scenario 1: Truncation in the middle of a tool round

Assistant: has tool_calls: [search_tool]  ← CAN BE TRUNCATED
User (tool): "search results..."          ← Orphaned! No parent tool_calls

Scenario 2: Tool result truncation

# websocket.py line ~280: Tool results are truncated to 500 chars
"content": sanitized_result[:500],  # May truncate mid-message

Suggested Fixes

Option 1: Smart Truncation (Recommended)

def truncate_safely(messages: list, max_count: int) -> list:
    """Truncate ensuring tool/tool_calls pairs stay together."""
    if len(messages) <= max_count:
        return messages
    
    # Find truncation points (after tool response, before assistant with tool_calls)
    safe_idx = len(messages) - max_count
    for i in range(safe_idx, len(messages)):
        msg = messages[i]
        if msg.get("role") == "tool":
            # Don't cut here - find an earlier point
            continue
        if msg.get("role") == "assistant" and msg.get("tool_calls"):
            # This is a tool_calls msg - truncate AFTER this if possible
            if i + 1 < len(messages) and messages[i + 1].get("role") == "tool":
                return messages[i + 1:]  # Start after the tool response
    return messages[-max_count:]

Option 2: Pre-flight Validation
Before sending to LLM, validate the message chain:

def validate_message_chain(messages: list) -> list:
    """Remove orphan tool messages that lack parent tool_calls."""
    seen_tool_call_ids = set()
    valid_messages = []
    for msg in messages:
        if msg.get("role") == "assistant" and msg.get("tool_calls"):
            for tc in msg["tool_calls"]:
                seen_tool_call_ids.add(tc.get("id"))
            valid_messages.append(msg)
        elif msg.get("role") == "tool":
            if msg.get("tool_call_id") in seen_tool_call_ids:
                valid_messages.append(msg)
            # else: orphan tool message - skip
        else:
            valid_messages.append(msg)
    return valid_messages

Priority Assessment

High - This completely blocks users from having extended conversations with tool-calling agents.

---

This issue should be tracked separately from general conversation management as it specifically affects the tool-calling message protocol.

[yaojin3616]

Fixed in commit 4921623 (PR #416): Prevent tool call message pairs (assistant + tool) from being broken down.

Root cause: When conversation history was truncated, the truncation logic could split an assistant message containing tool_calls from its corresponding tool result message, leaving orphaned tool result messages that caused the LLM API to reject the request.

Fix: The truncation logic now treats assistant+tool message pairs as atomic units and never splits them.