openclacky 1.3.3 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b9b4de98a5b98c110e4ee71bc8039c1b6445fda13f4479c42d466d80bb307bd
-  data.tar.gz: b47e189d857b86955eb95253e0b873d1cad16f9dfcb5040e29e638134151b9a8
+  metadata.gz: 8d5879a7f2c6eb0a1846dd3049fa79abd3ca53119750bd0a43b337339f146dad
+  data.tar.gz: 12a39e3d860e9e9e691424289543b73813bcb4652e11fe0719e72aa9e6c72760
 SHA512:
-  metadata.gz: 1ab60195873b54c48d72a4d6ebe5f79c9e5daeaa826f867c50cb79e5f6d367dd809b53ebe50aecd42af397cdd03962c0f0a5517ac2e94112b7399778d52c22ec
-  data.tar.gz: c11638e5355fde8fc2ade76d7868f8b68f47722dada241abafd34adf5a61fc88d5b734292ded5cb97cbdb4bc6360c9fd7b84a77ebd9fe95ec156a8eb02828556
+  metadata.gz: cdb47cb9da7cccae4329aa0d4b98f03d9e5cadf763c12b9cd255060e2f230154eed3e7404e494f9a0b7e7b54cdb569f2dc25a1ea69c0b8af386a4a1122942d65
+  data.tar.gz: 196c48e418e2119201664b920871aa489ff3531128a8aa8b981f73d6ddc95a7d3ef23ecb79da0611810b8af02735f83340ce0712ddb18ad30de0f94421dbd0a4

data/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.4] - 2026-06-25
+
+### Added
+- Skill edit UI with brand skill theme colors
+- WebUI language preference propagated to backend for localized error messages
+- Edit message resend with confirmation modal and localStorage key normalization
+- Duplicate model card action
+- i18n support for aside tab labels (files/git/time-machine)
+- File picker defaults to workspace with mkdir/rename support and hardened validation
+- API extensions and EPIPE rebuild client handling
+- Ruby Rich enhancement and refactoring (runtime dependency added)
+
+### Improved
+- Default aside panel to collapsed; sidebar widths aligned to 16rem
+- Onboarding manual config UX and spacing improvements
+- Fixed positioning for modal model/baseurl dropdowns to avoid overflow clipping
+- Disable transition during aside resize drag
+- Rename resetAfterUnbind to resetBrandState to avoid view/store collision
+
+### Fixed
+- Edit tool performs literal replacement (C-5682)
+- Shield code spans before math extraction to prevent LaTeX rendering (C-5635)
+- Preserve updated_at on idle compression and session eviction; fix Today/Yesterday display bug
+- Remove media output dir UI setting — always use session workspace
+- Test: stub req.path and req.request_method in check_access_key loopback bypass spec
+
 ## [1.3.3] - 2026-06-23
 
 ### Added

data/docs/rich_ui_guide.md

