openclacky 1.3.3 → 1.3.4

data/docs/rich_ui_refactor_plan.md

@@ -0,0 +1,396 @@
+# RichUI Controller Refactoring Plan
+
+> Goal: Learn from UI2's MVC layering, componentization, and id-based content management to refactor `lib/clacky/rich_ui_controller.rb` (2336 lines, 12+ classes) into a clear, single-responsibility, maintainable modular architecture.
+
+---
+
+## I. Current State Diagnosis
+
+### 1.1 Core Problems
+
+| Problem | Current State | Impact |
+|---------|---------------|--------|
+| **Single file too large** | 2336 lines, 12+ classes (Shell, Sidebar, 3 Panels, StatusView, ThinkingLiveView, UIController, 3 Dialogs, 2 Adapters) | High code conflict rate, difficult code review, steep onboarding cost |
+| **No MVC layering** | Rendering logic, layout coordinates, business state, and event callbacks all mixed together | Cannot unit-test rendering logic; changing one part may ripple through everything |
+| **No component system** | All output is inline string concatenation (`"#{AnsiCode.color(:green)}✓#{reset}"`) | Style leakage, hard to maintain uniformly, not reusable |
+| **Centralized monkey patches** | Patches for `RubyRich::Viewport`, `RubyRich::Transcript`, `RubyRich::Markdown::TerminalRenderer` crammed at the top of the file | Patches entangled with business code; concentrated risk when upgrading the gem |
+| **Deep coupling with gem internals** | Extensive `instance_variable_get(:@callbacks)`, `instance_variable_set(:@on_interrupt, nil)` | RubyRich internal refactoring causes breakage — fragile external dependency |
+| **Dialogs embedded inline** | `ConfigMenuDialog`, `FormDialog`, `ApprovalDialog` defined in the same file | Dialog logic growth further bloats file size |
+| **No id-based content management** | Relies on `ruby_rich`'s `transcript.store.entries`; no custom OutputBuffer | Cannot precisely `replace`/`remove` non-tail content; lacks commit dedup mechanism |
+| **Theme hardcoded** | `RubyRich::Theme.whale_dark` hardwired in `RichUIController#initialize` | Users cannot switch themes; not interoperable with UI2's theme system |
+| **Progress is an adapter wrapper** | `ProgressHandleAdapter` just wraps ruby_rich native handles; no UI2 v2 semantics (owned handle, stack, quiet_on_fast_finish) | Concurrent progress contention; fast-finish unsupported |
+
+### 1.2 Key Gaps vs. UI2
+
+```
+UI2 Architecture (mature)                RichUI Architecture (to be refactored)
+─────────────────────────────────        ─────────────────────────────────
+UIController  (coordination, thin)        RichUIController (coordination + rendering + layout, thick)
+  ├── ViewRenderer  (view dispatch)       └── no counterpart, directly manipulates strings
+  │     ├── MessageComponent              └── no component, inline concatenation
+  │     ├── ToolComponent                 └── no component, inline concatenation
+  │     └── CommonComponent               └── no component, inline concatenation
+  ├── LayoutManager  (layout engine)      └── no counterpart, relies on RubyRich::Layout
+  │     └── OutputBuffer  (id-based)      └── no counterpart, relies on transcript.entries
+  ├── ScreenBuffer   (ANSI primitives)    └── no counterpart, encapsulated by ruby_rich
+  ├── InputArea      (input editor)       └── RubyRich::Composer (external, but intruded via ivar)
+  └── ThemeManager   (theme system)       └── hardcoded Theme.whale_dark
+```
+
+---
+
+## II. Refactoring Goals
+
+1. **File splitting**: Single file → multi-file modular, each class in its own file
+2. **MVC layering**: Introduce `ViewRenderer` + `Components` + `LayoutAdapter` layers
+3. **Componentization**: Extract Panel, Dialog, Status as independent Components
+4. **Decouple from gem**: Move monkey patches into `extensions/`; reduce `instance_variable_get`
+5. **id-based content management** (optional enhancement): Wrap a lightweight id tracking layer on top of RubyRich Transcript
+6. **Theme interoperability**: Reuse or bridge UI2's `ThemeManager` so `--theme` takes effect
+
+---
+
+## III. Target Directory Structure
+
+```
+lib/clacky/
+├── rich_ui.rb                              # Entry file (similar to ui2.rb)
+├── rich_ui/
+│   ├── rich_ui_controller.rb               # Thin Controller (from 2336 lines → target < 300 lines)
+│   ├── layout_adapter.rb                   # Layout coordination (replaces original LayoutAdapter)
+│   ├── progress_handle_adapter.rb          # Progress adapter (existing, retained)
+│   │
+│   ├── components/                         # View components (similar to ui2/components/)
+│   │   ├── base_component.rb               # Base class: provides muted, colored, truncate, etc.
+│   │   ├── message_component.rb            # Message rendering (user/assistant/system)
+│   │   ├── tool_component.rb               # Tool call/result/error rendering
+│   │   ├── common_component.rb             # Progress/success/error/warning rendering
+│   │   ├── welcome_banner.rb               # Welcome banner (reuse UI2 or independent impl)
+│   │   ├── thinking_live_view.rb           # Thinking area (original ThinkingLiveView)
+│   │   ├── status_view.rb                  # Bottom status bar (original RichStatusView)
+│   │   ├── sidebar.rb                      # Sidebar container (original RichSidebar)
+│   │   ├── sidebar_panels.rb               # WorkPanel/TasksPanel/ContextPanel
+│   │   └── dialogs/                        # Dialog components
+│   │       ├── base_dialog.rb              # Shared wait/finish/key protocol
+│   │       ├── config_menu_dialog.rb       # Model configuration menu
+│   │       ├── form_dialog.rb              # Form input
+│   │       └── approval_dialog.rb          # Approval confirmation
+│   │
+│   ├── extensions/                         # Extensions to ruby_rich (replaces top-level monkey patches)
+│   │   ├── viewport_selection.rb           # Viewport text selection and clipboard
+│   │   ├── transcript_plain.rb             # Transcript plain mode
+│   │   └── markdown_table_adapter.rb       # TerminalRenderer table adapter
+│   │
+│   └── shell/                              # RichAgentShell and its configuration
+│       └── rich_agent_shell.rb             # Inherits RubyRich::AgentShell
+│
+└── cli.rb                                  # Update require paths
+```
+
+---
+
+## IV. Phased Implementation Plan
+
+### Phase 1: File Splitting and Directory Setup (Low Risk, Pure Movement)
+
+**Goal**: Split the 2336-line single file into multiple files by class, with zero behavioral change.
+
+| Step | Action |
+|------|--------|
+| 1.1 | Create `lib/clacky/rich_ui/` directory and subdirectories |
+| 1.2 | Move `RichAgentShell` into `rich_ui/shell/rich_agent_shell.rb` |
+| 1.3 | Move `RichSidebar` + 3 Panels into `rich_ui/components/sidebar.rb` and `sidebar_panels.rb` |
+| 1.4 | Move `ThinkingLiveView` into `rich_ui/components/thinking_live_view.rb` |
+| 1.5 | Move `RichStatusView` into `rich_ui/components/status_view.rb` |
+| 1.6 | Move 3 Dialogs into `rich_ui/components/dialogs/*.rb`, extract `BaseDialog` |
+| 1.7 | Move `LayoutAdapter`, `ProgressHandleAdapter` into `rich_ui/` root directory |
+| 1.8 | Create `lib/clacky/rich_ui.rb` entry file, unify requires |
+| 1.9 | Update `cli.rb`: `require_relative "rich_ui_controller"` → `require_relative "rich_ui"` |
+
+**Verification**: Run `--ui=rich`; all functionality identical.
+
+---
+
+### Phase 2: Monkey Patch Extraction and Decoupling (Medium Risk)
+
+**Goal**: Convert file-top monkey patches into explicit extension modules, reducing coupling.
+
+#### 2.1 Viewport Selection Extension
+
+**Current state**:
+```ruby
+class RubyRich::Viewport
+  alias_method :clacky_handle_event_without_text_selection, :handle_event
+  def handle_event(event_data, layout = nil)
+    # ... 30+ lines ...
+  end
+end
+```
+
+**After refactoring**: `lib/clacky/rich_ui/extensions/viewport_selection.rb`
+```ruby
+module Clacky::RichUI::Extensions::ViewportSelection
+  def self.apply!
+    RubyRich::Viewport.class_eval do
+      # patch here
+    end
+  end
+end
+
+# Explicitly invoked in rich_ui.rb entry point:
+Clacky::RichUI::Extensions::ViewportSelection.apply!
+```
+
+Benefits:
+- Patch code physically isolated from business logic
+- `apply!` is explicit — when upgrading the gem you can see at a glance where conflicts might arise
+- Can add `apply?` check (`method_defined?`) to avoid double loading
+
+#### 2.2 Markdown Table Extension
+
+Similarly moved into `extensions/markdown_table_adapter.rb`, with explicit `apply!`.
+
+#### 2.3 Reducing `instance_variable_get`
+
+**Current state** (multiple locations):
+```ruby
+clacky = @shell.instance_variable_get(:@clacky_controller)
+status = clacky.instance_variable_get(:@status)
+```
+
+**After refactoring**: Provide formal accessors in `RichAgentShell`:
+```ruby
+class RichAgentShell < RubyRich::AgentShell
+  attr_accessor :clacky_controller, :status, :work_label
+  # ...
+end
+```
+
+`RichStatusView` updated to:
+```ruby
+def render
+  clacky = @shell.clacky_controller
+  return [""] unless clacky
+  status = clacky.status
+  # ...
+end
+```
+
+---
+
+### Phase 3: Introduce ViewRenderer Component Layer (Medium Risk)
+
+**Goal**: Following UI2's `ViewRenderer` + `Components` pattern, extract string concatenation logic into testable components.
+
+#### 3.1 Create BaseComponent
+
+```ruby
+# lib/clacky/rich_ui/components/base_component.rb
+module Clacky::RichUI::Components
+  class BaseComponent
+    def muted(text)
+      "#{RubyRich::AnsiCode.color(:black, true)}#{text}#{RubyRich::AnsiCode.reset}"
+    end
+
+    def colored(text, color)
+      "#{RubyRich::AnsiCode.color(color, true)}#{text}#{RubyRich::AnsiCode.reset}"
+    end
+
+    def truncate(text, limit = 40)
+      # ...
+    end
+  end
+end
+```
+
+#### 3.2 Extract Sidebar Panels as Components
+
+Original `RichWorkPanel#render` inline concatenation:
+```ruby
+def render
+  lines = []
+  lines << @plan unless @plan.empty?
+  # ...
+  lines.join("\n")
+end
+```
+
+After refactoring:
+```ruby
+class SidebarWorkPanel < BaseComponent
+  def render(plan:, activities:, tasks:, cost:)
+    lines = []
+    lines << plan if plan && !plan.empty?
+    # ...
+    lines << muted("#{tasks} tasks · $#{cost.round(4)}")
+    lines.join("\n")
+  end
+end
+```
+
+Panel classes only retain **state storage**; rendering is delegated to Components.
+
+#### 3.3 Extract Dialog Rendering as Components
+
+`ApprovalDialog`'s `render_content`, `render_choices`, `category_badge`, `colored`, `muted` all use `BaseComponent` methods.
+
+After refactoring structure:
+```ruby
+class ApprovalDialog
+  # Retain: event loop, wait/finish, key binding (these are interaction logic)
+  # Remove: string concatenation in render_content → delegate to ApprovalDialogRenderer
+end
+
+class ApprovalDialogRenderer < BaseComponent
+  def render(tool_name:, message:, params:, risk:, category:, selected_index:)
+    # Pure rendering logic, no side effects, unit-testable
+  end
+end
+```
+
+---
+
+### Phase 4: Controller Slimming and Theme Interoperability (Medium Risk)
+
+#### 4.1 Controller Retains Only Coordination Logic
+
+Goal:
+```ruby
+class RichUIController
+  include Clacky::UIInterface
+
+  def initialize(config = {})
+    @config = config
+    @shell = RichAgentShell.new(...)
+    @renderer = ViewRenderer.new        # ← New
+    @sidebar = @shell.sidebar            # ← Provided by Shell
+    @progress_stack = []                 # ← Prepare for future v2
+    wire_callbacks
+  end
+
+  def show_tool_call(name, args)
+    output = @renderer.render_tool_call(name: name, args: args)
+    # ... delegate to ruby_rich for display
+  end
+end
+```
+
+#### 4.2 Reuse UI2 ThemeManager (Optional)
+
+**Approach A (bridge)**: RichUI continues using `RubyRich::Theme`, but maps names like `whale_dark` to UI2 theme names.
+
+**Approach B (unified)**: RichUI components accept UI2's `ThemeManager.current_theme`, calling `theme.format_symbol(:user)` instead of directly using `RubyRich::AnsiCode`.
+
+Recommend **Approach A** (low intrusion), providing theme bridging in `BaseComponent`:
+```ruby
+def theme
+  @theme ||= RubyRich::Theme.whale_dark
+end
+```
+
+---
+
+### Phase 5: id-based Content Management (Optional Enhancement, High Risk)
+
+UI2's `OutputBuffer` is the essence of its architecture, but RichUI relies on `ruby_rich`'s `Transcript` + `Viewport`; forcibly replacing them is costly.
+
+**Recommended approach**: Introduce a lightweight **EntryTracker** in RichUI instead of a full OutputBuffer.
+
+```ruby
+# lib/clacky/rich_ui/entry_tracker.rb
+class EntryTracker
+  # Tracks message_id / block_id returned by ruby_rich
+  # Provides:
+  # - register(id, type:) → record id
+  # - update(id, content) → call @shell.append_to_message(id, content)
+  # - remove(id) → call @shell.transcript.remove_entry(id)
+  # - current_tool_id → top-of-stack tool_call id
+end
+```
+
+Thus `show_tool_call` / `show_tool_result` no longer rely on `@tool_ids.pop` (fragile stack semantics), but instead explicitly track by id.
+
+---
+
+## V. Key Design Decisions
+
+### Decision 1: Should Monkey Patches Be Retained?
+
+**Conclusion**: Retain functionality, but move into `extensions/` directory with explicit `apply!`.
+
+Rationale:
+- The RubyRich gem does not provide extension points; without patching, selection/copy cannot be implemented
+- Centralized management means only `extensions/` needs checking when upgrading the gem
+
+### Decision 2: Should Dialogs Use RubyRich Native Dialog?
+
+**Conclusion**: Continue using custom Dialogs (`ConfigMenuDialog` etc.), but extract rendering layer into Components.
+
+Rationale:
+- RubyRich native Dialog capabilities are limited; current custom Dialogs already implement blocking wait and custom key bindings
+- Extracting Renderer decouples Dialog interaction logic from rendering styles
+
+### Decision 3: Should Sidebar Panels Be Split into Separate Files?
+
+**Conclusion**: 3 Panels (Work/Tasks/Context) merged into `sidebar_panels.rb`, but each as an independent class.
+
+Rationale:
+- Each Panel is only ~50 lines; separate files would be overly granular
+- Merged while maintaining class-level independence, facilitating later Component extraction
+
+### Decision 4: Should ProgressHandle v2 Be Introduced?
+
+**Conclusion**: Keep `ProgressHandleAdapter` bridging for now, but reserve interfaces for the future.
+
+Rationale:
+- ruby_rich's `start_progress` / `update` / `finish` semantics differ from UI2; forcing alignment has a wide blast radius
+- Can reserve `@progress_stack` in `RichUIController` and implement true stack semantics later
+
+---
+
+## VI. Verification Checklist
+
+After refactoring, the following functionality must be preserved 1:1:
+
+- [ ] `--ui=rich` starts normally, displays welcome banner
+- [ ] Full flow: user input → Agent response
+- [ ] Tool call cards (start/complete/error)
+- [ ] Thinking area real-time streaming
+- [ ] Right sidebar (Work/Tasks/Context panels and F1-F4 switching)
+- [ ] Bottom status bar (spinner, mode, model, task count, cost)
+- [ ] Mouse selection + right-click copy
+- [ ] Markdown table adaptive width
+- [ ] `/config` dialog (menu + form)
+- [ ] Tool approval dialog (ApprovalDialog)
+- [ ] Model switch dialog
+- [ ] Ctrl+C interrupt, Esc cancel stack, Tab switch mode
+- [ ] `--theme` parameter takes effect (or at least does not error)
+
+---
+
+## VII. Estimated Effort
+
+| Phase | Effort | Risk |
+|-------|--------|------|
+| Phase 1: File splitting | 2-3 hours | Low (pure movement + requires) |
+| Phase 2: Patch extraction + decoupling | 3-4 hours | Medium (carefully verify ivar replacements) |
+| Phase 3: ViewRenderer + Components | 4-6 hours | Medium (rendering logic extraction, compare output line by line) |
+| Phase 4: Controller slimming + themes | 2-3 hours | Medium |
+| Phase 5: EntryTracker (optional) | 4-6 hours | High (involves ruby_rich internal id mechanisms) |
+| **Total (excluding Phase 5)** | **11-16 hours** | |
+
+---
+
+## VIII. Immediate First Step
+
+If starting the refactoring now, recommended order:
+
+1. **Create directory structure**: `mkdir -p lib/clacky/rich_ui/{components/dialogs,extensions,shell}`
+2. **Phase 1 file splitting**: Cut classes one by one into new files, keep original file as compatibility shim (`require_relative "rich_ui"`)
+3. **Run smoke test**: `bundle exec ruby ./bin/openclacky agent --ui=rich`, confirm no require errors
+4. **Gradual replacement**: Verify after each class move; don't let changes pile up
+
+---
+
+*Plan date: 2026-06-11*
+*Reference baseline: UI2 architecture (`lib/clacky/ui2/` directory, docs/ui2-architecture.md)*

