Research: Sanitize Loop Canonicalization Bottleneck

Research: Sanitize Loop Canonicalization Bottleneck

Date: 2026-02-02 Phase: Research Branch: bottlenecks

Problem Statement

run_cleanup_loop() performs 4N message conversions per iteration (up to 10 iterations), resulting in worst-case 40N conversions for N messages.

Structure

File Layout

src/tunacode/
├── core/agents/resume/sanitize.py     # Cleanup loop orchestrator
├── utils/messaging/adapter.py          # Message conversion + tool call extraction
└── types/canonical.py                   # CanonicalMessage definition

Entry Point

• sanitize.py:458-502 - run_cleanup_loop(messages, tool_registry)
• Called from: main.py:291

Key Files

sanitize.py - Cleanup Loop

adapter.py - Conversion Functions

Patterns Found

Pattern 1: Double Conversion in find_dangling_tool_calls

Location: adapter.py:309-318

def find_dangling_tool_calls(messages: list[Any]) -> set[str]:
    call_ids: set[str] = set()
    return_ids: set[str] = set()

    for msg in messages:                         # N iterations
        call_ids.update(get_tool_call_ids(msg))   # → to_canonical(msg)  [conversion 1]
        return_ids.update(get_tool_return_ids(msg))  # → to_canonical(msg)  [conversion 2]

    return call_ids - return_ids

Observation: Same message converted twice per loop iteration. The canonical result from get_tool_call_ids() is discarded before get_tool_return_ids() re-converts the same message.

Pattern 2: Conversion-for-Inspection in remove_empty_responses

Location: sanitize.py:326-355

def remove_empty_responses(messages: list[Any]) -> bool:
    canonical_messages = _canonicalize_messages(messages)  # Line 332: N conversions
    # ... inspection logic ...
    del messages[index]  # Line 351: mutates ORIGINAL list, not canonical

Observation: Canonical messages used only for read-only inspection. Mutations happen on original pydantic-ai list.

Pattern 3: Identical Conversion-for-Inspection in remove_consecutive_requests

Location: sanitize.py:358-404

def remove_consecutive_requests(messages: list[Any]) -> bool:
    canonical_messages = _canonicalize_messages(messages)  # Line 364: N conversions
    # ... inspection logic ...
    del messages[index]  # Line 400: mutates ORIGINAL list

Observation: Same pattern as Pattern 2. Independent conversion with no shared cache.

Pattern 4: No Caching Between Functions

Location: sanitize.py:469-491

for cleanup_iteration in range(MAX_CLEANUP_ITERATIONS):
    dangling_tool_call_ids = find_dangling_tool_call_ids(messages)  # 2N conversions
    # ...
    removed_empty_responses = remove_empty_responses(messages)       # N conversions
    # ...
    removed_consecutive_requests = remove_consecutive_requests(messages)  # N conversions

Observation: Three functions called sequentially, each converts the entire message list independently. No shared canonical cache within an iteration.

Dependencies

Conversion Call Chain

run_cleanup_loop (sanitize.py:458)
├── find_dangling_tool_call_ids (sanitize.py:248)
│   └── find_dangling_tool_calls (adapter.py:309)
│       ├── get_tool_call_ids (adapter.py:295)
│       │   └── to_canonical (adapter.py:146)  # 1 per msg
│       └── get_tool_return_ids (adapter.py:302)
│           └── to_canonical (adapter.py:146)  # 1 per msg (DUPLICATE)
├── remove_empty_responses (sanitize.py:326)
│   └── _canonicalize_messages (sanitize.py:61)
│       └── to_canonical_list (adapter.py:205)  # N conversions
└── remove_consecutive_requests (sanitize.py:358)
    └── _canonicalize_messages (sanitize.py:61)
        └── to_canonical_list (adapter.py:205)  # N conversions

Import Dependencies

sanitize.py imports from adapter.py:
├── find_dangling_tool_calls
└── to_canonical_list (via _canonicalize_messages)

sanitize.py imports from canonical.py:
├── CanonicalMessage
├── MessageRole
└── SystemPromptPart

Conversion Count Summary

Per Iteration (N messages)

Total Conversions

Symbol Index

sanitize.py Exports

• sanitize_history_for_resume() - Main entry point (line 412)
• run_cleanup_loop() - Loop orchestrator (line 458)
• find_dangling_tool_call_ids() - ID extraction (line 248)
• remove_dangling_tool_calls() - Removal (line 253)
• remove_empty_responses() - Cleanup (line 326)
• remove_consecutive_requests() - Cleanup (line 358)

adapter.py Exports (relevant)

• to_canonical() - Single message conversion (line 146)
• to_canonical_list() - Batch conversion (line 205)
• get_tool_call_ids() - ID extraction (line 295)
• get_tool_return_ids() - ID extraction (line 302)
• find_dangling_tool_calls() - Detection (line 309)

Bottleneck Root Causes

1. Double conversion in find_dangling_tool_calls: Same message converted twice to extract call_ids then return_ids

2. Independent conversions per function: Each cleanup function (find_dangling, remove_empty, remove_consecutive) converts the full list independently

3. No per-iteration cache: Canonical messages created and discarded by each function; no shared cache within an iteration

4. Read-only conversions on mutable data: Conversions used only for inspection while mutations happen on original pydantic-ai list

Fix Locations

After fixes: 1N conversions per iteration (down from 4N) = 75% reduction