openclacky 1.5.12 → 1.5.13

data/lib/clacky/openai_responses_stream_aggregator.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Clacky
+  # Reassembles an OpenAI Responses API event stream into the non-streaming
+  # response shape that MessageFormat::OpenAIResponses.parse_response consumes,
+  # while invoking on_chunk(input_tokens:, output_tokens:) for progress updates.
+  #
+  # The Responses API uses typed SSE events rather than the Chat Completions
+  # delta-based format. Key event types:
+  #
+  #   response.created                  -> response object created
+  #   response.output_item.added        -> new output item (message or function_call)
+  #   response.output_text.delta        -> text content delta
+  #   response.output_text.done         -> text content complete
+  #   response.reasoning_text.delta     -> reasoning content delta (OpenAI official / DeepSeek)
+  #   response.function_call_arguments.delta -> tool call argument delta
+  #   response.output_item.done         -> output item complete
+  #   response.completed                -> final event with full response + usage
+  #   response.done                     -> terminal event (OpenAI official API)
+  #   response.incomplete               -> response ended prematurely
+  #
+  # Unlike Chat Completions, there is no "[DONE]" sentinel; the stream ends
+  # with a "response.completed" / "response.done" (or "response.incomplete") event.
+  class OpenAIResponsesStreamAggregator
+    def initialize(on_chunk: nil)
+      @on_chunk = on_chunk
+      @text = +""
+      @reasoning_text = +""
+      @function_calls = {}   # call_id -> { name:, arguments: }
+      @call_id_by_item_id = {} # item_id -> call_id (for delta routing)
+      @usage = nil
+      @status = nil
+      @incomplete_details = nil
+      @last_input_tokens = 0
+      @last_output_tokens = 0
+      @parse_failures = 0
+      @frames_seen = 0
+      @bytes_seen = 0
+    end
+
+    attr_reader :parse_failures, :frames_seen, :bytes_seen
+
+    def saw_done?
+      !@status.nil?
+    end
+
+    def handle(data_str)
+      @bytes_seen += data_str.bytesize
+      @frames_seen += 1
+      data = parse_or_nil(data_str)
+      return unless data
+
+      event_type = data["type"]
+
+      case event_type
+      when "response.output_text.delta"
+        @text << data["delta"].to_s
+        emit_estimate_progress
+      # OpenAI's official API emits response.reasoning_text.delta; keep
+      # response.reasoning.delta as a tolerant alias for providers that
+      # rename it.
+      when "response.reasoning_text.delta", "response.reasoning.delta"
+        @reasoning_text << data["delta"].to_s
+      when "response.output_item.added"
+        handle_item_added(data)
+      when "response.function_call_arguments.delta"
+        handle_function_call_delta(data)
+      when "response.output_item.done"
+        handle_item_done(data)
+      when "response.completed", "response.done"
+        # OpenAI's official API sends response.completed followed by
+        # response.done as the terminal event; DeepSeek sends only
+        # response.completed. Either one marks a successful end.
+        @status = "completed"
+        response = data["response"]
+        @usage ||= response["usage"] if response && response["usage"]
+        # Also sync output items from the final response if our incremental
+        # tracking missed anything (e.g. provider sent complete items only).
+        sync_from_final_output(response["output"]) if response && response["output"]
+        emit_usage_progress(@usage) if @usage
+      when "response.incomplete"
+        @status = "incomplete"
+        # Preserve incomplete_details (e.g. reason: "max_output_tokens" vs
+        # "content_filter") so finish_reason mapping can distinguish a token
+        # limit from a safety-filtered response.
+        response = data["response"]
+        @incomplete_details = response["incomplete_details"] if response.is_a?(Hash) && response["incomplete_details"]
+      when "response.created", "response.in_progress"
+        # Informational events, no action needed
+      end
+    end
+
+    # Render into the non-streaming Responses API response shape
+    # so MessageFormat::OpenAIResponses.parse_response works unchanged.
+    def to_h
+      output = []
+
+      # Message item with text content
+      unless @text.empty?
+        output << {
+          "type"    => "message",
+          "role"    => "assistant",
+          "content" => [{ "type" => "output_text", "text" => @text.to_s }]
+        }
+      end
+
+      # Reasoning item. Both providers stream reasoning via
+      # response.reasoning(_text).delta; emit it as a top-level "reasoning"
+      # item (DeepSeek shape) so MessageFormat::OpenAIResponses#extract_reasoning
+      # can consume it. Without this the streaming path silently drops
+      # reasoning content while the non-streaming path keeps it.
+      unless @reasoning_text.empty?
+        output << {
+          "type" => "reasoning",
+          "content" => [{ "type" => "reasoning_text", "text" => @reasoning_text.to_s }]
+        }
+      end
+
+      # Function call items
+      @function_calls.each_value do |fc|
+        output << {
+          "type"      => "function_call",
+          "call_id"   => fc[:call_id],
+          "name"      => fc[:name],
+          "arguments" => fc[:arguments].to_s
+        }
+      end
+
+      result = {
+        "output" => output,
+        "status" => @status || "completed",
+        "usage"  => @usage || {}
+      }
+      result["incomplete_details"] = @incomplete_details if @incomplete_details
+      result
+    end
+
+    private def handle_item_added(data)
+      item = data["item"]
+      return unless item
+
+      if item["type"] == "function_call"
+        call_id = item["call_id"]
+        item_id = item["id"]
+        @call_id_by_item_id[item_id] = call_id if item_id
+        @function_calls[call_id] = {
+          call_id:    call_id,
+          name:       item["name"],
+          arguments:  +""
+        }
+      end
+    end
+
+    private def handle_function_call_delta(data)
+      # The delta event carries item_id to identify which function call
+      # the arguments belong to. Map it to the call_id we registered in
+      # handle_item_added. Fall back to the most recent call if mapping fails.
+      item_id = data["item_id"]
+      call_id = @call_id_by_item_id[item_id] || @function_calls.keys.last
+
+      return unless call_id && @function_calls[call_id]
+
+      @function_calls[call_id][:arguments] << data["delta"].to_s
+    end
+
+    private def handle_item_done(data)
+      item = data["item"]
+      return unless item
+
+      if item["type"] == "function_call"
+        call_id = item["call_id"]
+        fc = @function_calls[call_id]
+        # Use the complete arguments from the done event if available -
+        # more reliable than accumulated deltas.
+        if fc && item["arguments"]
+          fc[:arguments] = item["arguments"]
+        end
+      end
+    end
+
+    private def sync_from_final_output(output)
+      return unless output.is_a?(Array)
+
+      # Sync per-item: only backfill what incremental tracking missed.
+      # A provider may send complete message items but only deltas for
+      # function calls (or vice versa), so don't require both to be empty.
+      output.each do |item|
+        case item["type"]
+        when "message"
+          content = item["content"]
+          next unless content.is_a?(Array)
+
+          content.each do |block|
+            case block["type"]
+            when "output_text"
+              @text << block["text"].to_s if @text.empty?
+            when "reasoning"
+              backfill_reasoning(block["content"], block["summary"])
+            end
+          end
+        when "reasoning"
+          backfill_reasoning(item["content"], item["summary"])
+        when "function_call"
+          next if @function_calls.key?(item["call_id"])
+          @function_calls[item["call_id"]] = {
+            call_id:    item["call_id"],
+            name:       item["name"],
+            arguments:  item["arguments"].to_s
+          }
+        end
+      end
+    end
+
+    # Backfill @reasoning_text from the final response snapshot when no
+    # reasoning delta was seen. Handles both item shapes: OpenAI's official
+    # reasoning block inside the message item, and DeepSeek's top-level
+    # reasoning item. Prefers full reasoning text; falls back to the summary
+    # (mirrors MessageFormat::OpenAIResponses#extract_reasoning).
+    private def backfill_reasoning(content_blocks, summary_blocks = nil)
+      return unless @reasoning_text.empty?
+
+      return if append_typed_blocks(content_blocks, "reasoning_text")
+
+      append_typed_blocks(content_blocks, "summary_text") || append_typed_blocks(summary_blocks, "summary_text")
+    end
+
+    # Append every block of the given type to @reasoning_text.
+    # Returns true when at least one block matched.
+    private def append_typed_blocks(blocks, type)
+      return false unless blocks.is_a?(Array)
+
+      found = false
+      blocks.each do |block|
+        next unless block.is_a?(Hash) && block["type"] == type
+
+        @reasoning_text << block["text"].to_s if block["text"]
+        found = true
+      end
+      found
+    end
+
+    private def parse_or_nil(s)
+      # Some providers / proxies append a "[DONE]" sentinel (inherited from
+      # Chat Completions SSE) even for the Responses API.  Silently ignore it
+      # instead of logging a parse failure.
+      return nil if s.to_s.strip == "[DONE]"
+
+      JSON.parse(s)
+    rescue JSON::ParserError => e
+      @parse_failures += 1
+      if @parse_failures == 1
+        Clacky::Logger.warn("stream.parse_failure",
+          provider: "openai-responses",
+          error: "#{e.class}: #{e.message}",
+          frame_head: s.to_s[0, 200],
+          frame_bytes: s.to_s.bytesize
+        )
+      end
+      nil
+    end
+
+    private def emit_estimate_progress
+      return unless @on_chunk
+      output = approximate_output_tokens
+      return if output == @last_output_tokens
+      @last_output_tokens = output
+      @on_chunk.call(input_tokens: @last_input_tokens, output_tokens: output)
+    rescue => e
+      Clacky::Logger.warn("[OpenAIResponsesStreamAggregator] on_chunk: #{e.class}: #{e.message}")
+    end
+
+    # Rough char/4 estimate; replaced by the real count when the upstream
+    # emits the response.completed event with usage data.
+    private def approximate_output_tokens
+      total_chars = @text.bytesize + @reasoning_text.bytesize +
+        @function_calls.values.sum { |tc| tc[:arguments].to_s.bytesize }
+      (total_chars / 4.0).ceil
+    end
+
+    private def emit_usage_progress(u)
+      return unless @on_chunk
+      total_prompt = u["input_tokens"].to_i
+      output       = u["output_tokens"].to_i
+      return if total_prompt == @last_input_tokens && output == @last_output_tokens
+      @last_input_tokens = total_prompt
+      @last_output_tokens = output
+      @on_chunk.call(input_tokens: total_prompt, output_tokens: output)
+    rescue => e
+      Clacky::Logger.warn("[OpenAIResponsesStreamAggregator] on_chunk: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/clacky/providers.rb

@@ -31,6 +31,7 @@ module Clacky
         "api" => "bedrock",
         "default_model" => "abs-claude-sonnet-5",
         "models" => [
+          "abs-claude-fable-5-1",
           "abs-claude-fable-5",
           "abs-claude-opus-5",
           "abs-claude-opus-4-8",
@@ -44,6 +45,7 @@ module Clacky
           "dsk-deepseek-v4-flash",
           "dsk-deepseek-v4-flash-vision-exp",
           "or-gemini-3-1-pro",
+          "or-gemini-3-8-flash",
           "or-gemini-3-7-flash",
           "or-gemini-3-6-flash",
           "or-gemini-3-5-flash"
@@ -97,34 +99,38 @@ module Clacky
         # routes them to Vertex AI Gemini (generateContent with inline
         # audio parts). The gateway returns transcription text.
         "stt_models" => [
+          "or-stt-gemini-3-8-flash",
           "or-stt-gemini-3-7-flash",
           "or-stt-gemini-3-6-flash",
           "or-stt-gemini-3-5-flash",
           "or-stt-gemini-1-5-pro"
         ],
         "stt_model_aliases" => {
+          "or-stt-gemini-3-8-flash" => "Gemini 3.8 Flash STT",
           "or-stt-gemini-3-7-flash" => "Gemini 3.7 Flash STT",
           "or-stt-gemini-3-6-flash" => "Gemini 3.6 Flash STT",
           "or-stt-gemini-3-5-flash" => "Gemini 3.5 Flash STT",
           "or-stt-gemini-1-5-pro"   => "Gemini 1.5 Pro STT"
         },
-        "default_stt_model" => "or-stt-gemini-3-7-flash",
+        "default_stt_model" => "or-stt-gemini-3-8-flash",
         # Video understanding models served by the openclacky gateway, which
         # routes video frames to Gemini (generateContent with inline image
         # parts). The gateway returns analysis text.
         "video_understanding_models" => [
+          "or-gemini-3-8-flash",
           "or-gemini-3-7-flash",
           "or-gemini-3-6-flash",
           "or-gemini-3-5-flash",
           "or-gemini-3-1-pro"
         ],
         "video_understanding_model_aliases" => {
+          "or-gemini-3-8-flash" => "Gemini 3.8 Flash",
           "or-gemini-3-7-flash" => "Gemini 3.7 Flash",
           "or-gemini-3-6-flash" => "Gemini 3.6 Flash",
           "or-gemini-3-5-flash" => "Gemini 3.5 Flash",
           "or-gemini-3-1-pro"   => "Gemini 3.1 Pro"
         },
-        "default_video_understanding_model" => "or-gemini-3-7-flash",
+        "default_video_understanding_model" => "or-gemini-3-8-flash",
         # Default OCR sidecar — used when the primary model is text-only.
         # Candidates are derived from the provider's vision-capable models;
         # this just picks the cheap+fast default to surface in "auto" mode.
@@ -148,6 +154,7 @@ module Clacky
         # themselves, so they're intentionally not listed here as keys —
         # no injection happens when the default model is already lite-class.
         "lite_models" => {
+          "abs-claude-fable-5-1"  => "abs-claude-haiku-4-5",
           "abs-claude-fable-5"    => "abs-claude-haiku-4-5",
           "abs-claude-opus-5"     => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-8"   => "abs-claude-haiku-4-5",
@@ -162,6 +169,7 @@ module Clacky
         # Fallback chain: if a model is unavailable, try the next one in order.
         # Keys are primary model names; values are the fallback model to use instead.
         "fallback_models" => {
+          "abs-claude-fable-5-1"  => "abs-claude-fable-5",
           "abs-claude-fable-5"    => "abs-claude-opus-5",
           "abs-claude-opus-5"     => "abs-claude-opus-4-8",
           "abs-claude-sonnet-5"   => "abs-claude-sonnet-4-6",
@@ -276,7 +284,7 @@ module Clacky
         "base_url" => "https://open.bigmodel.cn/api/paas/v4",
         "api" => "openai-completions",
         "default_model" => "glm-5.3",
-        "models" => ["glm-5.3", "glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7"],
+        "models" => ["glm-5.3", "glm-5.3-flash", "glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7"],
         # Zhipu / Z.ai expose four functionally-equivalent endpoints:
         # two regional sites (mainland open.bigmodel.cn + international api.z.ai)
         # each with a general-billing and a Coding-Plan subpath. They share the
@@ -292,10 +300,12 @@ module Clacky
           { "label" => "International · Pay-as-you-go", "label_key" => "settings.models.baseurl.variant.international_payg",  "base_url" => "https://api.z.ai/api/paas/v4",                "region" => "intl" }.freeze,
           { "label" => "International · Coding Plan",   "label_key" => "settings.models.baseurl.variant.international_coding","base_url" => "https://api.z.ai/api/coding/paas/v4",         "region" => "intl" }.freeze
         ].freeze,
-        # GLM models are text-only except glm-5v-turbo which is vision-capable ("v" = visual).
+        # GLM models are text-only except the vision-capable SKUs: glm-5v-turbo
+        # ("v" = visual) and glm-5.3-flash (GLM-5's first natively-multimodal model).
         "capabilities" => { "vision" => false }.freeze,
         "model_capabilities" => {
-          "glm-5v-turbo" => { "vision" => true }.freeze
+          "glm-5v-turbo" => { "vision" => true }.freeze,
+          "glm-5.3-flash" => { "vision" => true }.freeze
         }.freeze,
         "default_ocr_model" => "glm-5v-turbo",
         "website_url" => "https://open.bigmodel.cn/console/overview"
@@ -446,8 +456,9 @@ module Clacky
         "name" => "Qwen (Alibaba)",
         "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",
         "api" => "openai-completions",
-        "default_model" => "qwen3.7-max",
+        "default_model" => "qwen3.8-max",
         "models" => [
+          "qwen3.8-max",
           "qwen3.7-max",
           "qwen3.6-plus",
           "qwen3.6-max",
@@ -466,6 +477,7 @@ module Clacky
         }.freeze,
         "default_ocr_model" => "qwen3.6-flash",
         "lite_models" => {
+          "qwen3.8-max"      => "qwen3.6-flash",
           "qwen3.7-max"      => "qwen3.6-flash",
           "qwen3.6-plus"     => "qwen3.6-flash",
           "qwen3.6-max"      => "qwen3.6-flash",

data/lib/clacky/server/dir_picker.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Clacky
+  module Server
+    # Directory-picker quick-access places + WSL/Windows drive detection.
+    # Extracted from HttpServer to keep the path/place helpers cohesive.
+    module DirPicker
+      # Windows "special" folders under C:\Users that aren't real user profiles.
+      WINDOWS_PROFILE_DIRS = ["Public", "Default", "Default User", "All Users"].freeze
+
+      # Sidebar quick-access favorites for the directory picker (Finder-style).
+      # Translated client-side via `id`. On WSL every favorite targets the
+      # Windows profile (/mnt/<drive>/Users/<name>/...) so they match where a
+      # Windows browser actually saves files; elsewhere they stay under Dir.home.
+      private def dir_picker_places
+        home = Dir.home
+        win_home = wsl_windows_home
+        places = []
+
+        [["home", win_home || home],
+         ["desktop",   File.join(win_home || home, "Desktop")],
+         ["downloads", File.join(win_home || home, "Downloads")],
+         ["documents", File.join(win_home || home, "Documents")]].each do |id, path|
+          places << { id: id, path: path, kind: "favorite" } if Dir.exist?(path)
+        end
+
+        places.concat(dir_picker_drives)
+        places
+      end
+
+      # Drive letters exposed to the picker so Windows users can reach D:/E:/…
+      # directly. Under WSL these are the /mnt/<drive> mounts; on native
+      # Windows the actual drive letters. Empty on macOS/Linux.
+      private def dir_picker_drives
+        if wsl?
+          mounts = "/mnt"
+          return [] unless Dir.exist?(mounts)
+
+          drives = []
+          Dir.children(mounts).sort.each do |drive|
+            next unless drive.match?(/\A[a-zA-Z]\z/)
+            path = File.join(mounts, drive)
+            next unless Dir.exist?(path)
+            drives << { id: "drive_#{drive.downcase}", path: path, letter: drive.upcase, kind: "drive" }
+          end
+          drives
+        elsif Gem.win_platform?
+          drives = []
+          ("A".."Z").each do |letter|
+            path = "#{letter}:/"
+            next unless Dir.exist?(path)
+            drives << { id: "drive_#{letter.downcase}", path: path, letter: letter, kind: "drive" }
+          end
+          drives
+        else
+          []
+        end
+      end
+
+      # True when running inside Windows Subsystem for Linux.
+      private def wsl?
+        return true if ENV["WSL_DISTRO_NAME"]
+        return true if File.exist?("/proc/sys/fs/binfmt_misc/WSLInterop")
+        version = begin
+          File.read("/proc/version")
+        rescue StandardError
+          ""
+        end
+        version.downcase.include?("microsoft")
+      end
+
+      # Best-effort path to the Windows user profile under WSL, or nil when it
+      # can't be determined (then callers fall back to Dir.home). Scans every
+      # mounted drive's Users dir instead of assuming the system drive is C:.
+      # Username sources are tried most-trusted first:
+      #   1. WINDOWS_USERNAME / USERNAME env (explicitly set or WSLENV-forwarded)
+      #   2. the live Windows %USERNAME%, read via cmd.exe interop
+      #   3. USER (the WSL Linux username, which usually matches the Windows one)
+      #   4. the first non-system profile dir found (last-resort guess)
+      private def wsl_windows_home
+        return nil unless wsl?
+
+        roots = wsl_windows_users_roots
+        wsl_profile_for(roots, ENV["WINDOWS_USERNAME"]) ||
+          wsl_profile_for(roots, ENV["USERNAME"]) ||
+          wsl_profile_for(roots, wsl_windows_username) ||
+          wsl_profile_for(roots, ENV["USER"]) ||
+          wsl_first_user_profile(roots)
+      end
+
+      # The first mounted profile dir named exactly `username`, or nil. WSL
+      # never inherits Windows env vars by default, which is why `username`
+      # may also come from cmd.exe interop rather than ENV.
+      private def wsl_profile_for(roots, username)
+        return nil if username.nil? || username.empty?
+
+        roots.each do |root|
+          candidate = File.join(root, username)
+          return candidate if Dir.exist?(candidate)
+        end
+        nil
+      end
+
+      # Last-resort guess: the first non-system profile dir under any mounted
+      # Users root. Filesystem enumeration order is arbitrary, so on
+      # multi-profile machines this may pick an inactive profile — every
+      # username source in wsl_windows_home exists to keep this unreached.
+      private def wsl_first_user_profile(roots)
+        roots.each do |root|
+          profiles = Dir.children(root).select do |name|
+            full = File.join(root, name)
+            File.directory?(full) &&
+              !WINDOWS_PROFILE_DIRS.include?(name) &&
+              !name.start_with?(".")
+          end
+          return File.join(root, profiles.first) if profiles.any?
+        end
+        nil
+      end
+
+      # The live Windows-side %USERNAME%, read via cmd.exe interop. Returns
+      # nil when interop is disabled or cmd.exe is unreachable; callers must
+      # still validate against the mounted Users directory. Cached —
+      # including failures — because interop availability doesn't change
+      # within a process and the spawn otherwise costs 100ms+ on every
+      # directory listing.
+      private def wsl_windows_username
+        return @wsl_windows_username if defined?(@wsl_windows_username)
+
+        @wsl_windows_username = begin
+          require "open3"
+          out, _err, status = Open3.capture3("cmd.exe", "/c", "echo %USERNAME%", binmode: true)
+          status.success? ? out.lines.first&.strip : nil
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Every mounted drive that exposes a Windows Users directory, e.g.
+      # /mnt/c/Users and /mnt/d/Users.
+      private def wsl_windows_users_roots
+        mounts = "/mnt"
+        return [] unless Dir.exist?(mounts)
+
+        roots = []
+        Dir.children(mounts).each do |drive|
+          root = File.join(mounts, drive, "Users")
+          roots << root if Dir.exist?(root)
+        end
+        roots
+      end
+    end
+  end
+end

data/lib/clacky/server/git_panel.rb

@@ -7,8 +7,8 @@ module Clacky
     # Read-mostly git operations scoped to a session's working directory, backing
     # the official "git" WebUI panel. Commands run with explicit argv (no shell),
     # so user-supplied values (paths, messages) cannot inject. Write operations
-    # are limited to a guarded `commit`; history-rewriting / remote-mutating
-    # commands are never exposed here.
+    # are limited to a guarded `commit` and a single-file `restore`;
+    # history-rewriting / remote-mutating commands are never exposed here.
     module GitPanel
       module_function
 
@@ -56,14 +56,24 @@ module Clacky
         { branch: branch, ahead: ahead, behind: behind, files: files }
       end
 
-      # Unified diff. `file` (optional, relative) limits to one path; omitted =
-      # whole working tree (tracked changes). `--` guards path from being read
-      # as an option.
+      # Unified diff for one file, or the whole tree when `file` is nil.
+      # Baseline is HEAD, not the index, so changes the agent staged with
+      # `git add` still show up. Untracked files have no baseline at all, so
+      # they diff against /dev/null via --no-index (rendered as pure
+      # additions); the trailing `--` keeps a leading-dash filename from
+      # being read as an option in that mode too.
       def diff(dir, file: nil)
-        args = ["diff"]
-        args += ["--", file] if file && !file.empty?
-        out, _err, _ok = git(dir, *args)
-        out
+        if file && !file.empty?
+          others, _e, _ok = git(dir, "ls-files", "--others", "--exclude-standard", "--", file)
+          if others.strip.empty?
+            out, _e, _ok = git(dir, "diff", "HEAD", "--", file)
+          else
+            out, _e, _ok = git(dir, "diff", "--no-index", "--", "/dev/null", file)
+          end
+          out
+        else
+          git(dir, "diff", "HEAD")[0]
+        end
       end
 
       # Recent commits: [{ hash:, short:, author:, date:, subject: }].
@@ -92,6 +102,48 @@ module Clacky
         end
       end
 
+      # Discard uncommitted changes to one file and return it to its HEAD
+      # state (same baseline the diff API uses, so "what you saw is what you
+      # lose"). Files that never existed in HEAD (staged-new or untracked)
+      # have no earlier version, so they are removed instead. argv-only and
+      # guarded against path traversal; history rewriting and remote-mutating
+      # commands remain out of bounds.
+      def restore(dir, file:)
+        path = file.to_s.strip
+        return { ok: false, error: "file is required" } if path.empty?
+        return { ok: false, error: "invalid path" } if invalid_path?(path)
+
+        head_tree, _e, _ok = git(dir, "ls-tree", "HEAD", "--", path)
+        if head_tree.include?("\t#{path}")
+          _o, err, ok = git(dir, "checkout", "HEAD", "--", path)
+          return ok ? { ok: true } : { ok: false, error: "git checkout failed: #{err.strip}" }
+        end
+
+        in_index, _e, idx_ok = git(dir, "ls-files", "--", path)
+        if idx_ok && !in_index.strip.empty?
+          _o, err, ok = git(dir, "rm", "-f", "--", path)
+          return ok ? { ok: true } : { ok: false, error: "git rm failed: #{err.strip}" }
+        end
+
+        target = File.expand_path(path, dir.to_s)
+        root = File.expand_path(dir.to_s)
+        return { ok: false, error: "invalid path" } unless target.start_with?(root + File::SEPARATOR)
+
+        begin
+          File.delete(target)
+          { ok: true }
+        rescue Errno::ENOENT
+          { ok: true }
+        rescue StandardError => e
+          { ok: false, error: e.message }
+        end
+      end
+
+      # Relative repo paths only: no absolute paths, no traversal segments.
+      def invalid_path?(path)
+        path.start_with?("/") || path.split("/").include?("..")
+      end
+
       # Stage `files` (relative paths) and commit with `message`. Returns
       # { ok:, error?:, hash? }. Refuses empty message / empty file set. Uses
       # argv so paths/message cannot inject; no --no-verify, no amend.