CodeScene: Low cohesion in src/agent/thread_ops.rs (#84)

[coderabbitai]

Title
CodeScene: Low cohesion in src/agent/thread_ops.rs (#84)

Summary
CodeScene reports “Low Cohesion” for:

• File: src/agent/thread_ops.rs
• Finding: At least 18 different responsibilities across 18 functions (threshold = 3).

Why this matters
Low cohesion increases the effort to understand and safely change the file and often correlates with higher change risk and future defects.

Evidence and backlinks

• Pull request Self-repair: enforce stuck threshold and cooperative shutdown #84: Self-repair: enforce stuck threshold and cooperative shutdown #84
• Reported by CodeScene on this PR (Low Cohesion biomarker for src/agent/thread_ops.rs).

Requested outcome (non‑prescriptive)

• Improve the cohesion of src/agent/thread_ops.rs so subsequent CodeScene analyses no longer flag this file for Low Cohesion (meeting or beating the current threshold), while preserving existing behaviour and public APIs.

Acceptance criteria

• CodeScene no longer reports “Low Cohesion” for src/agent/thread_ops.rs after the remediation lands.
• Unit/integration tests pass.
• No user‑visible behaviour changes.

Requester
@leynos

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Extract the root file's 18 functions into 4 new/expanded submodules organised by responsibility: control commands (8 functions), persistence (3 functions), turn execution (1 function), and hydration (2 functions)
• Retain only the message-handling orchestration (4 functions) in the root file, bringing its responsibility count below CodeScene's threshold of 3
• Preserve the existing impl Agent method pattern and pub(super) visibility already established by sibling submodules
• No behavioural changes—this is a pure structural refactoring

Implementation Steps

Phase 1: Extract Thread Control Commands

Move the eight thread control command handlers into a dedicated submodule, grouping them by their shared responsibility of managing thread lifecycle state transitions.

Create thread control submodule

Extract all thread control command handlers into a new cohesive submodule focused on thread state management operations.

• Create src/agent/thread_ops/control.rs containing an impl Agent block
• Move process_undo, process_redo, process_interrupt, process_compact, process_clear, process_new_thread, process_switch_thread, and process_resume from the root file
• Maintain pub(super) visibility on all methods to preserve internal API surface
• Add necessary imports for Session, ThreadState, UndoManager, ContextCompactor, and channel types
• Declare the submodule in the root file with mod control;

🤖 Prompt for AI agents

Create a new submodule `src/agent/thread_ops/control.rs` to house all eight
thread control command handlers. The goal is to group thread lifecycle state
transition logic into a single, cohesive file.

- Create `src/agent/thread_ops/control.rs` with an `impl Agent` block
- Move the following methods from `src/agent/thread_ops.rs` into the new file:
`process_undo`, `process_redo`, `process_interrupt`, `process_compact`,
`process_clear`, `process_new_thread`, `process_switch_thread`, and
`process_resume`
- Preserve `pub(super)` visibility on all moved methods
- Add the necessary imports to `control.rs` for `Session`, `ThreadState`,
`UndoManager`, `ContextCompactor`, and any channel types used by these methods
- In `src/agent/thread_ops.rs`, remove the moved method bodies and add `mod
control;` to the submodule declarations

Phase 2: Extract Persistence and Turn Execution

Consolidate database persistence operations and extract the turn execution logic into dedicated submodules. These are grouped together because process_user_input directly depends on all three persistence methods.

Task 1: Expand persistence submodule

Move the three persist_* methods into the existing persistence.rs submodule, which currently contains only the gateway_conversation_params helper.

• Move persist_user_message, persist_assistant_response, and persist_tool_calls to src/agent/thread_ops/persistence.rs
• Add an impl Agent block to contain the methods (the file currently has only a free function)
• Add imports for Arc, serde_json, TurnToolCall, and truncate_preview
• Ensure methods remain callable from turn_execution.rs and approval.rs via the self. receiver

Task 2: Create turn execution submodule

Extract the user turn lifecycle orchestration into its own submodule.

• Create src/agent/thread_ops/turn_execution.rs containing an impl Agent block
• Move process_user_input (~360 lines) from the root file
• Add imports for safety validation, command routing, auto-compaction, undo checkpointing, attachment augmentation, and agentic loop components
• The method's calls to self.persist_user_message, self.persist_assistant_response, and self.persist_tool_calls will continue to work via method dispatch on Agent
• Declare the submodule in the root file with mod turn_execution;

🤖 Prompt for AI agents

Expand the existing `src/agent/thread_ops/persistence.rs` and create a new
`src/agent/thread_ops/turn_execution.rs`. The goal is to co-locate DB
persistence logic and isolate the user turn lifecycle orchestration.

**Expand persistence submodule (`src/agent/thread_ops/persistence.rs`):**
- Add an `impl Agent` block to the file (it currently contains only a free
function)
- Move `persist_user_message`, `persist_assistant_response`, and
`persist_tool_calls` from `src/agent/thread_ops.rs` into this block
- Add imports for `Arc`, `serde_json`, `TurnToolCall`, and `truncate_preview` as
required by the moved methods
- Ensure these methods remain accessible via `self.` from `turn_execution.rs`
and `approval.rs`

**Create turn execution submodule (`src/agent/thread_ops/turn_execution.rs`):**
- Create the file with an `impl Agent` block
- Move `process_user_input` (~360 lines) from the root file into this block
- Add all necessary imports: safety validation, command routing,
auto-compaction, undo checkpointing, attachment augmentation, and agentic loop
components
- Calls to `self.persist_user_message`, `self.persist_assistant_response`, and
`self.persist_tool_calls` require no changes—they resolve via method dispatch on
`Agent`
- In `src/agent/thread_ops.rs`, remove the moved method body and add `mod
turn_execution;`

Phase 3: Extract Hydration and Finalise Root File

Complete the extraction by moving thread hydration functions and ensuring the root file retains only its message-handling orchestration responsibility.

Task 1: Create hydration submodule

Extract thread loading and session resolution into a dedicated submodule.

• Create src/agent/thread_ops/hydration.rs containing an impl Agent block
• Move maybe_hydrate_thread and hydrate_and_resolve_session_thread from the root file
• Add imports for SessionManager, Uuid, database store types, and rebuild_chat_messages_from_db
• Declare the submodule in the root file with mod hydration;

Task 2: Clean up root file

Verify the root thread_ops.rs file contains only message-handling orchestration and submodule declarations.

• Confirm the root file retains only: store_extracted_documents (free function, thin wrapper), handle_message (main entry point), check_auth_mode_intercept (private helper), and set_tool_context_for_message (private helper)
• Verify all mod declarations are present: approval, control, dispatch, document_store, hydration, message_rebuild, persistence, turn_execution
• Remove any unused imports from the root file
• Run cargo check and cargo test to verify compilation and test passage

🤖 Prompt for AI agents

Create `src/agent/thread_ops/hydration.rs` and perform a final clean-up pass on
the root `src/agent/thread_ops.rs`. The goal is to complete the structural
refactoring so the root file holds only message-handling orchestration.

**Create hydration submodule (`src/agent/thread_ops/hydration.rs`):**
- Create the file with an `impl Agent` block
- Move `maybe_hydrate_thread` and `hydrate_and_resolve_session_thread` from the
root file
- Add imports for `SessionManager`, `Uuid`, database store types, and
`rebuild_chat_messages_from_db`
- In `src/agent/thread_ops.rs`, remove the moved method bodies and add `mod
hydration;`

**Clean up root file (`src/agent/thread_ops.rs`):**
- Confirm the root file retains exactly these four items:
`store_extracted_documents` (free function, thin wrapper), `handle_message`
(main entry point), `check_auth_mode_intercept` (private helper), and
`set_tool_context_for_message` (private helper)
- Verify all eight `mod` declarations are present: `approval`, `control`,
`dispatch`, `document_store`, `hydration`, `message_rebuild`, `persistence`,
`turn_execution`
- Remove any unused imports
- Run `cargo check` and `cargo test` to confirm compilation succeeds and all
tests pass

Research

The src/agent/thread_ops.rs file is a 1,008-line module serving as the thread operations coordinator for the agent system. It currently bundles five distinct responsibility clusters: message entry/routing, user turn execution, DB persistence, thread control commands, and thread hydration. The module already has a subdirectory structure with extracted submodules (approval.rs, dispatch.rs, document_store.rs, message_rebuild.rs, persistence.rs), establishing a clear pattern for further extraction. The public API surface is narrow—only handle_message and store_extracted_documents are called externally from agent_loop.rs. All other process_* methods are invoked internally via dispatch_submission in dispatch.rs.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a new submodule `src/agent/thread_ops/control.rs` to house all eight
thread control command handlers. The goal is to group thread lifecycle state
transition logic into a single, cohesive file.

- Create `src/agent/thread_ops/control.rs` with an `impl Agent` block
- Move the following methods from `src/agent/thread_ops.rs` into the new file:
`process_undo`, `process_redo`, `process_interrupt`, `process_compact`,
`process_clear`, `process_new_thread`, `process_switch_thread`, and
`process_resume`
- Preserve `pub(super)` visibility on all moved methods
- Add the necessary imports to `control.rs` for `Session`, `ThreadState`,
`UndoManager`, `ContextCompactor`, and any channel types used by these methods
- In `src/agent/thread_ops.rs`, remove the moved method bodies and add `mod
control;` to the submodule declarations
===============================================================================

Task: 2

Expand the existing `src/agent/thread_ops/persistence.rs` and create a new
`src/agent/thread_ops/turn_execution.rs`. The goal is to co-locate DB
persistence logic and isolate the user turn lifecycle orchestration.

**Expand persistence submodule (`src/agent/thread_ops/persistence.rs`):**
- Add an `impl Agent` block to the file (it currently contains only a free
function)
- Move `persist_user_message`, `persist_assistant_response`, and
`persist_tool_calls` from `src/agent/thread_ops.rs` into this block
- Add imports for `Arc`, `serde_json`, `TurnToolCall`, and `truncate_preview` as
required by the moved methods
- Ensure these methods remain accessible via `self.` from `turn_execution.rs`
and `approval.rs`

**Create turn execution submodule (`src/agent/thread_ops/turn_execution.rs`):**
- Create the file with an `impl Agent` block
- Move `process_user_input` (~360 lines) from the root file into this block
- Add all necessary imports: safety validation, command routing,
auto-compaction, undo checkpointing, attachment augmentation, and agentic loop
components
- Calls to `self.persist_user_message`, `self.persist_assistant_response`, and
`self.persist_tool_calls` require no changes—they resolve via method dispatch on
`Agent`
- In `src/agent/thread_ops.rs`, remove the moved method body and add `mod
turn_execution;`
===============================================================================

Task: 3

Create `src/agent/thread_ops/hydration.rs` and perform a final clean-up pass on
the root `src/agent/thread_ops.rs`. The goal is to complete the structural
refactoring so the root file holds only message-handling orchestration.

**Create hydration submodule (`src/agent/thread_ops/hydration.rs`):**
- Create the file with an `impl Agent` block
- Move `maybe_hydrate_thread` and `hydrate_and_resolve_session_thread` from the
root file
- Add imports for `SessionManager`, `Uuid`, database store types, and
`rebuild_chat_messages_from_db`
- In `src/agent/thread_ops.rs`, remove the moved method bodies and add `mod
hydration;`

**Clean up root file (`src/agent/thread_ops.rs`):**
- Confirm the root file retains exactly these four items:
`store_extracted_documents` (free function, thin wrapper), `handle_message`
(main entry point), `check_auth_mode_intercept` (private helper), and
`set_tool_context_for_message` (private helper)
- Verify all eight `mod` declarations are present: `approval`, `control`,
`dispatch`, `document_store`, `hydration`, `message_rebuild`, `persistence`,
`turn_execution`
- Remove any unused imports
- Run `cargo check` and `cargo test` to confirm compilation succeeds and all
tests pass

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!