openclacky 1.5.20 → 1.5.21

data/lib/clacky/server/web_ui_controller.rb

@@ -29,7 +29,6 @@ module Clacky
 
         # Pending confirmation state: { id => ConditionVariable, result => value }
         @pending_confirmations = {}
-        @pending_feedback = nil
 
         # Channel subscribers: array of objects implementing UIInterface.
         # All emitted events are forwarded to each subscriber after WebSocket broadcast.
@@ -69,49 +68,68 @@ module Clacky
         end
       end
 
-      def deliver_feedback(answer, **options)
+      # Use the same contract as the CLI. The server owns the deadline;
+      # typing cancels automatic continuation but keeps the answer wait alive.
+      def request_feedback_with_countdown(seconds: 20)
+        pending = { id: @feedback_request_id || SecureRandom.uuid, cond: ConditionVariable.new,
+                    deadline_ms: (Time.now.to_f * 1000).to_i + seconds * 1000 }
+        pending[:seconds] = seconds
+        pending[:deadline] = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
         @mutex.synchronize do
-          pending = @pending_feedback
-          return false unless pending && !answer.strip.empty?
-          pending[:answer], pending[:resolution], pending[:options] = answer, "human", options
-          pending[:cond].signal
-          true
-        end
-      end
-
-      # The caller supplies a timeout for this wait; nil keeps manual feedback.
-      def wait_for_feedback(timeout_seconds:, question: nil, recommended_label: nil)
-        unless recommended_label && !timeout_seconds.nil?
-          yield
-          return
+          pending[:manual] = @feedback_permission_mode == :confirm_all
+          @pending_feedback = pending
         end
-        raise ArgumentError, "Invalid feedback timeout" unless timeout_seconds.is_a?(Integer) && timeout_seconds >= 0
-
-        pending = { id: SecureRandom.uuid, cond: ConditionVariable.new }
-        countdown = { request_id: pending[:id], question: question, recommended_label: recommended_label,
-                      deadline_ms: (Time.now.to_f * 1000).to_i + timeout_seconds * 1000,
-                      duration_seconds: timeout_seconds }
-        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
-        pending[:countdown] = countdown
-        @mutex.synchronize { @pending_feedback = pending }
-        yield
-        emit("feedback_countdown_started", **countdown)
+        emit("feedback_countdown", request_id: pending[:id], deadline_ms: pending[:manual] ? nil : pending[:deadline_ms])
         @mutex.synchronize do
-          until pending[:answer]
-            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            if remaining <= 0
-              pending.merge!(answer: recommended_label, resolution: "timeout")
+          until pending[:result]
+            remaining = pending[:deadline] - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if !pending[:manual] && remaining <= 0
+              pending[:result] = :timeout
             else
-              pending[:cond].wait(@mutex, remaining)
+              pending[:cond].wait(@mutex, pending[:manual] ? nil : remaining)
             end
           end
-          [pending[:answer], pending.fetch(:options, {})]
+          pending[:result]
         end
       ensure
-        if pending
-          @mutex.synchronize { @pending_feedback = nil }
-          emit("feedback_countdown_resolved", request_id: pending[:id],
-               resolution: pending[:resolution] || "cancelled", answer: pending[:answer])
+        cleared = @mutex.synchronize do
+          if pending && @pending_feedback.equal?(pending)
+            @pending_feedback = nil
+            true
+          end
+        end
+        if cleared
+          emit("feedback_countdown", request_id: pending[:id], resolved: true,
+               resolution: pending[:result] || :cancelled)
+        end
+      end
+
+      def update_permission_mode(mode)
+        countdown = @mutex.synchronize do
+          @feedback_permission_mode = mode.to_sym
+          pending = @pending_feedback
+          if pending && !pending[:result]
+            if mode.to_sym == :auto_approve && pending[:manual]
+              pending[:deadline] = Process.clock_gettime(Process::CLOCK_MONOTONIC) + pending[:seconds]
+              pending[:deadline_ms] = (Time.now.to_f * 1000).to_i + pending[:seconds] * 1000
+            end
+            pending[:manual] = mode.to_sym != :auto_approve
+            pending[:cond].signal
+            { request_id: pending[:id],
+              deadline_ms: pending[:manual] ? nil : pending[:deadline_ms] }
+          end
+        end
+        emit("feedback_countdown", **countdown) if countdown
+      end
+
+      def intervene_feedback(request_id)
+        @mutex.synchronize do
+          pending = @pending_feedback
+          return false unless pending && pending[:id] == request_id && !pending[:result]
+          pending[:result] = :intervened
+          pending[:cond].signal
+          emit("feedback_countdown", request_id: pending[:id], deadline_ms: nil)
+          true
         end
       end
 
