2875 2026 02 12 Issue 382 Manual Compact Boundary Map 37d619fa

Research – Issue #382 Manual /compact Boundary Flow

Date: 2026-02-12 Phase: Research

Structure

• src/tunacode/ui/commands/
  • compact.py — manual /compact command implementation (src/tunacode/ui/commands/compact.py:1)
  • __init__.py — command registry includes "compact": CompactCommand() (src/tunacode/ui/commands/__init__.py:514)
• src/tunacode/core/compaction/
  • controller.py — compaction orchestration and outcome notices (src/tunacode/core/compaction/controller.py:88)
  • summarizer.py — retention boundary and transcript serialization (src/tunacode/core/compaction/summarizer.py:37)
  • types.py — compaction statuses, reasons, and dataclasses (src/tunacode/core/compaction/types.py:18)
  • prompts.py — summary prompt templates (src/tunacode/core/compaction/prompts.py:1)
• src/tunacode/core/agents/
  • main.py — request-time auto compaction and overflow retry force compaction (src/tunacode/core/agents/main.py:358, src/tunacode/core/agents/main.py:378)
  • agent_components/agent_config.py — tinyagent transform_context compaction path (src/tunacode/core/agents/agent_components/agent_config.py:288)
• src/tunacode/core/session/
  • state.py — session stores compaction record and _compaction_controller cache (src/tunacode/core/session/state.py:41, src/tunacode/core/session/state.py:61)
• tests/
  • tests/unit/core/test_compaction_controller_outcomes.py — force_compact outcome contracts (tests/unit/core/test_compaction_controller_outcomes.py:79)
  • tests/unit/core/test_compaction_summarizer.py — retention boundary policy tests (tests/unit/core/test_compaction_summarizer.py:75)
  • tests/test_compaction.py — integration flow test (tests/test_compaction.py:89)

Key Files

• src/tunacode/ui/commands/compact.py:28 → CompactCommand

• src/tunacode/ui/commands/compact.py:35 → CompactCommand.execute

• src/tunacode/ui/commands/compact.py:58 → manual path calls controller.force_compact(...)

• src/tunacode/ui/commands/compact.py:24 → COMPACT_SKIPPED_NOTICE = "Compaction skipped (no eligible boundary)."

• src/tunacode/ui/commands/compact.py:73 → calls build_compaction_notice(compaction_outcome)

• src/tunacode/ui/commands/compact.py:75 → emits COMPACT_SKIPPED_NOTICE when notice builder returns None

• src/tunacode/core/compaction/controller.py:148 → check_and_compact(...)

• src/tunacode/core/compaction/controller.py:175 → force_compact(...)

• src/tunacode/core/compaction/controller.py:184 → force_compact delegates to check_and_compact(..., force=True, allow_threshold=True)

• src/tunacode/core/compaction/controller.py:209 → _compact(...)

• src/tunacode/core/compaction/controller.py:216 → computes boundary = self._summarizer.calculate_retention_boundary(...)

• src/tunacode/core/compaction/controller.py:219 → logs skip with reason COMPACTION_REASON_NO_VALID_BOUNDARY

• src/tunacode/core/compaction/controller.py:220 → returns skip outcome for no_valid_boundary

• src/tunacode/core/compaction/controller.py:468 → build_compaction_notice(...)

• src/tunacode/core/compaction/summarizer.py:43 → calculate_retention_boundary(...)

• src/tunacode/core/compaction/summarizer.py:145 → _find_threshold_index(...)

• src/tunacode/core/compaction/summarizer.py:169 → _snap_to_valid_boundary(...)

• src/tunacode/core/compaction/summarizer.py:175 → _is_valid_boundary(...)

• src/tunacode/core/compaction/summarizer.py:217 → assistant boundary validity depends on stop_reason is not None

• src/tunacode/core/compaction/summarizer.py:221 → tool-result message role check

• src/tunacode/core/compaction/types.py:27 → COMPACTION_REASON_NO_VALID_BOUNDARY

• src/tunacode/core/compaction/types.py:68 → CompactionOutcome

• src/tunacode/core/compaction/types.py:84 → CompactionRecord

• src/tunacode/core/agents/main.py:358 → _compact_history_for_request(...) calls check_and_compact(...)

• src/tunacode/core/agents/main.py:364 → auto path callsite

• src/tunacode/core/agents/main.py:378 → _force_compact_history(...)

• src/tunacode/core/agents/main.py:383 → force path callsite

• src/tunacode/core/agents/main.py:352 → compaction notice creation via build_compaction_notice(...)

• src/tunacode/core/agents/agent_components/agent_config.py:288 → _build_transform_context(...)

• src/tunacode/core/agents/agent_components/agent_config.py:297 → check_and_compact(...) call in transform_context

• src/tunacode/core/agents/agent_components/agent_config.py:301 → allow_threshold=False

• src/tunacode/core/agents/agent_components/agent_config.py:303 → inject_summary_message(...)

• tests/unit/core/test_compaction_controller_outcomes.py:79 → test_force_compact_empty_history_returns_no_boundary_skip

• tests/unit/core/test_compaction_controller_outcomes.py:93 → expects COMPACTION_REASON_NO_VALID_BOUNDARY

• tests/unit/core/test_compaction_summarizer.py:75 → test_retention_boundary_snaps_to_zero_when_no_valid_boundary_exists

