openclacky 0.9.5 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a50886ecfabfb60ea86a139a0180fc64803d1853d49aee14b201aa4e1d14a907
-  data.tar.gz: 7979255d8dc2113189a5934081a8b5cd24cce0e84aad9ab3deda97116924c6a5
+  metadata.gz: a499294341fb7b3fd0f4884ecc672705317c1f33d4ead1531ebdd34465a8f5f8
+  data.tar.gz: a2c023146c5ed2b91c0777e31266800ff933fd053bee146430c0587cc8fc1999
 SHA512:
-  metadata.gz: '0882ad06699e96e87581066d2be75755ccc0b82bd2bf1997fad7155f493733015c8abe5fb857391796157173c1408b9d011d6cc731b18123890cd33c2c9f34e4'
-  data.tar.gz: 78e98487a191ba8014fb1d6b84d518bd1949b3724e90ab49523919bbbf0a17cfd1596b00ddf7576727fe96cf5e2d6783a17855c9be940fd5d9f9b7ea6304ee96
+  metadata.gz: 32640a8ff88ebfe3c37f69c9362c6935a876515a30a9fbff14d6496af6dbc2ec3c0df227db4a62d362c80d44a117f63e5c0ce48dc96f4229d1a03c1761b01eae
+  data.tar.gz: 72ed3bf45504176b76904cbeb90bcf32e5606c65405deb4b26fa3e6923e1e977c99615f5221d27a318e7585c5831523770ddae97b23affc2306efc2ef00fa9e4

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.6] - 2026-03-18
+
+### Added
+- **Environment-aware context injection**: the agent now automatically detects your OS, desktop environment, and screen info and includes it in every session — so it can give OS-specific advice without you having to explain your setup
+- **File attachments via IM channels**: you can now send images and documents directly through Feishu or WeCom to the agent, which processes them just like files sent via the Web UI
+- **Unified file attachment pipeline for Web UI**: images and Office/PDF documents can now be attached in the web chat interface with automatic image compression before upload
+- **Skills can now be installed from local zip files**: `skill-add` now accepts a local file path (not just a URL), so you can install skills from a downloaded zip without hosting it anywhere
+- **Skill import bar in Web UI**: the Skills settings page now has an import bar where you can paste a URL or upload a local zip file directly — no terminal needed to install new skills
+- **`$SKILL_DIR` available in skill instructions**: skill files can now reference `$SKILL_DIR` to get the absolute path to their own directory, making it easy to reference supporting files with correct paths
+- **`product-help` built-in skill**: the agent can now answer questions about Clacky's own features, configuration, and usage through a dedicated built-in skill
+
+### Fixed
+- **PDF and Office files now appear in glob results**: file discovery tools no longer skip `.pdf`, `.docx`, and other document formats — they show up correctly in file listings
+- **Chat history visible after message compression**: sessions where all user messages were compressed no longer show a blank history — prior conversation is now correctly replayed
+- **Stale message reference in task history**: an internal bug (`@messages` vs `@history`) that could cause incorrect task history in compressed sessions is fixed
+- **File-only messages handled correctly in channel UI**: sending a file without text via IM channels no longer causes a display issue in the channel UI
+- **WeCom WebSocket client stability**: fixed async dispatch and frame acknowledgment in the WeCom WS client to reduce dropped messages and connection issues
+- **Session serializer variable fix**: corrected a stale variable reference in session replay that could cause errors when restoring sessions
+- **`web_fetch` compatibility improved**: better request headers make web page fetching more reliable across more sites
+- **Reasoning content preserved in API messages**: `reasoning_content` fields are no longer stripped from messages, fixing potential issues with reasoning-capable models
+
+### More
+- Markdown links in chat now open in a new tab
+- Removed public skill store tab from the Skills panel (store content is now integrated differently)
+- Reduce WebSocket ping log noise in HTTP server
+- Centralize message cleanup logic in `MessageHistory`
+
 ## [0.9.5] - 2026-03-17
 
 ### Added

data/lib/clacky/agent/llm_caller.rb

@@ -45,6 +45,17 @@ module Clacky
             @ui&.show_error("Network failed after #{max_retries} retries: #{e.message}")
             raise AgentError, "Network connection failed after #{max_retries} retries: #{e.message}"
           end