@@ -0,0 +1,277 @@
+# OpenClacky Rich UI Mode — Operations and Interface Display
+
+> Source directory: `lib/clacky/rich_ui/`
+> Terminal TUI interface built on the RubyRich library
+
+---
+
+## I. Overall Architecture
+
+`lib/clacky/rich_ui` is OpenClacky's terminal TUI interface module, built on the `RubyRich` library, implementing a complete terminal user interaction interface. The core entry point is `RichUIController` (`rich_ui_controller.rb`), which manages layout, components, events, and lifecycle through `RichAgentShell`.
+
+---
+
+## II. Interface Layout (7-layer Zoning)
+
+The interface is defined by the zoning layout in `RichAgentShell#build_layout`:
+
+| Zone | Name | Description |
+|------|------|-------------|
+| Row 1 | **Header** | Top title bar, displays `OpenClacky` title/subtitle |
+| Main body left | **Transcript** | Conversation viewport, displays user messages, assistant replies, tool calls, etc. |
+| Main body right | **Sidebar** | Sidebar (36 columns wide), contains Work / Tasks / Context three panels |
+| Main body bottom | **ThinkingLive** | Real-time thinking display area (dynamically appears/disappears, height 0 or 6 rows) |
+| From row 6 | **Composer** | Input editor, with Framed border titled "Composer" |
+| Last row | **Status** | Bottom status bar, displays current mode, model, task count, cost, etc. |
+
+---
+
+## III. Sidebar — Three Information Panels
+
+The sidebar (`RichSidebar`, `components/sidebar.rb`) supports multiple display modes, switched via F1-F4 shortcuts:
+
+- **F1 → Work panel**: Displays plan description, up to 8 recent tool activities (with status markers), task count and cost statistics
+- **F2 → Tasks panel**: Displays the current task list (from `update_todos`), with completion progress (e.g. `3/5 done`), status markers:
+  - `✓` (green) = Completed
+  - `●` (blue) = In progress
+  - `!` (red) = Failed
+  - `○` (gray) = Pending
+- **F3 → Auto mode**: Automatically displays all panels that have content
+- **F4 → Context panel**: Displays Token usage details (prompt / output / total / cost)
+
+Sidebar panels are implemented by `components/sidebar_panels.rb`:
+- `RichWorkPanel`: Work progress panel
+- `RichTasksPanel`: Task list panel
+- `RichContextPanel`: Context / Token info panel
+
+---
+
+## IV. Bottom Status Bar
+
+`RichStatusView` (`components/status_view.rb`) renders a single row of status information at the very bottom of the terminal:
+
+- **Idle state**: Shows mode name + "idle" + model name + task count + cost + "Ctrl+C quit"
+- **Working**: Shows rotating spinner animation + current tool name (e.g. "web_search…") + model/latency + task count + cost
+- **Ctrl+C warning**: Red prompt "Press Ctrl+C again to exit"
+- Latency info is appended after the model name (format: `model_name (1.2s)`)
+
+---
+
+## V. Transcript — Operations and Display
+
+### 5.1 Message Display
+
+- **User messages**: Displayed directly in the conversation area
+- **Assistant replies**: Rendered in Markdown format (supports code blocks, tables, lists, etc.)
+  - Long text (≥240 characters) triggers **streaming rendering**: 6 characters per chunk, 0.03s interval, appearing progressively
+  - File summaries are automatically appended at the end of replies (e.g. `Files - path/to/file.rb`)
+- **System messages**: Regular info / warning / error displayed in different colors
+- **Welcome banner**: On first launch, displays `WelcomeBanner` containing working directory, mode, etc.; if there is session history, shows a "recent session" separator and the last user message
+
+### 5.2 Thinking Process Display (Two Phases)
+
+1. **Live phase**: `ThinkingLiveView` (`components/thinking_live_view.rb`) dynamically appears (occupying 6 rows), renders thinking content character by character in real time, with a rotating spinner and elapsed time counter, stays for about 0.6s after completion
+2. **Collapsed phase**: Thinking content is retained in the conversation area as a collapsed block (marked "Xs"), press Ctrl+O to expand and view
+
+### 5.3 Tool Call Display
+
+Each tool call process is visualized in three steps:
+
+- **Start**: Insert a `running` status entry in the conversation area, displaying tool name and parameters (truncated as needed, e.g. `web_search("query...")`, `web_fetch(hostname)`)
+- **Complete**: Update entry status to `done` (green `[OK]`), with output content appended
+- **Error**: Update entry status to `error` (red `[Error]`), with error message appended
+
+Tool activities are simultaneously synced to the sidebar Work panel (up to 12 entries recorded).
+
+### 5.4 Diff Display
+
+Through the `show_diff` method, using the `Diffy` library to generate unified format diffs, truncated to 50 visible lines (excess lines indicate hidden count), with stats appended (e.g. `+5, -3, 2 hunks`).
+
+### 5.5 Token Usage Display
+
+`show_token_usage` displays prompt/output/total token counts and cost estimates in the conversation area, while syncing to the sidebar Context panel.
+
+### 5.6 Text Selection and Copy
+
+`ViewportSelection` (`extensions/viewport_selection.rb`) extends `RubyRich::Viewport`, supporting:
+
+- **Mouse selection**: Left-click drag to select text, highlighted with reverse color
+- **Right-click copy**: Copy selected text to system clipboard
+- **Multi-platform clipboard support**: Linux (wl-copy / xclip / xsel), macOS (pbcopy), Windows, with OSC 52 terminal protocol fallback
+
+### 5.7 Table Rendering Optimization
+
+`MarkdownTableAdapter` (`extensions/markdown_table_adapter.rb`) extends RubyRich's Markdown converter, enabling tables to adapt to terminal width: calculating natural column widths, proportionally compressing columns when exceeding terminal width, and auto-wrapping long text.
+
+---
+
+## VI. Composer (Input Area) — Operations
+
+### 6.1 Basic Operations
+
+- **Text input**: Single-line editor, `Shift+Enter` for newline
+- **History navigation**: Up/down arrows to browse message history
+- **Vim scrolling**: Type `/vim` to toggle, enabling `j`/`k` to scroll the conversation area in single-line mode
+- **Clear**: `Ctrl+C` first press interrupts current task, second press exits; `Esc` multi-layer cancel (see below)
+
+### 6.2 Slash Commands
+
+Built-in commands trigger a dropdown menu via `/`:
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear output and restart session |
+| `/config` | Open model configuration dialog |
+| `/undo` | Restore previous task state |
+| `/help` | Show help information |
+| `/exit` | Exit application |
+| `/model` | Switch LLM model |
+
+Skill slash commands are also dynamically registered in the Composer menu, with descriptions truncated to 50 characters.
+
+### 6.3 Esc Multi-Layer Cancel Stack
+
+Pressing `Esc` processes in priority order:
+
+1. Close any open dialog (if present)
+2. Close slash menu (if open)
+3. Interrupt running task
+4. Clear input field text (Composer native behavior)
+
+---
+
+## VII. Dialog System
+
+RichUI provides three dialog types, all running in blocking mode (calling `show_blocking_dialog`):
+
+### 7.1 Approval Dialog (ApprovalDialog)
+
+File: `components/dialogs/approval_dialog.rb`
+
+Security confirmation before tool execution, displaying:
+- **Tool name** + category badge (File/Shell/Network/Paid, different colors)
+- **Risk level**: Low (green), Medium (yellow), High (yellow), Critical (red), with `●○○○` style progress bar
+- **Tool info** and parameter details
+- Three action buttons: `Approve`, `Deny`, `Always allow` (fingerprint whitelist)
+
+Navigation: `←`/`→` or `h`/`l` to switch options, `Enter` to confirm, `Esc` to deny.
+
+### 7.2 Configuration Menu Dialog (ConfigMenuDialog)
+
+File: `components/dialogs/config_menu_dialog.rb`
+
+Opened by `/config` command, for model management:
+- Lists all configured models (showing API Key mask, type labels)
+- Actions: Switch model / Add new model / Edit current model / Delete model / Close
+- When adding a model, first select Provider (pre-configured vs custom), then fill in API Key, Model name, Base URL form
+- Connection test verification available after adding/editing
+
+Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` to select, `q`/`Esc` to cancel.
+
+### 7.3 Form Dialog (FormDialog)
+
+File: `components/dialogs/form_dialog.rb`
+
+General-purpose form input, used for model editing and similar scenarios:
+- Supports multiple fields (with labels, default values, placeholders, password masking)
+- Focused field shows `➜` marker
+- Navigation: `↑`/`↓`/`Tab`/`Shift+Tab` to switch fields, `Enter` to submit, `Esc` to cancel
+
+### 7.4 Model Switch Dialog
+
+Triggered by `/model` command, two-step operation:
+1. Select target model from the available model list
+2. Choose scope: current session only / save permanently
+
+---
+
+## VIII. Keyboard Shortcut Overview
+
+| Shortcut | Scope | Function |
+|----------|-------|----------|
+| `Ctrl+C` | Global (within 1s) | Interrupt current task |
+| `Ctrl+C` | Global (after 1s) | Exit program |
+| `Ctrl+M` | Global (within 2s) | Toggle permission mode (confirm_safes ↔ confirm_all) |
+| `Tab` | Global | Toggle permission mode + refocus Composer |
+| `F1` | Global | Sidebar → Work panel |
+| `F2` | Global | Sidebar → Tasks panel |
+| `F3` | Global | Sidebar → Auto mode |
+| `F4` | Global | Sidebar → Context panel |
+| `Esc` | Global | Multi-layer cancel (dialog→menu→interrupt→clear input) |
+| `Shift+Enter` | Composer | Newline |
+| `↑`/`↓` | Composer | History message navigation |
+| `j`/`k` | Composer (single-line mode) | Scroll conversation area |
+| `Ctrl+O` | Transcript | Expand/collapse thinking block |
+| Left-click drag | Transcript | Select text |
+| Right-click | Transcript | Copy selected text |
+
+---
+
+## IX. Auxiliary Modules
+
+| Module | File | Function |
+|--------|------|----------|
+| **ViewRenderer** | `view_renderer.rb` | Tool output formatting (`[OK]`/`[Error]`), parameter truncation, tool activity label generation, Diff stat parsing, thinking text extraction, API Key masking, config menu option building, model form validation |
+| **EntryTracker** | `entry_tracker.rb` | Lightweight ID tracker, maintains tool call stack (push/pop), ensures correct pairing of tool calls and results |
+| **LayoutAdapter** | `layout_adapter.rb` | Layout adapter, provides `clear_output` to clear conversation area |
+| **ProgressHandleAdapter** | `progress_handle_adapter.rb` | Wraps RubyRich progress handler, provides `update` / `finish` / `cancel` interface |
+| **BaseComponent** | `components/base_component.rb` | Component base class, provides shared rendering methods: `muted`/`colored`/`status_marker`/`truncate`/`theme` |
+| **TranscriptPlain** | `extensions/transcript_plain.rb` | Extends Transcript, supports `plain: true` marked plain text entries (for welcome banner, etc.) |
+| **MarkdownTableAdapter** | `extensions/markdown_table_adapter.rb` | Monkey patch extending Kramdown-to-RubyRich table conversion, implementing terminal-width-adaptive table wrapping |
+| **ViewportSelection** | `extensions/viewport_selection.rb` | Extends viewport, supports text selection and multi-platform clipboard copy |
+
+---
+
+## X. Key Rendering Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `STREAMING_MARKDOWN_THRESHOLD` | 240 chars | Triggers streaming rendering when exceeded |
+| `STREAMING_MARKDOWN_CHUNK_SIZE` | 6 chars/chunk | Streaming rendering chunk size |
+| `STREAMING_MARKDOWN_DELAY` | 0.03s | Streaming rendering interval |
+| Thinking streaming chunk size | 3 chars/chunk | Thinking content streaming display chunk size |
+| Thinking streaming delay | 0.008s | Thinking content streaming display interval |
+| `SKILL_DESC_MAX` | 50 chars | Skill description truncation length in menu |
+| Tool activity record limit | 12 entries | Max entries in sidebar Work panel |
+| Diff visible lines | 50 lines | Default max display lines for `show_diff` |
+| Tool label truncation | 40 chars | Truncation length for tool call parameter labels |
+
+---
+
+## XI. Source File Listing
+
+```
+lib/clacky/rich_ui/
+├── rich_ui_controller.rb            # Core controller (824 lines)
+├── view_renderer.rb                 # View rendering helper module (291 lines)
+├── entry_tracker.rb                 # Entry ID tracker
+├── layout_adapter.rb                # Layout adapter
+├── progress_handle_adapter.rb       # Progress handler adapter
+├── shell/
+│   └── rich_agent_shell.rb          # AgentShell in Rich mode
+├── components/
+│   ├── base_component.rb            # Base component module
+│   ├── sidebar.rb                   # Sidebar
+│   ├── sidebar_panels.rb            # Sidebar panels (Work/Tasks/Context)
+│   ├── status_view.rb               # Status view (bottom status bar)
+│   ├── thinking_live_view.rb        # Real-time thinking view
+│   └── dialogs/
+│       ├── approval_dialog.rb       # Approval dialog
+│       ├── form_dialog.rb           # Form dialog
+│       └── config_menu_dialog.rb    # Configuration menu dialog
+└── extensions/
+    ├── markdown_table_adapter.rb    # Markdown table adapter
+    ├── transcript_plain.rb          # Plain text transcript extension
+    └── viewport_selection.rb        # Viewport text selection extension
+```
+
+## XII. Lifecycle
+
+1. `RichUIController#initialize` — Initializes configuration, creates `RichAgentShell`, `LayoutAdapter`, `EntryTracker`, binds callbacks
+2. `initialize_and_show_banner` — Sets `running=true`, displays welcome banner or session history
+3. `start` → `start_input_loop` → `@shell.start` — Enters terminal event loop
+4. User submits input → `on_submit` callback → `@input_callback` → CLI → Agent
+5. Agent response → `show_assistant_message` (thinking streaming + Markdown rendering)
+6. Tool calls → `show_tool_call` / `show_tool_result` / `show_tool_error`
+7. Task complete → `show_complete`, updates status bar and sidebar
+8. `stop` — Exits event loop, optional screen clear