Refactor src/worker/job.rs to reduce Low Cohesion (responsibilities 74 → ≤3)

[coderabbitai]

Low Cohesion in src/worker/job.rs

CodeScene has flagged a significant worsening of the Low Cohesion biomarker in src/worker/job.rs:

The number of different responsibilities increases from 8 to 74, threshold = 3

This was identified during PR #123 (Add regression coverage for worker reload contracts).

Why this matters

High numbers of distinct responsibilities in a single module indicate that the file is doing too much. This makes the code harder to understand, test, and maintain, and increases the risk of unintended coupling between concerns.

Suggested next steps

• Audit the responsibilities now present in and group related ones.
• Extract cohesive subsets into dedicated modules (e.g. separate tool invocation, safety checks, state management, and event emission).
• Review imports such as , ///, and to determine whether they belong in a thinner coordination layer or in dedicated sub-modules.

References

• PR: Add regression coverage for worker reload contracts #123
• CodeScene delta report: https://codescene.io/projects/77987/delta?repo-id=1501128&review-id=123&biomarker=Low+Cohesion&filename=src%2Fworker%2Fjob.rs&method=

/cc @leynos

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Restructure src/worker/job.rs into a job/ subdirectory following the established codebase pattern of thin coordinators with focused submodules
• Extract four cohesive submodules: events.rs (event emission + state transitions), tool_execution.rs (approval/rate-limit/hook/safety/execute pipeline), delegate.rs (NativeLoopDelegate implementation), and planning.rs (plan generation and execution)
• Reduce mod.rs to ~300 lines containing only Worker, WorkerDeps, and high-level orchestration (run, execution_loop)
• Preserve the existing public API (Worker, WorkerDeps re-exports) and all runtime behaviour

Implementation Steps

Phase 1: Create Directory Structure and Extract Events/State Module

Establish the job/ subdirectory structure and extract the event emission and state transition logic. These two concerns are tightly coupled—terminal state transitions always trigger terminal events—so group them together. This unlocks subsequent extractions that depend on event logging.

Task 1: Create job/ Directory and Module Skeleton

Set up the new directory structure and prepare the module hierarchy.

• Create src/worker/job/ directory
• Create src/worker/job/mod.rs containing Worker, WorkerDeps, ToolExecResult, and WorkerLoopOutcome structs plus the convenience accessor methods
• Declare submodules: mod events;, mod tool_execution;, mod planning;, mod delegate;
• Update src/worker/mod.rs to reference mod job; (path now job/mod.rs) instead of job.rs

Task 2: Extract Events and State Transitions

Move all event emission, SSE broadcasting, and terminal state management into a dedicated submodule.

• Create src/worker/job/events.rs
• Move persist_status, log_event, log_terminal_result_event, and broadcast_event into this module as functions receiving &WorkerDeps and job_id
• Move mark_completed, mark_failed, and mark_stuck into this module (they orchestrate state transitions + terminal event logging)
• Expose these functions via pub(super) or pub(crate) as appropriate
• Update call sites in mod.rs to invoke the extracted functions

🤖 Prompt for AI agents

Restructure `src/worker/job.rs` into a `job/` subdirectory by creating the
module skeleton and extracting the events/state module. The goal is to establish
the directory layout and isolate event emission and state transition logic as
the first cohesive submodule.

**Step 1 — Create the directory and module skeleton:**
- Create the `src/worker/job/` directory
- Create `src/worker/job/mod.rs` — move `Worker`, `WorkerDeps`,
`ToolExecResult`, and `WorkerLoopOutcome` struct definitions and their
convenience accessor methods into this file
- Declare the following submodules at the top of `mod.rs`: `mod events;`, `mod
tool_execution;`, `mod planning;`, `mod delegate;`
- Update `src/worker/mod.rs` to point `mod job;` at `job/mod.rs` rather than the
old `job.rs` flat file