+        rescue RetryableError => e
+          @ui&.clear_progress
+          retries += 1
+          if retries <= max_retries
+            @ui&.show_warning("#{e.message} (#{retries}/#{max_retries})")
+            sleep retry_delay
+            retry
+          else
+            @ui&.show_error("LLM service unavailable after #{max_retries} retries. Please try again later.")
+            raise AgentError, "LLM service unavailable after #{max_retries} retries"
+          end
         ensure
           @ui&.clear_progress
         end

data/lib/clacky/agent/message_compressor_helper.rb

@@ -34,13 +34,11 @@ module Clacky
           true
         rescue Clacky::AgentInterrupted => e
           @ui&.log("Idle compression canceled: #{e.message}", level: :info)
-          @history.pop_while { |m| m[:system_injected] && !m.equal?(compression_message) }
-          @history.pop_last if @history.to_a.last&.equal?(compression_message)
+          @history.rollback_before(compression_message)
           false
         rescue => e
           @ui&.log("Idle compression failed: #{e.message}", level: :error)
-          @history.pop_while { |m| m[:system_injected] && !m.equal?(compression_message) }
-          @history.pop_last if @history.to_a.last&.equal?(compression_message)
+          @history.rollback_before(compression_message)
           false
         end
       end

data/lib/clacky/agent/session_serializer.rb