@@ -176,7 +194,9 @@ module Clacky
           context   = args_data.is_a?(Hash) ? (args_data[:context] || args_data["context"]).to_s : ""
           first     = questions.first || {}
 
+          @feedback_request_id = Clacky::Tools::AskUser.fetch_key(args_data, :request_id)
           emit("request_feedback",
+               request_id: @feedback_request_id,
                question: first[:question].to_s,
                context: context,
                options: first[:options] || [],
@@ -383,8 +403,11 @@ module Clacky
       # The frontend's appendToolStdout will attach to the last visible .tool-item
       # even when _liveLastToolItem is null (after the tab re-loaded).
       def replay_live_state
-        countdown = @mutex.synchronize { @pending_feedback&.dig(:countdown) }
-        emit("feedback_countdown_started", **countdown) if countdown
+        countdown = @mutex.synchronize do
+          pending = @pending_feedback
+          pending ? { request_id: pending[:id], deadline_ms: pending[:manual] ? nil : pending[:deadline_ms] } : { resolved: true }
+        end
+        emit("feedback_countdown", **countdown)
         return unless @live_progress_state
 
         # Replay complete progress state (not just message).

data/lib/clacky/session_manager.rb

@@ -216,7 +216,7 @@ module Clacky
     def all_sessions(current_dir: nil, limit: nil)
       sessions = Dir.glob(File.join(@sessions_dir, "*.json")).filter_map do |filepath|
         load_session_file(filepath)
-      end.sort_by { |s| s[:updated_at] || s[:created_at] || "" }.reverse
+      end.sort_by { |s| [s[:updated_at] || s[:created_at] || "", s[:session_id].to_s] }.reverse
 
       if current_dir
         current_sessions = sessions.select { |s| s[:working_dir] == current_dir }
@@ -436,6 +436,12 @@ module Clacky
       Clacky::Tools::TrashManager.permanent_delete_trash_session(session_id, sessions_dir: @sessions_dir)
     end
 
+    # Permanently delete exactly these sessions from the trash. Returns the count deleted.
+    def permanent_delete_trash_sessions(session_ids)
+      require_relative "tools/trash_manager"
+      Clacky::Tools::TrashManager.empty_trash_sessions(sessions_dir: @sessions_dir, ids: session_ids)
+    end
+
     # Keep file-trash on the same rolling window as sessions-trash.
     def cleanup_file_trash(days: 8)
       require_relative "tools/trash_manager"

data/lib/clacky/skill.rb

@@ -319,7 +319,7 @@ module Clacky
           > should either:
           >
           > 1. Ask the user to start the server in another terminal: `clacky server`
-          >    (then retry — the CLI auto-detects it via `/tmp/clacky-master-*.pid`), or
+          >    (then retry — the CLI auto-detects it via `clacky-master-*.pid` in the configured PID directory), or
           > 2. If the task can be completed without the server API, skip those steps
           >    and tell the user which parts require the server.
           >

data/lib/clacky/tools/ask_user.rb

@@ -110,7 +110,7 @@ module Clacky
         recommended = recommended.to_i if recommended.is_a?(Numeric) || recommended.to_s =~ /\A-?\d+\z/
         recommended = nil unless recommended.is_a?(Integer) && recommended >= 0 && recommended < options.size
 
-        {
+        normalized = {
           question: text,
           description: fetch_key(item, :description).to_s.strip,
           options: options,
@@ -119,6 +119,9 @@ module Clacky
           allow_free_text: options.empty? || truthy?(fetch_key(item, :allow_free_text)),
           recommended: recommended
         }
+        metadata = fetch_key(item, :metadata)
+        normalized[:metadata] = metadata if metadata.is_a?(Hash)
+        normalized
       end
 
       def self.fetch_key(hash, key)

data/lib/clacky/tools/base.rb

@@ -14,8 +14,9 @@ module Clacky
         attr_accessor :receives_tool_call_id
       end
 
-      # Host agent, injected at registration for extension tools so they can
-      # reach its public API (fan_out_labeled, fork_subagent, skill_loader).
+      # Host agent, injected at registration for extension tools and for built-ins
+      # that need its public API (config, fan_out_labeled, fork_subagent,
+      # skill_loader).
       attr_accessor :agent
 
       def name

data/lib/clacky/tools/browser.rb

@@ -543,12 +543,21 @@ module Clacky
         # Save original (full-resolution) PNG to disk before any downscaling
         original_path = save_screenshot_to_disk(image_block["data"], suffix: "original")
 
+        config = screenshot_config
+        limit = config["screenshot_max_base64_bytes"]
+        max_base64_bytes = limit.is_a?(Integer) && limit.positive? ? limit : SCREENSHOT_MAX_BASE64_BYTES
         image_data = png_downscale_base64(image_block["data"], SCREENSHOT_MAX_WIDTH)
+        if image_data.bytesize > max_base64_bytes
+          image_data = Clacky::Utils::FileProcessor.quantize_png_base64(image_data)
+        end
 
-        if image_data.bytesize > SCREENSHOT_MAX_BASE64_BYTES
+        if image_data.bytesize > max_base64_bytes
           size_kb = image_data.bytesize / 1024
+          saved   = original_path ? " The full-resolution file is saved at #{original_path}." : ""
           return { action: "screenshot", success: false, profile: "user",
-                   output: "Screenshot too large after resize (#{size_kb}KB). Use action=snapshot instead." }
+                   original_path: original_path,
+                   output: "Screenshot still too large after compression (#{size_kb}KB).#{saved} " \
+                           "Use action=snapshot instead." }
         end
 
         # Save compressed (800px) PNG for AI reference
@@ -560,6 +569,13 @@ module Clacky
           output: "Screenshot captured." }
       end
 