Patterns Found

• Manual command entry pattern

  • src/tunacode/ui/commands/__init__.py:514 ("compact": CompactCommand())
  • src/tunacode/ui/commands/compact.py:35 (execute command handler)

• Manual compaction invocation pattern

  • src/tunacode/ui/commands/compact.py:58 (controller.force_compact(...))
  • src/tunacode/core/compaction/controller.py:175 (force_compact)
  • src/tunacode/core/compaction/controller.py:184 (force_compact delegates to check_and_compact)

• Boundary gate pattern

  • src/tunacode/core/compaction/controller.py:216 (calculate_retention_boundary)
  • src/tunacode/core/compaction/controller.py:219 / :220 (no_valid_boundary skip branch)
  • src/tunacode/core/compaction/summarizer.py:43 (calculate_retention_boundary)
  • src/tunacode/core/compaction/summarizer.py:175 (_is_valid_boundary)

• User-facing skip message propagation pattern

  • src/tunacode/ui/commands/compact.py:73 (build_compaction_notice)
  • src/tunacode/ui/commands/compact.py:75 (fallback COMPACT_SKIPPED_NOTICE)
  • src/tunacode/core/compaction/controller.py:468 (build_compaction_notice implementation)

• Automatic/background compaction path pattern

  • src/tunacode/core/agents/main.py:364 (check_and_compact in request flow)
  • src/tunacode/core/agents/agent_components/agent_config.py:297 (check_and_compact in transform_context)
  • src/tunacode/core/agents/agent_components/agent_config.py:301 (allow_threshold=False)

Dependencies

• src/tunacode/ui/commands/compact.py:9 → imports tunacode.core.compaction.controller

• src/tunacode/ui/commands/compact.py:14 → imports COMPACTION_STATUS_COMPACTED from tunacode.core.compaction.types

• src/tunacode/ui/commands/compact.py:15 → imports estimate_messages_tokens from tunacode.core.ui_api.messaging

• src/tunacode/core/compaction/controller.py:23 → imports ContextSummarizer from tunacode.core.compaction.summarizer

• src/tunacode/core/compaction/controller.py:24 → imports compaction constants and dataclasses from tunacode.core.compaction.types

• src/tunacode/core/compaction/controller.py:10 / :11 → imports tinyagent message/model stream primitives

• src/tunacode/core/compaction/summarizer.py:14 → imports prompt templates from tunacode.core.compaction.prompts

• src/tunacode/core/compaction/summarizer.py:12 → imports token estimation and content helpers from tunacode.utils.messaging

• src/tunacode/core/agents/main.py:35 → imports compaction controller utilities

• src/tunacode/core/agents/main.py:41 → imports CompactionOutcome

• src/tunacode/core/agents/agent_components/agent_config.py:44 → imports get_or_create_compaction_controller

• src/tunacode/core/session/state.py:21 → imports CompactionRecord

• src/tunacode/core/session/state.py:41 → session field compaction: CompactionRecord | None

• src/tunacode/core/session/state.py:61 → session runtime cache _compaction_controller

Symbol Index

• src/tunacode/ui/commands/compact.py:28 → CompactCommand

• src/tunacode/ui/commands/compact.py:35 → CompactCommand.execute(self, app, args)

• src/tunacode/ui/commands/compact.py:92 → _coerce_history(messages)

• src/tunacode/core/compaction/controller.py:88 → CompactionController

• src/tunacode/core/compaction/controller.py:119 → set_status_callback(...)

• src/tunacode/core/compaction/controller.py:124 → reset_request_state(...)

• src/tunacode/core/compaction/controller.py:129 → should_compact(...)

• src/tunacode/core/compaction/controller.py:148 → check_and_compact(...)

• src/tunacode/core/compaction/controller.py:175 → force_compact(...)

• src/tunacode/core/compaction/controller.py:192 → inject_summary_message(...)

• src/tunacode/core/compaction/controller.py:209 → _compact(...)

• src/tunacode/core/compaction/controller.py:442 → get_or_create_compaction_controller(state_manager)

• src/tunacode/core/compaction/controller.py:457 → apply_compaction_messages(state_manager, messages)

• src/tunacode/core/compaction/controller.py:468 → build_compaction_notice(outcome)

• src/tunacode/core/compaction/summarizer.py:37 → ContextSummarizer

• src/tunacode/core/compaction/summarizer.py:43 → calculate_retention_boundary(...)

• src/tunacode/core/compaction/summarizer.py:67 → serialize_messages(...)

• src/tunacode/core/compaction/summarizer.py:95 → summarize(...)

• src/tunacode/core/compaction/summarizer.py:145 → _find_threshold_index(...)

• src/tunacode/core/compaction/summarizer.py:169 → _snap_to_valid_boundary(...)

• src/tunacode/core/compaction/summarizer.py:175 → _is_valid_boundary(...)

• src/tunacode/core/compaction/types.py:47 → __all__

• src/tunacode/core/compaction/types.py:68 → CompactionOutcome

• src/tunacode/core/compaction/types.py:84 → CompactionRecord

Structural Script Availability (Observed)

• scripts/structure-map.sh → command not found in repo (bash exit code 127)
• scripts/ast-scan.sh → command not found in repo (bash exit code 127)
• scripts/symbol-index.sh → command not found in repo (bash exit code 127)