@@ -90,7 +90,8 @@ module Clacky
             active_task_id: @active_task_id || 0
           },
           config: {
-            models: @config.models,
+            # NOTE: api_key and other sensitive credentials are intentionally excluded
+            # to prevent leaking secrets into session files on disk.
             permission_mode: @config.permission_mode.to_s,
             enable_compression: @config.enable_compression,
             enable_prompt_caching: @config.enable_prompt_caching,
@@ -121,7 +122,7 @@ module Clacky
       #   created_at < before. Pass nil to get the most recent rounds.
       # @return [Hash] { has_more: Boolean } — whether older rounds exist beyond this page
       def replay_history(ui, limit: 20, before: nil)
-        # Split @messages into rounds, each starting at a real user message
+        # Split @history into rounds, each starting at a real user message
         rounds = []
         current_round = nil
 
@@ -155,62 +156,31 @@ module Clacky
           rounds = rounds.select { |r| r[:user_msg][:created_at] && r[:user_msg][:created_at] < before }
         end
 
+        # Fallback: when the conversation was compressed and no user messages remain in the
+        # kept slice, render the surviving assistant/tool messages directly so the user can
+        # still see the last visible state of the chat (e.g. compressed summary + recent work).
+        if rounds.empty?
+          visible = @history.to_a.reject { |m| m[:role].to_s == "system" || m[:system_injected] }
+          visible.each { |msg| _replay_single_message(msg, ui) }
+          return { has_more: false }
+        end
+
         has_more = rounds.size > limit
         # Take the most recent `limit` rounds
         page = rounds.last(limit)
 
         page.each do |round|
           msg = round[:user_msg]
-          display_text = extract_text_from_content(msg[:content])
-          # Extract image data URLs from multipart content (for history replay rendering)
-          images = extract_images_from_content(msg[:content])
-          # Emit user message with its timestamp for dedup on the frontend
-          ui.show_user_message(display_text, created_at: msg[:created_at], images: images)
+          raw_text = extract_text_from_content(msg[:content])
+          # Files are stored as system_injected messages (skipped below), not embedded in user text.
+          ui.show_user_message(raw_text, created_at: msg[:created_at])
 
           round[:events].each do |ev|
             # Skip system-injected messages (e.g. synthetic skill content, memory prompts)
             # — they are internal scaffolding and must not be shown to the user.
             next if ev[:system_injected]
 
-            case ev[:role].to_s
-            when "assistant"
-              # Text content
-              text = extract_text_from_content(ev[:content]).to_s.strip
-              ui.show_assistant_message(text) unless text.empty?
-
-              # Tool calls embedded in assistant message
-              Array(ev[:tool_calls]).each do |tc|
-                name     = tc[:name] || tc.dig(:function, :name) || ""
-                args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
-                args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
-
-                # Special handling: request_user_feedback question is shown as an
-                # assistant message (matching real-time behavior), not as a tool call.
-                if name == "request_user_feedback"
-                  question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
-                  ui.show_assistant_message(question) unless question.empty?
-                else
-                  ui.show_tool_call(name, args)
-                end
-              end
-
-              # Emit token usage stored on this message (for history replay display)
-              ui.show_token_usage(ev[:token_usage]) if ev[:token_usage]
-
-            when "user"
-              # Anthropic-format tool results (role: user, content: array of tool_result blocks)
-              next unless ev[:content].is_a?(Array)
-
-              ev[:content].each do |blk|
-                next unless blk.is_a?(Hash) && blk[:type] == "tool_result"
-
-                ui.show_tool_result(blk[:content].to_s)
-              end
-
-            when "tool"
-              # OpenAI-format tool result
-              ui.show_tool_result(ev[:content].to_s)
-            end
+            _replay_single_message(ev, ui)
           end
         end
 
@@ -219,6 +189,52 @@ module Clacky
 
       private
 
+      # Render a single non-user message into the UI.
+      # Used by both the normal round-based replay and the compressed-session fallback.
+      def _replay_single_message(msg, ui)
+        return if msg[:system_injected]
+
+        case msg[:role].to_s
+        when "assistant"
+          # Text content
+          text = extract_text_from_content(msg[:content]).to_s.strip
+          ui.show_assistant_message(text, files: []) unless text.empty?
+
+          # Tool calls embedded in assistant message
+          Array(msg[:tool_calls]).each do |tc|
+            name     = tc[:name] || tc.dig(:function, :name) || ""
+            args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
+            args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
+
+            # Special handling: request_user_feedback question is shown as an
+            # assistant message (matching real-time behavior), not as a tool call.
+            if name == "request_user_feedback"
+              question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
+              ui.show_assistant_message(question, files: []) unless question.empty?
+            else
+              ui.show_tool_call(name, args)
+            end
+          end
+
+          # Emit token usage stored on this message (for history replay display)
+          ui.show_token_usage(msg[:token_usage]) if msg[:token_usage]
+
+        when "user"
+          # Anthropic-format tool results (role: user, content: array of tool_result blocks)
+          return unless msg[:content].is_a?(Array)
+
+          msg[:content].each do |blk|
+            next unless blk.is_a?(Hash) && blk[:type] == "tool_result"
+
+            ui.show_tool_result(blk[:content].to_s)
+          end
+
+        when "tool"
+          # OpenAI-format tool result
+          ui.show_tool_result(msg[:content].to_s)
+        end
+      end
+
       # Replace the system message in @messages with a freshly built system prompt.
       # Called after restore_session so newly installed skills and any other
       # configuration changes since the session was saved take effect immediately.

data/lib/clacky/agent/time_machine.rb

@@ -147,7 +147,7 @@ module Clacky
         tasks = []
         (1..@current_task_id).to_a.reverse.take(limit).reverse.each do |task_id|
           # Find first user message for this task
-          first_user_msg = @messages.find do |msg|
+          first_user_msg = @history.to_a.find do |msg|
             msg[:task_id] == task_id && msg[:role] == "user"
           end
 

data/lib/clacky/agent.rb

@@ -6,6 +6,7 @@ require "tty-prompt"
 require "set"
 require_relative "utils/arguments_parser"
 require_relative "utils/file_processor"
+require_relative "utils/environment_detector"
 
 # Load all agent modules
 require_relative "agent/message_compressor"
@@ -151,7 +152,7 @@ module Clacky
       @name = new_name.to_s.strip
     end
 
-    def run(user_input, images: [], files: [])
+    def run(user_input, files: [])
       # Start new task for Time Machine
       task_id = start_new_task
 
@@ -178,11 +179,38 @@ module Clacky
       # Inject session context (date + model) if not yet present or date has changed
       inject_session_context_if_needed
 
-      # Format user message with images and files if provided
-      user_content = format_user_content(user_input, images, files)
+      # Split files into vision images and disk files; downgrade oversized images to disk
+      image_files, disk_files = partition_files(Array(files))
+      vision_urls, downgraded  = resolve_vision_images(image_files)
+      all_disk_files = disk_files + downgraded
+
+      # Format user message — text + inline vision images
+      user_content = format_user_content(user_input, vision_urls)
       @history.append({ role: "user", content: user_content, task_id: task_id, created_at: Time.now.to_f })
       @total_tasks += 1
 
+      # Inject disk file references as a system_injected message so:
+      #   - LLM sees the file info (system_injected is NOT stripped from to_api)
+      #   - replay_history skips it (next if ev[:system_injected]), keeping the user bubble clean
+      unless all_disk_files.empty?
+        file_prompt = all_disk_files.filter_map do |f|
+          path         = f[:path]         || f["path"]
+          name         = f[:name]         || f["name"]
+          type         = f[:type]         || f["type"]
+          preview_path = f[:preview_path] || f["preview_path"]
+          next unless path && name
+
+          lines = ["[File: #{name}]", "Type: #{type || "file"}"]
+          lines << "Original: #{path}"
+          lines << "Preview (Markdown): #{preview_path}" if preview_path
+          lines.join("\n")
+        end.join("\n\n")
+
+        unless file_prompt.empty?
+          @history.append({ role: "user", content: file_prompt, system_injected: true, task_id: task_id })
+        end
+      end
+
       # If the user typed a slash command targeting a skill with disable-model-invocation: true,
       # inject the skill content as a synthetic assistant message so the LLM can act on it.
       # Skills already in the system prompt (model_invocation_allowed?) are skipped.
@@ -218,7 +246,7 @@ module Clacky
             if @memory_updating && response[:content] && !response[:content].empty?
               @ui&.show_info(response[:content].strip)
             elsif response[:content] && !response[:content].empty?
-              @ui&.show_assistant_message(response[:content])
+              emit_assistant_message(response[:content])
             end
 
             # Show token usage after the assistant message so WebUI renders it below the bubble
@@ -243,7 +271,7 @@ module Clacky
           # Show assistant message if there's content before tool calls
           # During memory update phase, suppress text output (only tool calls matter)
           if response[:content] && !response[:content].empty? && !@memory_updating
-            @ui&.show_assistant_message(response[:content])
+            emit_assistant_message(response[:content])
           end
 
           # Show token usage after assistant message (or immediately if no message).
@@ -277,7 +305,7 @@ module Clacky
               next
             else
               # User just said "no" without feedback - stop and wait
-              @ui&.show_assistant_message("Tool execution was denied. Please give more instructions...")
+              @ui&.show_assistant_message("Tool execution was denied. Please give more instructions...", files: [])
               break
             end
           end
@@ -350,12 +378,9 @@ module Clacky
           handle_compression_response(response, compression_context)
           compression_handled = true
         ensure
-          # If interrupted or failed, remove the dangling compression message so it
-          # doesn't pollute future conversation turns.
-          unless compression_handled
-            @history.pop_while { |m| m[:system_injected] && !m.equal?(compression_message) }
-            @history.pop_last if @history.to_a.last&.equal?(compression_message)
-          end
+          # If interrupted or failed, roll back the speculative compression message
+          # so it doesn't pollute future conversation turns.
+          @history.rollback_before(compression_message) unless compression_handled
         end
         return nil
       end
@@ -565,7 +590,7 @@ module Clacky
           # Special handling for request_user_feedback: show directly as message
           if call[:name] == "request_user_feedback"
             if result.is_a?(Hash) && result[:message]
-              @ui&.show_assistant_message(result[:message])
+              @ui&.show_assistant_message(result[:message], files: [])
             end
 
             if @config.permission_mode == :auto_approve
@@ -756,13 +781,9 @@ module Clacky
       subagent.instance_variable_set(:@previous_total_tokens, @previous_total_tokens)
 
       # Deep clone history to avoid cross-contamination.
-      # to_api already strips trailing orphaned tool_calls; we use to_a here so the
-      # subagent gets the full internal list and its own to_api handles the strip on send.
+      # Dangling tool_calls (no tool_result yet) are cleaned up automatically by
+      # MessageHistory#append when the subagent appends its first user message.
       cloned_messages = deep_clone(@history.to_a)
-      # Strip pending tool_calls (no tool_result yet) — fork happens inside act(),
-      # before observe() has appended tool results. Anthropic rejects orphaned tool_use.
-      cloned_messages.pop if cloned_messages.last&.dig(:role) == "assistant" &&
-                             cloned_messages.last[:tool_calls]&.any?
       subagent.instance_variable_set(:@history, MessageHistory.new(cloned_messages))
 
       # Append system prompt suffix as user message (for cache reuse)
@@ -861,24 +882,85 @@ module Clacky
     # @param images [Array<String>] Array of image file paths or data: URLs
     # @param files [Array] Unused — kept for signature compatibility
     # @return [String|Array] String if no images, Array with content blocks otherwise
-    private def format_user_content(text, images, files = [])
-      images ||= []
+    # Partition files array into [image_files, non_image_files].
+    # Image files: have mime_type starting with "image/" OR have data_url present.
+    private def partition_files(files)
+      image_files = []
+      non_image_files = []
+      files.each do |f|
+        mime = f[:mime_type] || f["mime_type"] || ""
+        data_url = f[:data_url] || f["data_url"]
+        if mime.start_with?("image/") || data_url
+          image_files << f
+        else
+          non_image_files << f
+        end
+      end
+      [image_files, non_image_files]
+    end
+
+    # Resolve image files to vision data_urls.
+    # Files with data_url: use as-is (already compressed by frontend or adapter).
+    # Files with path: convert to data_url via FileProcessor.
+    # Oversized images (> MAX_IMAGE_BYTES) are downgraded to disk file refs.
+    # @return [Array<String>, Array<Hash>] [vision_urls, downgraded_disk_files]
+    private def resolve_vision_images(image_files)
+      require "base64"
+      max_bytes = Utils::FileProcessor::MAX_IMAGE_BYTES
+      vision_urls = []
+      downgraded  = []
+
+      image_files.each do |f|
+        name     = f[:name]     || f["name"]     || "image.jpg"
+        mime     = f[:mime_type] || f["mime_type"] || "image/jpeg"
+        data_url = f[:data_url]  || f["data_url"]
+        path     = f[:path]      || f["path"]
+
+        if data_url
+          # Strip header to check byte size: "data:image/jpeg;base64,<data>"
+          b64_data = data_url.split(",", 2).last.to_s
+          byte_size = (b64_data.bytesize * 3) / 4
+          if byte_size > max_bytes
+            # Downgrade: save to disk
+            raw      = Base64.decode64(b64_data)
+            file_ref = Utils::FileProcessor.save_image_to_disk(body: raw, mime_type: mime, filename: name)
+            downgraded << { name: name, path: file_ref.original_path, type: "image", mime_type: mime }
+          else
+            vision_urls << data_url
+          end
+        elsif path
+          begin
+            data_url_from_path = Utils::FileProcessor.image_path_to_data_url(path)
+            b64_data = data_url_from_path.split(",", 2).last.to_s
+            byte_size = (b64_data.bytesize * 3) / 4
+            if byte_size > max_bytes
+              raw      = Base64.decode64(b64_data)
+              file_ref = Utils::FileProcessor.save_image_to_disk(body: raw, mime_type: mime, filename: name)
+              downgraded << { name: name, path: file_ref.original_path, type: "image", mime_type: mime }
+            else
+              vision_urls << data_url_from_path
+            end
+          rescue => e
+            @ui&.log("Failed to load image #{name}: #{e.message}", level: :warn)
+          end
+        end
+      end
+
+      [vision_urls, downgraded]
+    end
+
+    # Build user message content for LLM.
+    # Returns plain String when no vision images; Array of content parts otherwise.
+    private def format_user_content(text, vision_urls)
+      vision_urls ||= []
 
-      return text if images.empty?
+      return text if vision_urls.empty?
 
       content = []
       content << { type: "text", text: text } unless text.nil? || text.empty?
-
-      images.each do |image|
-        # Accept both file paths and pre-encoded data: URLs (e.g. from Web UI)
-        image_url = if image.start_with?("data:")
-                      image
-                    else
-                      Utils::FileProcessor.image_path_to_data_url(image)
-                    end
-        content << { type: "image_url", image_url: { url: image_url } }
+      vision_urls.each do |url|
+        content << { type: "image_url", image_url: { url: url } }
       end
-
       content
     end
 
@@ -896,7 +978,16 @@ module Clacky
       # Skip if we already have a context for today
       return if @history.last_session_context_date == today
 
-      content = "[Session context: Today is #{Time.now.strftime('%Y-%m-%d, %A')}. Current model: #{current_model}]"
+      os      = Clacky::Utils::EnvironmentDetector.os_type
+      desktop = Clacky::Utils::EnvironmentDetector.desktop_path
+      parts   = [
+        "Today is #{Time.now.strftime('%Y-%m-%d, %A')}",
+        "Current model: #{current_model}",
+        os != :unknown ? "OS: #{Clacky::Utils::EnvironmentDetector.os_label}" : nil,
+        desktop ? "Desktop: #{desktop}" : nil
+      ].compact.join(". ")
+
+      content = "[Session context: #{parts}]"
       @history.append({
         role: "user",
         content: content,
@@ -906,6 +997,36 @@ module Clacky
       })
     end
 
+    # Parse markdown file:// links from assistant message content.
+    # Handles both regular links and inline images:
+    #   [Download report](file:///path/to/file.pdf)
+    #   ![chart](file:///path/to/chart.png)
+    #
+    # Returns { text: String, files: Array<{name:, path:, inline:}> }
+    # File links are stripped from the returned text.
+    private def parse_file_links(content)
+      return { text: content, files: [] } if content.nil? || content.empty?
+
+      files = []
+      text = content.gsub(/(!?)\[([^\]]*)\]\(file:\/\/([^)]+)\)/) do
+        inline = $1 == "!"
+        name   = $2.empty? ? File.basename($3) : $2
+        path   = File.expand_path($3)
+        Clacky::Logger.info("[parse_file_links] raw=#{$3.inspect} expanded=#{path.inspect} exist=#{File.exist?(path)}")
+        files << { name: name, path: path, inline: inline }
+        ""
+      end
+      { text: text.strip, files: files }
+    end
+
+    # Emit assistant message to UI, parsing any embedded file:// links first.
+    private def emit_assistant_message(content)
+      return if content.nil? || content.empty?
+
+      parsed = parse_file_links(content)
+      @ui&.show_assistant_message(parsed[:text], files: parsed[:files])
+    end
+
     # Track modified files for Time Machine snapshots
     # @param tool_name [String] Name of the tool that was executed
     # @param args [Hash] Arguments passed to the tool