data/lib/clacky/agent/llm_caller.rb

@@ -201,12 +201,18 @@ module Clacky
             sleep retry_delay
             retry
           else
-            raise AgentError, "[LLM] Request timed out after #{max_retries} retries: #{e.message}"
+            raise AgentError, "[LLM] #{I18n.t("llm.error.request_timeout", retries: max_retries)}"
           end
 
-        rescue Faraday::ConnectionFailed, Faraday::SSLError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
+        rescue Faraday::ConnectionFailed, Faraday::SSLError, Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EPIPE => e
           retries += 1
 
+          # Errno::EPIPE means the underlying TCP socket is dead (server closed the
+          # connection after idle time). The Faraday connection object caches the
+          # socket, so retrying without resetting it would hit the same dead socket.
+          epipe = e.is_a?(Errno::EPIPE) || (e.respond_to?(:wrapped_exception) && e.wrapped_exception.is_a?(Errno::EPIPE))
+          @client.reset_connections! if epipe
+
           # Probing failure: primary still down — renew cooling-off and retry with fallback.
           if @config.probing?
             handle_probe_failure
@@ -230,7 +236,7 @@ module Clacky
           else
             # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
             # Progress cleanup is the caller's responsibility (via its own ensure block).
-            raise AgentError, "[LLM] Network connection failed after #{max_retries} retries: #{e.message}"
+            raise AgentError, "[LLM] #{I18n.t("llm.error.network_failed", retries: max_retries)}"
           end
 
         rescue RetryableError => e