+      private def screenshot_config
+        config = YAMLCompat.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol])
+        config.is_a?(Hash) ? config : {}
+      rescue StandardError
+        {}
+      end
+
       private def png_downscale_base64(b64, max_width)
         Clacky::Utils::FileProcessor.downscale_image_base64(
           b64, "image/png", max_width: max_width

data/lib/clacky/tools/file_reader.rb

@@ -46,7 +46,7 @@ module Clacky
       MAX_CONTENT_CHARS = 60_000
 
       # Maximum characters per line (prevent single huge lines from bloating tokens)
-      MAX_LINE_CHARS = 1000
+      MAX_LINE_CHARS = 8_000
 
       def execute(path:, max_lines: 1000, start_line: nil, end_line: nil, working_dir: nil, image_max_width: nil)
         # Expand path relative to working_dir when provided

data/lib/clacky/tools/terminal/session_manager.rb

@@ -43,7 +43,9 @@ module Clacky
           :read_offset,     # Integer, bytes already returned by previous read calls
           :mutex,           # per-session mutex for PTY writes
           :resource_group,   # Optional cgroup for task limits and OOM attribution
+          :script_paths,    # Internal script paths for cleanup and output masking
           :shell_name,      # "zsh" | "bash" | "sh" — informs marker syntax & rc reload
+          :echo_head,       # String, last `{ CMD` line written; strips its wrapped echo
           keyword_init: true
         )
 