data/lib/clacky/cli.rb

@@ -53,7 +53,8 @@ module Clacky
     option :attach, type: :string, aliases: "-a", desc: "Attach to session by number or keyword"
     option :json, type: :boolean, default: false, desc: "Output NDJSON to stdout (for scripting/piping)"
     option :message, type: :string, aliases: "-m", desc: "Run non-interactively with this message and exit"
-    option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (use with -m; can be specified multiple times)"
+    option :file,  type: :array, aliases: "-f", desc: "File path(s) to attach (use with -m; supports images and documents)"
+    option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (alias for --file, kept for compatibility)"
     option :agent, type: :string, default: "coding", desc: "Agent profile to use: coding, general, or any custom profile name (default: coding)"
     option :help, type: :boolean, aliases: "-h", desc: "Show this help message"
     def agent
@@ -111,7 +112,8 @@ module Clacky
       Dir.chdir(working_dir) if should_chdir
       begin
         if options[:message]
-          run_non_interactive(agent, options[:message], Array(options[:image]), agent_config, session_manager)
+          file_paths = Array(options[:file]) + Array(options[:image])
+          run_non_interactive(agent, options[:message], file_paths, agent_config, session_manager)
         elsif options[:json]
           run_agent_with_json(agent, working_dir, agent_config, session_manager, client, profile: agent_profile)
         else