**Step 2 — Extract events and state transitions into
`src/worker/job/events.rs`:**
- Move `persist_status`, `log_event`, `log_terminal_result_event`, and
`broadcast_event` — all as free functions receiving `&WorkerDeps` and `job_id`
- Move `mark_completed`, `mark_failed`, and `mark_stuck` into the same file, as
they orchestrate state transitions and terminal event logging together
- Expose all moved functions with `pub(super)` or `pub(crate)` visibility as
appropriate
- Update all call sites in `mod.rs` to invoke the newly extracted functions from
`events.rs`
- Do not change any runtime behaviour

Phase 2: Extract Tool Execution Pipeline

The tool execution pipeline (lines ~483–1079) is the largest single concern at ~600 lines. Extract it to isolate approval checks, rate limiting, hook invocation, safety validation, parallel execution, timeout enforcement, and action recording.

Task 1: Create Tool Execution Module

Extract the entire tool execution pipeline into its own submodule.

• Create src/worker/job/tool_execution.rs
• Move execute_tool_inner, execute_tools_parallel, execute_tool, and process_tool_result_job into this module
• These functions receive &WorkerDeps, job_id, and the necessary parameters
• Retain the ten-step execution sequence (lookup → approval → context → rate limit → hook → safety → execute → memory → persist → serialise) without behavioural changes
• Import event functions from events.rs for log_event calls within tool processing

Task 2: Wire Tool Execution into Coordinator

Connect the extracted tool execution module back to the main coordinator and delegate.

• Update mod.rs to call tool_execution::execute_tool and tool_execution::execute_tools_parallel
• Ensure JobDelegate::execute_tool_calls delegates to the new module
• Verify all tool-related imports are now sourced from tool_execution.rs

🤖 Prompt for AI agents

Extract the tool execution pipeline from `mod.rs` into
`src/worker/job/tool_execution.rs`, then wire it back into the coordinator. The
goal is to isolate all ~600 lines of approval, rate-limiting, hook, safety,
execution, and recording logic into a single focused submodule.

**Step 1 — Create `src/worker/job/tool_execution.rs`:**
- Move `execute_tool_inner`, `execute_tools_parallel`, `execute_tool`, and
`process_tool_result_job` into this file
- All moved functions must receive `&WorkerDeps`, `job_id`, and their necessary
parameters
- Preserve the ten-step execution sequence exactly: lookup → approval → context
→ rate limit → hook → safety → execute → memory → persist → serialise
- Import `log_event` and related functions from `super::events` for any logging
calls within tool processing
- Do not alter any runtime behaviour

**Step 2 — Wire the module into the coordinator:**
- Update `mod.rs` to replace inline function bodies with calls to
`tool_execution::execute_tool` and `tool_execution::execute_tools_parallel`
- Ensure `JobDelegate::execute_tool_calls` delegates to the new module's
functions
- Confirm all tool-related imports are now sourced exclusively from
`tool_execution.rs`

Phase 3: Extract Delegate, Planning, and Finalise Coordinator

Extract the remaining concerns—JobDelegate implementation and planning phase—then slim down mod.rs to a thin orchestration layer.

Task 1: Extract JobDelegate Module

Move the NativeLoopDelegate implementation into its own submodule.

• Create src/worker/job/delegate.rs
• Move JobDelegate struct, handle_rate_limit, and the entire NativeLoopDelegate impl block
• Move selections_to_tool_calls helper function
• The delegate calls into tool_execution and events modules for execution and logging

Task 2: Extract Planning Module

Move planning-related logic into a dedicated submodule.

• Create src/worker/job/planning.rs
• Move generate_plan, maybe_plan_and_execute, and execute_plan functions
• These functions receive &Worker (or &WorkerDeps) plus the necessary Reasoning and ReasoningContext parameters
• Import from tool_execution for plan step execution and from events for plan logging

Task 3: Slim Down mod.rs to Thin Coordinator

Reduce mod.rs to contain only the core orchestration logic and re-exports.