@@ -77,6 +79,7 @@ module Clacky
                 read_offset: 0,
                 mutex: Mutex.new,
                 resource_group: resource_group,
+                script_paths: [],
                 shell_name: shell_name
               )
               @sessions[session.id] = session
@@ -116,7 +119,21 @@ module Clacky
           # Forget a session (after it has been killed/exited).  Does NOT kill
           # the process — callers should kill first.
           def forget(id)
-            @mutex.synchronize { @sessions.delete(id) }
+            session = @mutex.synchronize { @sessions.delete(id) }
+            cleanup_scripts(session) if session
+          end
+
+          # Cleanup must never replace the command's result with an unlink error.
+          def cleanup_scripts(session)
+            # The reader may clean up before buffered output is packaged.
+            # Preserve paths so error messages can still mask internal filenames.
+            Array(session.script_paths).each do |path|
+              begin
+                File.unlink(path)
+              rescue SystemCallError
+                # Best effort; retain the path for a later cleanup attempt.
+              end
+            end
           end
 
           # Refresh status of one session in-place (mutex-held).
@@ -188,6 +205,7 @@ module Clacky
               s.log_io&.close rescue nil
               s.writer&.close rescue nil
               s.reader&.close rescue nil
+              cleanup_scripts(s)
             end
           end
 

data/lib/clacky/tools/terminal.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "pty"
+require "tempfile"
+require "shellwords"
 require "securerandom"
 require "fileutils"
 require_relative "base"
@@ -73,9 +75,6 @@ module Clacky
           {session_id, input:"pw\n"}      reply to prompt / poll (input:"")
           {session_id, kill:true}         stop
 
-        Single-line only. For multi-line scripts (heredoc, loops, multi-statement blocks)
-        write a file first, then run it: write(path:"/tmp/run.sh", content:...) → terminal(command:"bash /tmp/run.sh").
-
         Response: exit_code = done; session_id = running (state: waiting/background/timeout).
         If output exceeds the limit, `output` is truncated and `full_output_file` points
         at a file on disk — use terminal(command: "grep ... <path>") to search it.
@@ -133,6 +132,7 @@ module Clacky
       BACKGROUND_COLLECT_SECONDS = 2
       # Sentinel: when passed as idle_ms, disables idle early-return.
       DISABLED_IDLE_MS = 10_000_000
+      PTY_COLS = 120
       # Gap between log-file polls while waiting for a command's end marker.
       MARKER_POLL_SECONDS = 0.05
       # A freshly spawned login shell prints its banner asynchronously; wait
@@ -244,17 +244,6 @@ module Clacky
 
         # Start a new command
         if command && !command.to_s.strip.empty?
-          if multiline_command?(command)
-            return {
-              error: "Multi-line commands are unreliable in our PTY shell " \
-                     "(heredocs / unclosed quotes / multi-line blocks can hang the session).",
-              hint: "Write the script to a file first, then execute it. " \
-                    "Example: 1) write(path: \"/tmp/run.sh\", content: \"...\")  " \
-                    "2) terminal(command: \"bash /tmp/run.sh\")",
-              multiline_blocked: true
-            }
-          end
-
           return do_start(command.to_s, cwd: cwd, env: env, timeout: timeout,
                           idle_ms: idle_ms, background: background ? true : false,
                           on_output: on_output)
@@ -402,6 +391,43 @@ module Clacky
         )
       end
 