@@ -446,20 +448,26 @@ module Clacky
       # Run agent non-interactively with a single message, then exit.
       # Forces auto_approve mode so no human confirmation is needed.
       # Output goes directly to stdout; exits with code 0 on success, 1 on error.
-      def run_non_interactive(agent, message, images, agent_config, session_manager)
+      def run_non_interactive(agent, message, file_paths, agent_config, session_manager)
         # Force auto-approve — no one is around to confirm anything
         agent_config.permission_mode = :auto_approve
 
-        # Validate image paths up-front so we fail fast with a clear message
-        images.each do |path|
-          raise ArgumentError, "Image file not found: #{path}" unless File.exist?(path)
+        # Validate paths up-front so we fail fast with a clear message
+        file_paths.each do |path|
+          raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+        end
+
+        # Convert file paths to file hashes — agent.run decides how to handle each
+        files = file_paths.map do |path|
+          mime = Utils::FileProcessor.detect_mime_type(path) rescue "application/octet-stream"
+          { name: File.basename(path), mime_type: mime, path: path }
         end
 
         # Wire up plain-text stdout UI so all agent output is visible
         plain_ui = Clacky::PlainUIController.new
         agent.instance_variable_set(:@ui, plain_ui)
 
-        agent.run(message, images: images)
+        agent.run(message, files: files)
         session_manager&.save(agent.to_session_data(status: :success))
         exit(0)
       rescue Clacky::AgentInterrupted