@@ -268,7 +274,7 @@ module Clacky
         else
           # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
           # Progress cleanup is the caller's responsibility (via its own ensure block).
-          raise AgentError, "[LLM] Service unavailable after #{current_max} retries"
+          raise AgentError, "[LLM] #{I18n.t("llm.error.service_unavailable", retries: current_max)}"
         end
 
         rescue Clacky::BadRequestError => e

data/lib/clacky/agent/session_serializer.rb

@@ -17,6 +17,7 @@ module Clacky
         @total_cost = session_data.dig(:stats, :total_cost_usd) || 0.0
         @working_dir = session_data[:working_dir]
         @created_at = session_data[:created_at]
+        @persisted_updated_at = session_data[:updated_at]
         @total_tasks = session_data.dig(:stats, :total_tasks) || 0
         # Restore cost_source so frontend knows if cost is reliable
         cost_src = session_data.dig(:stats, :cost_source)
@@ -152,7 +153,7 @@ module Clacky
       # @param status [Symbol] Status of the last task: :success, :error, or :interrupted
       # @param error_message [String] Error message if status is :error
       # @return [Hash] Session data ready for serialization
-      def to_session_data(status: :success, error_message: nil)
+      def to_session_data(status: :success, error_message: nil, updated_at: nil, preserve_updated_at: false)
         stats_data = {
           total_tasks: @total_tasks,
           total_iterations: @iterations,
@@ -173,7 +174,7 @@ module Clacky
           name: @name,
           pinned: @pinned,
           created_at: @created_at,
-          updated_at: Time.now.iso8601,
+          updated_at: (updated_at || (preserve_updated_at && @persisted_updated_at) || Time.now.iso8601).then { |v| v.is_a?(String) ? v : v.iso8601 },
           working_dir: @working_dir,
           source: @source.to_s,                      # "manual" | "cron" | "channel" | "setup"
           agent_profile: @agent_profile&.name || "", # "general" | "coding" | custom

data/lib/clacky/agent.rb

@@ -252,7 +252,7 @@ module Clacky
       @name = new_name.to_s.strip
     end
 
-    def run(user_input, files: [], display_text: nil)
+    def run(user_input, files: [], display_text: nil, created_at: nil)
       # Show the "thinking" indicator as early as possible so the user gets
       # immediate feedback after sending a message. Without this the UI stays
       # silent during synchronous setup work (system prompt assembly, file
@@ -361,7 +361,8 @@ module Clacky
           preview_path: f[:preview_path] || f["preview_path"] }
       end
 