• Retain Worker, WorkerDeps, ToolExecResult, WorkerLoopOutcome definitions
• Retain Worker::new and Worker::run (the main entry point)
• Retain execution_loop which orchestrates planning and delegates to run_agentic_loop
• Remove all extracted function bodies; replace with calls to submodule functions
• Re-export Worker and WorkerDeps via pub use for external consumers
• Verify the public API exposed by src/worker/mod.rs remains unchanged

Task 4: Relocate Tests

Move inline tests to accompany their respective submodules.

• Move tool-execution tests (parallel speedup, ordering, missing tools, approval contexts) to tool_execution.rs
• Move state transition tests to events.rs
• Move delegate-related tests (token budget, iteration cap) to delegate.rs
• Keep integration-level worker tests in mod.rs or a dedicated tests.rs submodule
• Ensure all test helpers (SlowTool, StubLlm, make_worker) remain accessible to tests that need them

🤖 Prompt for AI agents

Extract the `JobDelegate` and planning logic into their own submodules, then
finalise `mod.rs` as a thin coordinator and relocate all inline tests. The goal
is to complete the refactor so that `mod.rs` is reduced to ~300 lines of pure
orchestration.

**Step 1 — Create `src/worker/job/delegate.rs`:**
- Move `JobDelegate` struct, `handle_rate_limit`, and the entire
`NativeLoopDelegate` impl block into this file
- Move the `selections_to_tool_calls` helper function alongside them
- Call into `super::tool_execution` and `super::events` for execution and
logging respectively

**Step 2 — Create `src/worker/job/planning.rs`:**
- Move `generate_plan`, `maybe_plan_and_execute`, and `execute_plan` into this
file
- All moved functions receive `&Worker` (or `&WorkerDeps`) plus the necessary
`Reasoning` and `ReasoningContext` parameters
- Import from `super::tool_execution` for plan step execution and from
`super::events` for plan logging

**Step 3 — Slim down `mod.rs`:**
- Retain only `Worker`, `WorkerDeps`, `ToolExecResult`, and `WorkerLoopOutcome`
definitions
- Retain `Worker::new`, `Worker::run`, and `execution_loop`
- Remove all extracted function bodies; replace each with a call to the
appropriate submodule function
- Add `pub use` re-exports for `Worker` and `WorkerDeps` to preserve the
external public API
- Verify the public API exposed by `src/worker/mod.rs` is unchanged

**Step 4 — Relocate inline tests:**
- Move tool-execution tests (parallel speedup, ordering, missing tools, approval
contexts) into `tool_execution.rs`
- Move state transition tests into `events.rs`
- Move delegate-related tests (token budget, iteration cap) into `delegate.rs`
- Keep integration-level worker tests in `mod.rs` or a dedicated `tests.rs`
submodule
- Ensure test helpers (`SlowTool`, `StubLlm`, `make_worker`) remain accessible
to all tests that require them

Research

The src/worker/ directory follows a pattern where major components have their own subdirectories with focused submodules (e.g., container/delegate.rs, container/reporting.rs, claude_bridge/orchestration.rs). Sibling modules such as src/tools/, src/safety/, and src/hooks/ all use a thin mod.rs coordinator that re-exports from single-responsibility submodules. The WorkerDeps struct already encapsulates dependencies cleanly. job.rs currently contains ~2,015 lines mixing six distinct concerns: lifecycle management, agentic loop orchestration, tool execution pipeline, event emission, state transitions, and signal handling via JobDelegate.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Restructure `src/worker/job.rs` into a `job/` subdirectory by creating the
module skeleton and extracting the events/state module. The goal is to establish
the directory layout and isolate event emission and state transition logic as
the first cohesive submodule.

**Step 1 — Create the directory and module skeleton:**
- Create the `src/worker/job/` directory
- Create `src/worker/job/mod.rs` — move `Worker`, `WorkerDeps`,
`ToolExecResult`, and `WorkerLoopOutcome` struct definitions and their
convenience accessor methods into this file
- Declare the following submodules at the top of `mod.rs`: `mod events;`, `mod
tool_execution;`, `mod planning;`, `mod delegate;`
- Update `src/worker/mod.rs` to point `mod job;` at `job/mod.rs` rather than the
old `job.rs` flat file

