Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add implementation plan for code quality fixes

Cursor Agentbe2d5b1d9ee7
diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md
new file mode 100644
index 00000000..0ffa8a67
--- /dev/null
+++ b/IMPLEMENTATION_PLAN.md
@@ -0,0 +1,237 @@
+# Implementation Plan: Code Quality Fixes
+
+A phased plan to address all issues from the codebase quality review. Tasks are ordered by dependency and risk.
+
+---
+
+## Phase 1: Low-Risk Cleanup (Dead Code & Redundant Wrappers)
+
+*Estimated effort: 1–2 hours | Risk: Low*
+
+### 1.1 Remove `MessageTree.get_queue_position`
+
+| Step | Action |
+|------|--------|
+| 1 | Search codebase for any `get_queue_position` calls |
+| 2 | Remove the method from `messaging/tree_data.py` (lines 268–276) |
+| 3 | Run tests: `pytest tests/test_tree_*.py tests/test_tree_concurrency.py -v` |
+
+**Verification:** No references remain; tree tests pass.
+
+---
+
+### 1.2 Remove or Document `extract_reasoning_from_delta`
+
+| Step | Action |
+|------|--------|
+| 1 | Remove from `providers/nvidia_nim/utils/__init__.py` exports |
+| 2 | Option A: Delete the function from `think_parser.py` if truly unused |
+| 2 | Option B: Keep function, add docstring: "For external/direct delta inspection. NIM client uses getattr(delta, 'reasoning_content') directly." |
+| 3 | Run: `pytest tests/test_nvidia_nim.py tests/test_parsers.py -v` |
+
+**Recommendation:** Option A (delete) — YAGNI. Can reintroduce if needed.
+
+---
+
+### 1.3 Remove `_extract_text_from_content` Wrapper
+
+| Step | Action |
+|------|--------|
+| 1 | In `tests/test_extract_text.py`, change import from `providers.logging_utils._extract_text_from_content as logging_extract` to `utils.text.extract_text_from_content as logging_extract` |
+| 2 | Remove `_extract_text_from_content` from `providers/logging_utils.py` |
+| 3 | Run: `pytest tests/test_extract_text.py tests/test_logging_utils*.py -v` |
+
+**Verification:** Tests still pass; no other imports of `_extract_text_from_content`.
+
+---
+
+## Phase 2: Extract Markdown Utilities (Modularity & DRY)
+
+*Estimated effort: 2–3 hours | Risk: Low–Medium*
+
+### 2.1 Create `messaging/telegram_markdown.py`
+
+| Step | Action |
+|------|--------|
+| 1 | Create new file `messaging/telegram_markdown.py` |
+| 2 | Move from `handler.py`: `MDV2_SPECIAL_CHARS`, `MDV2_LINK_ESCAPE`, `_MD`, `_TABLE_SEP_RE`, `_FENCE_RE` |
+| 3 | Move functions: `_is_gfm_table_header_line`, `_normalize_gfm_tables`, `escape_md_v2`, `escape_md_v2_code`, `escape_md_v2_link_url`, `mdv2_bold`, `mdv2_code_inline`, `format_status`, `render_markdown_to_mdv2` |
+| 4 | Add `__all__` with public exports |
+| 5 | Update `messaging/handler.py`: `from .telegram_markdown import ...` (all moved symbols) |
+| 6 | Update `messaging/telegram.py`: `from .telegram_markdown import escape_md_v2` and remove local definition |
+| 7 | Update tests: `test_handler_format.py`, `test_robust_formatting.py`, `test_transcript.py`, `test_reliability.py` — import from `messaging.telegram_markdown` |
+| 8 | Run full test suite |
+
+**Verification:** All markdown-related tests pass; no duplicate `escape_md_v2`.
+
+---
+
+### 2.2 Slim Down `handler.py`
+
+| Step | Action |
+|------|--------|
+| 1 | After Phase 2.1, `handler.py` should only contain `ClaudeMessageHandler` and its imports |
+| 2 | Confirm no markdown logic remains in handler |
+| 3 | Run: `pytest tests/test_handler*.py tests/test_transcript.py -v` |
+
+---
+
+## Phase 3: Split `_process_node` (Simplicity)
+
+*Estimated effort: 2–3 hours | Risk: Medium*
+
+### 3.1 Extract Helper Methods
+
+| Step | Action |
+|------|--------|
+| 1 | Extract `_setup_render_ctx()` — returns `(TranscriptBuffer, RenderCtx)` |
+| 2 | Extract `_handle_session_info_event(event_data, tree, node_id, ...)` — handles session_info, returns updated session_id/temp_id |
+| 3 | Extract `_dispatch_transcript_event(parsed, transcript, update_ui, ...)` — maps event types to transcript.apply + status updates |
+| 4 | Extract `_finalize_node_success(tree, node_id, captured_session_id)` — state update + persist |
+| 5 | Extract `_finalize_node_error(node_id, error_msg, tree)` — propagate error, update UI |
+| 6 | Refactor `_process_node` to call these helpers in sequence |
+| 7 | Run: `pytest tests/test_handler*.py tests/test_handler_integration.py -v` |
+
+**Design note:** Keep `update_ui` as a closure inside `_process_node` (it needs `last_ui_update`, `last_displayed_text`, etc.) or pass a small state object.
+
+---
+
+## Phase 4: Time Complexity — `find_node_by_status_message` O(1)
+
+*Estimated effort: 1–2 hours | Risk: Low*
+
+### 4.1 Add Reverse Index to MessageTree
+
+| Step | Action |
+|------|--------|
+| 1 | In `MessageTree.__init__`, add `self._status_to_node: Dict[str, str] = {}` |
+| 2 | In `add_node`, after creating node: `self._status_to_node[status_message_id] = node_id` |
+| 3 | In `from_dict`, after loading nodes: build `_status_to_node` from all nodes |
+| 4 | Rewrite `find_node_by_status_message`: `node_id = self._status_to_node.get(status_msg_id); return self._nodes.get(node_id) if node_id else None` |
+| 5 | Consider: when a node is removed (e.g. cleanup), remove from `_status_to_node` — currently nodes are rarely removed, so defer if not needed |
+| 6 | Run: `pytest tests/test_tree_repository.py tests/test_tree_concurrency.py tests/test_restart_reply_restore.py -v` |
+
+**Verification:** `resolve_parent_node_id` behavior unchanged; tests pass.
+
+---
+
+## Phase 5: Encapsulation — Repository & Tree API
+
+*Estimated effort: 2–3 hours | Risk: Medium*
+
+### 5.1 TreeRepository — Add Proper Methods
+
+| Step | Action |
+|------|--------|
+| 1 | Add `has_node(node_id: str) -> bool` |
+| 2 | Add `get_tree_by_parent(parent_node_id: str) -> Optional[MessageTree]` (or `get_root_id_for_node`) |
+| 3 | Add `tree_count() -> int` |
+| 4 | Add `get_all_tree_data() -> dict` returning `{"trees": ..., "node_to_tree": ...}` for serialization |
+| 5 | Update `TreeQueueManager` to use these methods instead of `_repository._trees` and `_repository._node_to_tree` |
+| 6 | Remove or deprecate `TreeQueueManager._trees` and `_node_to_tree` properties |
+| 7 | Update `handler._handle_clear_command` if it uses `_trees` directly — it uses `to_dict()` which goes through `TreeRepository.to_dict()`, so likely no change |
+| 8 | Update `tests/test_messaging.py` and any test that asserts on `mgr._trees` — use `mgr.to_dict()` or new accessors |
+| 9 | Run full test suite |
+
+---
+
+### 5.2 MessageTree — Encapsulate Queue Access
+
+| Step | Action |
+|------|--------|
+| 1 | Add `cancel_current_task() -> bool` — cancels `_current_task` if running |
+| 2 | Add `clear_queue_and_mark_stale() -> List[MessageNode]` — drains queue, returns affected nodes, sets `_is_processing = False` |
+| 3 | Add `get_queue_node_ids() -> List[str]` — returns `list(self._queue._queue)` (or a proper copy method) |
+| 4 | Update `TreeQueueManager.cancel_tree` and `TreeQueueProcessor` to use these methods instead of direct `_queue`, `_lock`, etc. |
+| 5 | Run: `pytest tests/test_tree_*.py tests/test_handler*.py -v` |
+
+**Note:** `TreeQueueProcessor` is tightly coupled to `MessageTree` internals by design (same module). Focus on `TreeQueueManager.cancel_tree` not reaching into `tree._queue._queue` directly.
+
+---
+
+## Phase 6: NIM Client — ContentBlockManager Fields
+
+*Estimated effort: 1 hour | Risk: Low*
+
+### 6.1 Add Explicit Fields to ContentBlockManager
+
+| Step | Action |
+|------|--------|
+| 1 | In `providers/nvidia_nim/utils/sse_builder.py`, add to `ContentBlockManager`: `task_arg_buffer: Dict[int, str] = field(default_factory=dict)`, `task_args_emitted: Dict[int, bool] = field(default_factory=dict)`, `tool_ids: Dict[int, str] = field(default_factory=dict)` (if not already present) |
+| 2 | In `NvidiaNimProvider._process_tool_call` and `_flush_task_arg_buffers`, remove the `getattr`/`isinstance` checks and use `sse.blocks.task_arg_buffer` etc. directly |
+| 3 | Run: `pytest tests/test_nvidia_nim.py tests/test_sse_builder.py -v` |
+
+**Verification:** No dynamic attribute creation; all fields declared.
+
+---
+
+## Phase 7: Routes Optimization Refactor (Optional)
+
+*Estimated effort: 1–2 hours | Risk: Low*
+
+### 7.1 Extract Optimization Handlers
+
+| Step | Action |
+|------|--------|
+| 1 | Create `api/optimization_handlers.py` |
+| 2 | Define `OptimizationResult` (or use `Optional[MessagesResponse]`) |
+| 3 | Implement functions: `try_prefix_detection(request_data, settings) -> Optional[MessagesResponse]`, `try_quota_mock(...)`, `try_title_skip(...)`, `try_suggestion_skip(...)`, `try_filepath_mock(...)` |
+| 4 | In `routes.py`, loop: `for fn in [try_prefix_detection, try_quota_mock, ...]: result = fn(request_data, settings); if result: return result` |
+| 5 | Run: `pytest tests/test_routes_optimizations.py tests/test_api.py -v` |
+
+**Alternative:** Keep current structure but extract each block into a named function for readability. Less structural change, still improves clarity.
+
+---
+
+## Phase 8: Request Utils Split (Optional)
+
+*Estimated effort: 1–2 hours | Risk: Low*
+
+### 8.1 Reorganize request_utils.py
+
+| Step | Action |
+|------|--------|
+| 1 | Create `api/detection.py`: move `is_quota_check_request`, `is_title_generation_request`, `is_prefix_detection_request`, `is_suggestion_mode_request`, `is_filepath_extraction_request` |
+| 2 | Create `api/command_utils.py`: move `extract_command_prefix`, `extract_filepaths_from_command` |
+| 3 | Keep `get_token_count` in `request_utils.py` (or move to `providers/model_utils.py`) |
+| 4 | Update `routes.py` and `request_utils.py` imports |
+| 5 | Update `tests/test_request_utils*.py` imports |
+| 6 | Run: `pytest tests/test_request_utils*.py tests/test_routes_optimizations.py -v` |
+
+---
+
+## Execution Order & Dependencies
+
+```
+Phase 1 (Dead code) ──► No dependencies
+Phase 2 (Markdown) ──► No dependencies
+Phase 3 (_process_node) ──► Can run after Phase 2 (handler is slimmer)
+Phase 4 (O(1) lookup) ──► No dependencies
+Phase 5 (Encapsulation) ──► No dependencies; can run in parallel with 4
+Phase 6 (NIM blocks) ──► No dependencies
+Phase 7 (Routes) ──► Optional
+Phase 8 (Request utils) ──► Optional
+```
+
+**Suggested order:** 1 → 2 → 3 → 4 → 5 → 6 → (7, 8 if desired)
+
+---
+
+## Rollback Strategy
+
+- Each phase is a separate commit (or small set of commits).
+- If a phase causes regressions, revert that commit.
+- Phases 1–4, 6 are independent; reverting one does not affect others.
+- Phase 5 touches multiple call sites; run full test suite before merging.
+
+---
+
+## Success Criteria
+
+- [ ] All existing tests pass
+- [ ] No new linter errors
+- [ ] `handler.py` under ~600 lines (after markdown extraction + _process_node split)
+- [ ] No duplicate `escape_md_v2` implementations
+- [ ] No dead code (get_queue_position, extract_reasoning_from_delta, _extract_text wrapper)
+- [ ] `find_node_by_status_message` is O(1)
+- [ ] TreeQueueManager does not expose `_trees`/`_node_to_tree` to external callers