-      @history.append({ role: "user", content: user_content, task_id: task_id, created_at: Time.now.to_f,
+      created_at ||= Time.now.to_f
+      @history.append({ role: "user", content: user_content, task_id: task_id, created_at: created_at,
                         display_text: display_text,
                         display_files: display_files.empty? ? nil : display_files })
       @total_tasks += 1

data/lib/clacky/agent_config.rb

@@ -165,8 +165,7 @@ module Clacky
                   :memory_update_enabled, :skill_evolution,
                   :max_running_agents, :max_idle_agents,
                   :default_working_dir,
-                  :proxy_url,
-                  :media_output_dir
+                  :proxy_url
 
     def initialize(options = {})
       @permission_mode = validate_permission_mode(options[:permission_mode])
@@ -224,15 +223,6 @@ module Clacky
       # a proxy. Leave nil to go direct.
       @proxy_url = options[:proxy_url]
 
-      # User-configured directory where generated images / videos / audio
-      # land when a /api/media/* call doesn't pass an explicit output_dir.
-      # Final on-disk path is `<media_output_dir>/assets/generated/<file>`
-      # (the `assets/generated/` suffix is fixed by Media::Base for stable
-      # markdown/relative-path semantics across docs).
-      # Leave nil → fall back to Dir.pwd (legacy behavior, preserved for
-      # older configs that have no key set).
-      @media_output_dir = options[:media_output_dir]
-
       # Per-session virtual model overlay.
       # When set, #current_model returns a *merged* hash (the resolved @models
       # entry merged with this overlay) without mutating the shared @models
@@ -425,7 +415,6 @@ module Clacky
       skill_evolution max_running_agents max_idle_agents
       default_working_dir
       proxy_url
-      media_output_dir
     ].freeze
 
     # Serialize the current agent configuration to YAML.
@@ -445,8 +434,7 @@ module Clacky
         "max_running_agents" => @max_running_agents,
         "max_idle_agents" => @max_idle_agents,
         "default_working_dir" => @default_working_dir,
-        "proxy_url" => @proxy_url,
-        "media_output_dir" => @media_output_dir
+        "proxy_url" => @proxy_url
       }
       YAML.dump("settings" => settings, "models" => persistable_models)
     end