**Step 2 — Extract events and state transitions into
`src/worker/job/events.rs`:**
- Move `persist_status`, `log_event`, `log_terminal_result_event`, and
`broadcast_event` — all as free functions receiving `&WorkerDeps` and `job_id`
- Move `mark_completed`, `mark_failed`, and `mark_stuck` into the same file, as
they orchestrate state transitions and terminal event logging together
- Expose all moved functions with `pub(super)` or `pub(crate)` visibility as
appropriate
- Update all call sites in `mod.rs` to invoke the newly extracted functions from
`events.rs`
- Do not change any runtime behaviour
===============================================================================

Task: 2

Extract the tool execution pipeline from `mod.rs` into
`src/worker/job/tool_execution.rs`, then wire it back into the coordinator. The
goal is to isolate all ~600 lines of approval, rate-limiting, hook, safety,
execution, and recording logic into a single focused submodule.

**Step 1 — Create `src/worker/job/tool_execution.rs`:**
- Move `execute_tool_inner`, `execute_tools_parallel`, `execute_tool`, and
`process_tool_result_job` into this file
- All moved functions must receive `&WorkerDeps`, `job_id`, and their necessary
parameters
- Preserve the ten-step execution sequence exactly: lookup → approval → context
→ rate limit → hook → safety → execute → memory → persist → serialise
- Import `log_event` and related functions from `super::events` for any logging
calls within tool processing
- Do not alter any runtime behaviour

**Step 2 — Wire the module into the coordinator:**
- Update `mod.rs` to replace inline function bodies with calls to
`tool_execution::execute_tool` and `tool_execution::execute_tools_parallel`
- Ensure `JobDelegate::execute_tool_calls` delegates to the new module's
functions
- Confirm all tool-related imports are now sourced exclusively from
`tool_execution.rs`
===============================================================================

Task: 3

Extract the `JobDelegate` and planning logic into their own submodules, then
finalise `mod.rs` as a thin coordinator and relocate all inline tests. The goal
is to complete the refactor so that `mod.rs` is reduced to ~300 lines of pure
orchestration.

**Step 1 — Create `src/worker/job/delegate.rs`:**
- Move `JobDelegate` struct, `handle_rate_limit`, and the entire
`NativeLoopDelegate` impl block into this file
- Move the `selections_to_tool_calls` helper function alongside them
- Call into `super::tool_execution` and `super::events` for execution and
logging respectively

**Step 2 — Create `src/worker/job/planning.rs`:**
- Move `generate_plan`, `maybe_plan_and_execute`, and `execute_plan` into this
file
- All moved functions receive `&Worker` (or `&WorkerDeps`) plus the necessary
`Reasoning` and `ReasoningContext` parameters
- Import from `super::tool_execution` for plan step execution and from
`super::events` for plan logging

**Step 3 — Slim down `mod.rs`:**
- Retain only `Worker`, `WorkerDeps`, `ToolExecResult`, and `WorkerLoopOutcome`
definitions
- Retain `Worker::new`, `Worker::run`, and `execution_loop`
- Remove all extracted function bodies; replace each with a call to the
appropriate submodule function
- Add `pub use` re-exports for `Worker` and `WorkerDeps` to preserve the
external public API
- Verify the public API exposed by `src/worker/mod.rs` is unchanged

**Step 4 — Relocate inline tests:**
- Move tool-execution tests (parallel speedup, ordering, missing tools, approval
contexts) into `tool_execution.rs`
- Move state transition tests into `events.rs`
- Move delegate-related tests (token budget, iteration cap) into `delegate.rs`
- Keep integration-level worker tests in `mod.rs` or a dedicated `tests.rs`
submodule
- Ensure test helpers (`SlowTool`, `StubLlm`, `make_worker`) remain accessible
to all tests that require them

💡 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!