@@ -476,7 +484,7 @@ module Clacky
       #
       # Input protocol (one JSON per line on stdin):
       #   {"type":"message","content":"..."}          — run agent with this message
-      #   {"type":"message","content":"...","images":["path"]} — with images
+      #   {"type":"message","content":"...","files":[{"name":"x.jpg","mime_type":"image/jpeg","data_url":"data:..."}]} — with files
       #   {"type":"exit"}                             — graceful shutdown
       #   {"type":"confirmation","id":"conf_1","result":"yes"} — answer to request_confirmation
       #
@@ -522,8 +530,8 @@ module Clacky
               next
             end
 
-            images = input["images"] || []
-            run_json_task(agent, json_ui, session_manager) { agent.run(content, images: images) }
+            files = input["files"] || []
+            run_json_task(agent, json_ui, session_manager) { agent.run(content, files: files) }
           when "exit"
             break
           else
@@ -645,7 +653,7 @@ module Clacky
         end
 
         # Set up input handler
-        ui_controller.on_input do |input, images, display: nil|
+        ui_controller.on_input do |input, files, display: nil|
           # Handle commands
           case input.downcase.strip
           when "/config"
@@ -693,7 +701,7 @@ module Clacky
 
               # Run agent (Agent will call @ui methods directly)
               # Agent internally tracks total_tasks and total_cost