+      SCRIPT_DIR = "/tmp/.clacky"
+      private def prepare_execution_command(session, command)
+        return command unless multiline_command?(command)
+
+        prepare_multiline_command(session, command)
+      end
+
+      # Keep script contents out of the interactive PTY input parser.
+      private def prepare_multiline_command(session, command)
+        session.script_paths.delete_if { |path| !File.exist?(path) }
+
+        script_dir = File.join(SCRIPT_DIR, session.id.to_s)
+        [SCRIPT_DIR, script_dir].each do |path|
+          FileUtils.mkdir_p(path, mode: 0700)
+          directory = File.lstat(path)
+          unless directory.directory? && directory.uid == Process.uid && (directory.mode & 0077).zero?
+            raise IOError, "#{path} must be a private directory owned by the current user"
+          end
+        end
+
+        file = Tempfile.create(["script-", ".sh"], script_dir)
+        session.script_paths << file.path
+        begin
+          file.write(command)
+          file.write("\n") unless command.end_with?("\n")
+        ensure
+          file.close
+        end
+        "( . #{Shellwords.escape(file.path)} )"
+      end
+
+      private def hide_script_paths(session, output)
+        Array(session.script_paths).reduce(output) do |text, path|
+          text.gsub(/#{Regexp.escape(path)}(?:: ?)?/, "")
+        end
+      end
+
       # ---------------------------------------------------------------------
       # 2) Continue / poll an existing session
       # ---------------------------------------------------------------------
@@ -475,11 +501,12 @@ module Clacky
         raw = read_log_slice(session.log_file, start_offset, new_offset)
         cleaned = OutputCleaner.clean(raw)
         cleaned = cleaned.sub(session.marker_regex, "").rstrip if session.marker_regex
-        cleaned = strip_command_echo(cleaned, marker_token: session.marker_token)
+        cleaned = strip_command_echo(cleaned, marker_token: session.marker_token, echo_head: session.echo_head)
         # Per-line cap first: one minified JSON blob shouldn't blow the
         # whole 4 KB budget. MUST run before overflow spill so the file
         # on disk also has the long lines shortened (otherwise grep-ing
         # the spill file returns thousand-char lines the LLM chokes on).
+        cleaned = hide_script_paths(session, cleaned)
         cleaned = truncate_long_lines(cleaned)
         truncated = false
         overflow_file = nil
@@ -516,6 +543,7 @@ module Clacky
 
         case state
         when :matched, :eof
+          SessionManager.cleanup_scripts(session)
           exit_code = code || session.exit_code
           if persistent && state == :matched && session_healthy?(session)
             # Command finished cleanly — return the shell to the pool so
@@ -611,7 +639,7 @@ module Clacky
       #     safe: the real completion marker was already removed via
       #     session.marker_regex above, so any surviving occurrence of
       #     __CLACKY_DONE_<token>_ is by definition an echoed wrapper.
-      private def strip_command_echo(text, marker_token: nil)
+      private def strip_command_echo(text, marker_token: nil, echo_head: nil)
         return text if text.nil? || text.empty?
 
         # Pass 0: strip the hooks prefix echo if `stty -echo` failed and
@@ -641,6 +669,16 @@ module Clacky
           text = text.sub(/\A\{[^\n]*\n/, "")
         end
 
+        # Pass 1b: a wrapped `{ CMD` echo leaves its last screen row as a bare command suffix above the tail.
+        if echo_head && echo_head.bytesize > PTY_COLS
+          lines = text.lines
+          text = lines.reject.with_index do |ln, i|
+            body = ln.chomp
+            !body.empty? && body.size < echo_head.size && echo_head.end_with?(body) &&
+              lines[i + 1].to_s.match?(/\A\}[^\n;]*; *__clacky_ec=\$\?/)
+          end.join
+        end
+
         # Pass 2: token-aware global strip — remove any leftover wrapper
         # echo fragment, wherever it sits. Requires the session token so
         # we never touch unrelated user output that happens to mention
@@ -881,7 +919,7 @@ module Clacky
         end
 
         begin
-          writer.winsize = [40, 120]
+          writer.winsize = [40, PTY_COLS]
         rescue StandardError
           # unsupported on some platforms
         end
@@ -1054,8 +1092,15 @@ module Clacky
         # non-WSL hosts (and on WSL when not invoking Windows binaries)
         # keep their PTY stdin and continue to behave as before.
         stdin_redirect = exe_needs_stdin_isolation?(command) ? " </dev/null" : ""
+        # Inspect the original command before replacing multiline input with a script.
+        # Internal shell setup must execute inline to update the session itself.
+        command = prepare_execution_command(session, command) if with_hooks
         line   = %Q|#{hooks_line}{ #{command}\n}#{stdin_redirect}; __clacky_ec=$?; printf "\n__CLACKY_DONE_#{token}_%s__\n" "$__clacky_ec"\n|
+        session.echo_head = "{ #{command}".lines.last.chomp
         session.mutex.synchronize { session.writer.write(line) }
+      rescue StandardError
+        cleanup_session(session)
+        raise
       end
 
       # True when the command should run with stdin redirected from
@@ -1277,7 +1322,7 @@ module Clacky
           cleaned = OutputCleaner.clean(buffered)
           # Strip any wrapper echo that still slipped through (e.g. when a
           # session is reused and ZLE re-echoes our wrapper mid-stream).
-          cleaned = strip_command_echo(cleaned, marker_token: session.marker_token)
+          cleaned = strip_command_echo(cleaned, marker_token: session.marker_token, echo_head: session.echo_head)
           # Belt-and-braces: drop any line that still carries our internal
           # tokens.
           cleaned = cleaned.lines.reject do |ln|
@@ -1292,7 +1337,7 @@ module Clacky
           # doesn't produce a wall of whitespace in the streaming UI.
           cleaned = cleaned.gsub(/\n{3,}/, "\n\n")
           cleaned = cleaned.lstrip if cleaned.match?(/\A\n+\z/)
-          on_output.call(cleaned) unless cleaned.empty? || cleaned.match?(/\A\s*\z/)
+          on_output.call(hide_script_paths(session, cleaned)) unless cleaned.empty? || cleaned.match?(/\A\s*\z/)
         rescue StandardError
           # Streaming is best-effort — never let a UI bug abort the command.
         end
@@ -1394,10 +1439,7 @@ module Clacky
 
       # True when `command` spans multiple lines. Trailing newlines are
       # ignored — a single-line command terminated with "\n" is still
-      # single-line. Multi-line commands frequently hang the persistent
-      # PTY shell (incomplete heredoc, unclosed quote, multi-line block
-      # without closer) — the agent should write a script file and
-      # invoke it instead.
+      # single-line. Multi-line input is sourced in a subshell.
       private def multiline_command?(command)
         return false if command.nil?
         command.to_s.sub(/\n+\z/, "").include?("\n")

data/lib/clacky/tools/trash_manager.rb

@@ -490,9 +490,10 @@ module Clacky
         true
       end
 
-      # Permanently delete all sessions in the trash, or only those older than
-      # :days days. Returns the count of permanently deleted sessions.
-      def self.empty_trash_sessions(sessions_dir:, days: nil)
+      # Permanently delete all sessions in the trash, only those older than
+      # :days days, or only the sessions whose full id is in :ids.
+      # Returns the count of permanently deleted sessions.
+      def self.empty_trash_sessions(sessions_dir:, days: nil, ids: nil)
         trash_dir = Clacky::TrashDirectory.sessions_trash_dir
         return 0 unless Dir.exist?(trash_dir)
 
@@ -503,6 +504,7 @@ module Clacky
         Dir.glob(File.join(trash_dir, "*.json")).each do |filepath|
           session = sm.send(:load_session_file, filepath)
           next unless session
+          next if ids && !ids.include?(session[:session_id])
 
           if cutoff
             trash_time = session[:deleted_at] || session[:updated_at]

data/lib/clacky/tools/web_fetch.rb

@@ -5,6 +5,7 @@ require "uri"
 require "tmpdir"
 require "fileutils"
 require_relative "../utils/encoding"
+require_relative "../deepseek_web_tools"
 
 module Clacky
   module Tools
@@ -39,30 +40,88 @@ module Clacky
           return { error: "Invalid URL: #{e.message}" }
         end
 
-        begin
-          # Fetch the web page
-          response = fetch_url(uri)
-
-          # Extract content and force UTF-8 encoding at the source
-          content = Clacky::Utils::Encoding.to_utf8(response.body)
-          content_type = response["content-type"] || ""
-
-          # Parse HTML if it's an HTML page
-          if content_type.include?("text/html")
-            result = parse_html(content, max_length, url)
-            result[:url] = url
-            result[:content_type] = content_type
-            result[:status_code] = response.code.to_i
-            result[:error] = nil
-            result
-          else
-            # For non-HTML content, return raw text
-            result = handle_raw_content(content, max_length, url, content_type, response.code.to_i)
-            result
+        deepseek_error = nil
+        if deepseek_fetch_selected?
+          begin
+            return fetch_via_deepseek(url, max_length)
+          rescue StandardError => e
+            # A paid upstream failure must not cost the user the page, so keep
+            # going with the local scraper. The cooldown stops the next fetch
+            # from paying the same timeout.
+            deepseek_error = e
+            Clacky::DeepSeekWebTools.mark_unavailable!
           end
-        rescue StandardError => e
-          { error: "Failed to fetch URL: #{e.message}" }
         end
+
+        result = fetch_locally(uri, url, max_length)
+        if deepseek_error && result[:error]
+          result[:error] = "#{result[:error]} (DeepSeek: #{deepseek_error.message})"
+        end
+        result
+      end
+
+      private def fetch_locally(uri, url, max_length)
+        response = fetch_url(uri)
+
+        content = Clacky::Utils::Encoding.to_utf8(response.body)
+        content_type = response["content-type"] || ""
+
+        if content_type.include?("text/html")
+          result = parse_html(content, max_length, url)
+          result[:url] = url
+          result[:content_type] = content_type
+          result[:status_code] = response.code.to_i
+          result[:error] = nil
+          result
+        else
+          handle_raw_content(content, max_length, url, content_type, response.code.to_i)
+        end
+      rescue StandardError => e
+        { error: "Failed to fetch URL: #{e.message}" }
+      end
+
+      # DeepSeek renders pages to clean Markdown, which covers JS-heavy sites the
+      # local scraper cannot read. Runs only when the user picks it as the search
+      # provider; #execute falls back to the local scraper when it raises.
+      private def fetch_via_deepseek(url, max_length)
+        config = agent.config
+        key = config.deepseek_web_key
+        data = Clacky::DeepSeekWebTools.fetch(
+          url: url,
+          api_key: key,
+          base_url: config.deepseek_web_base_url(key)
+        )
+
+        text = data[:content].to_s
+        truncated = text.length > max_length
+        temp_file = nil
+        if truncated
+          temp_dir = Dir.mktmpdir
+          safe_name = extract_domain(url).gsub(/[^\w\-.]/, '_')[0...50]
+          timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+          temp_file = File.join(temp_dir, "#{safe_name}_#{timestamp}.md")
+          File.write(temp_file, text)
+        end
+
+        {
+          url: url,
+          title: data[:title].to_s.strip,
+          content_type: "text/markdown",
+          status_code: 200,
+          content: text[0, max_length],
+          truncated: truncated,
+          temp_file: temp_file,
+          error: nil
+        }
+      end
+
+      private def deepseek_fetch_selected?
+        return false unless agent
+        return false if Clacky::DeepSeekWebTools.cooling_down?
+
+        agent.config.deepseek_web_ready?
+      rescue StandardError
+        false
       end
 
       def handle_raw_content(content, max_length, url, content_type, status_code)