-              result = agent.run(input, images: images)
+              result = agent.run(input, files: files)
 
               # Save session after each task
               if session_manager

data/lib/clacky/client.rb

@@ -112,6 +112,7 @@ module Clacky
       response = anthropic_connection.post("v1/messages") { |r| r.body = body.to_json }
 
       raise_error(response) unless response.status == 200
+      check_html_response(response)
       MessageFormat::Anthropic.parse_response(JSON.parse(response.body))
     end
 
@@ -132,6 +133,7 @@ module Clacky
       response = openai_connection.post("chat/completions") { |r| r.body = body.to_json }
 
       raise_error(response) unless response.status == 200
+      check_html_response(response)
       MessageFormat::OpenAI.parse_response(JSON.parse(response.body))
     end
 
@@ -227,12 +229,20 @@ module Clacky
       when 401 then raise AgentError, "Invalid API key"
       when 403 then raise AgentError, "Access denied: #{error_message}"
       when 404 then raise AgentError, "API endpoint not found: #{error_message}"
-      when 429 then raise AgentError, "Rate limit exceeded"
-      when 500..599 then raise AgentError, "Server error (#{response.status}): #{error_message}"
+      when 429 then raise RetryableError, "Rate limit exceeded, please wait a moment"
+      when 500..599 then raise RetryableError, "LLM service temporarily unavailable (#{response.status}), retrying..."
       else raise AgentError, "Unexpected error (#{response.status}): #{error_message}"
       end
     end
 
+    # Raise a friendly error if the response body is HTML (e.g. gateway error page returned with 200)
+    def check_html_response(response)
+      body = response.body.to_s.lstrip
+      if body.start_with?("<!DOCTYPE", "<!doctype", "<html", "<HTML")
+        raise RetryableError, "LLM service temporarily unavailable (received HTML error page), retrying..."
+      end
+    end
+
     def extract_error_message(error_body, raw_body)
       if raw_body.is_a?(String) && raw_body.strip.start_with?("<!DOCTYPE", "<html")
         return "Invalid API endpoint or server error (received HTML instead of JSON)"

data/lib/clacky/default_agents/base_prompt.md

@@ -4,6 +4,7 @@
 - Break down complex tasks into manageable steps
 - **USE TOOLS to create/modify files** — don't just return content
 - Provide brief explanations after completing actions
+- When the user asks to send/download a file or you generate one for them, append `[filename](file://~/path/to/file)` at the end of your reply
 
 ## Tool Usage Rules