openclacky 1.5.13 → 1.5.14

data/lib/clacky/media/openai_compat.rb

@@ -308,38 +308,69 @@ module Clacky
         end
 
         ext = mime_type.split(";").first.split("/").last.then { |e| e == "mpeg" ? "mp3" : e }
-        filename = "chunk.#{ext}"
-        audio_data = Base64.decode64(audio_base64)
-        boundary = "----FormBoundary#{SecureRandom.hex(8)}"
-        # A multipart body is a byte stream: build it in binary so UTF-8 text
-        # parts (e.g. a non-ASCII vocabulary prompt) don't clash with the
-        # ASCII-8BIT audio bytes.
-        body = "".b
-        body << "--#{boundary}\r\n".b
-        body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n".b
-        body << "Content-Type: #{mime_type.split(';').first}\r\n\r\n".b
-        body << audio_data.b
-        body << "\r\n--#{boundary}\r\n".b
-        body << "Content-Disposition: form-data; name=\"model\"\r\n\r\n".b
-        body << @model.to_s.b
-        unless prompt.to_s.strip.empty?
-          body << "\r\n--#{boundary}\r\n".b
-          body << "Content-Disposition: form-data; name=\"prompt\"\r\n\r\n".b
-          body << prompt.to_s.strip.b
-        end
-        body << "\r\n--#{boundary}--\r\n".b
 
-        begin
-          response = stt_connection.post("audio/transcriptions") do |req|
-            req.headers["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
-            req.headers["Authorization"] = "Bearer #{@api_key}"
-            req.body = body
+        # OpenRouter caps multipart uploads at 25 MB and redirects larger files
+        # to base64 JSON via input_audio. Plain OpenAI-compatible providers keep
+        # multipart (incl. the openclacky gateway, which only parses multipart
+        # on its /audio/transcriptions today — enable the JSON flavor there once
+        # the server supports it).
+        if provider_id == Clacky::Providers::OPENROUTER_ID
+          ext = "m4a" if ext == "mp4" # OpenRouter wants the audio format, not the container
+          payload = {
+            model: @model,
+            input_audio: {
+              data:   audio_base64, # raw base64 bytes, NOT a data URI
+              format: ext
+            }
+          }
+          payload[:prompt] = prompt.to_s.strip unless prompt.to_s.strip.empty?
+
+          begin
+            response = stt_json_connection.post("audio/transcriptions") do |req|
+              req.headers["Content-Type"]  = "application/json"
+              req.headers["Authorization"] = "Bearer #{@api_key}"
+              req.body = JSON.generate(payload)
+            end
+          rescue Faraday::Error => e
+            return transcription_error_response(
+              error: "HTTP request failed: #{e.message}",
+              error_type: "network_error", provider: provider_id
+            )
+          end
+        else
+          filename = "chunk.#{ext}"
+          audio_data = Base64.decode64(audio_base64)
+          boundary = "----FormBoundary#{SecureRandom.hex(8)}"
+          # A multipart body is a byte stream: build it in binary so UTF-8 text
+          # parts (e.g. a non-ASCII vocabulary prompt) don't clash with the
+          # ASCII-8BIT audio bytes.
+          body = "".b
+          body << "--#{boundary}\r\n".b
+          body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n".b
+          body << "Content-Type: #{mime_type.split(';').first}\r\n\r\n".b
+          body << audio_data.b
+          body << "\r\n--#{boundary}\r\n".b
+          body << "Content-Disposition: form-data; name=\"model\"\r\n\r\n".b
+          body << @model.to_s.b
+          unless prompt.to_s.strip.empty?
+            body << "\r\n--#{boundary}\r\n".b
+            body << "Content-Disposition: form-data; name=\"prompt\"\r\n\r\n".b
+            body << prompt.to_s.strip.b
+          end
+          body << "\r\n--#{boundary}--\r\n".b
+
+          begin
+            response = stt_connection.post("audio/transcriptions") do |req|
+              req.headers["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
+              req.headers["Authorization"] = "Bearer #{@api_key}"
+              req.body = body
+            end
+          rescue Faraday::Error => e
+            return transcription_error_response(
+              error: "HTTP request failed: #{e.message}",
+              error_type: "network_error", provider: provider_id
+            )
           end
-        rescue Faraday::Error => e
-          return transcription_error_response(
-            error: "HTTP request failed: #{e.message}",
-            error_type: "network_error", provider: provider_id
-          )
         end
 
         unless response.success?
@@ -479,6 +510,15 @@ module Clacky
         end
       end
 
+      # STT JSON body carries a large base64 payload; upstream may need longer
+      # to decode/transcribe it than the 30s multipart path.
+      private def stt_json_connection
+        Faraday.new(url: normalized_base_url) do |f|
+          f.options.timeout      = 120
+          f.options.open_timeout = 10
+        end
+      end
+
       private def vu_connection
         Faraday.new(url: normalized_base_url) do |f|
           f.options.timeout      = 60

data/lib/clacky/message_format/bedrock.rb

@@ -26,6 +26,8 @@ module Clacky
       # the same Clacky proxy on a different endpoint. The *model prefix* is
       # the source of truth for which upstream format the proxy expects:
       #
+      #   abs-gpt-* → OpenAI-compatible (POST /chat/completions) — GPT models
+      #               on Bedrock use the OpenAI endpoint, not Converse
       #   abs-*  → Bedrock Converse  (POST /model/{id}/converse)
       #   dsk-*  → OpenAI-compatible (POST /chat/completions)
       #   or-*   → OpenAI-compatible (POST /chat/completions)
@@ -38,7 +40,10 @@ module Clacky
       # will route correctly without touching this file.
       def self.bedrock_api_key?(api_key, model)
         return true if api_key.to_s.start_with?("ABSK")
-        model.to_s.start_with?("abs-")
+        model_str = model.to_s
+        # abs-gpt-* is served through Bedrock's OpenAI-compatible endpoint.
+        return false if model_str.start_with?("abs-gpt-")
+        model_str.start_with?("abs-")
       end
 
       module_function

data/lib/clacky/prompts/base.md

@@ -3,7 +3,7 @@
 - Ask clarifying questions if requirements are unclear.
 - Break down complex tasks into manageable steps.
 - **USE TOOLS to create/modify files** — don't just return content.
-- 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. Use the raw file path as-is (keep non-ASCII characters and spaces literal); never URL-encode it.
+- When the user asks to send/download a file or you generate one for them, append `[filename](file:///absolute/path/to/file)` at the end of your reply. Use the exact absolute path the write tool returned — don't rewrite or abbreviate it with `~` (keep non-ASCII characters and spaces literal); never URL-encode it.
 
 ## Tool Usage Rules
 

data/lib/clacky/providers.rb

@@ -29,8 +29,12 @@ module Clacky
         "name" => "OpenClacky",
         "base_url" => "https://api.openclacky.com",
         "api" => "bedrock",
-        "default_model" => "abs-claude-sonnet-5",
+        "default_model" => "or-gemini-3-8-flash",
         "models" => [
+          "abs-gpt-6-astra",
+          "abs-gpt-5.6-sol",
+          "abs-gpt-5.6-terra",
+          "abs-gpt-5.6-luna",
           "abs-claude-fable-5-1",
           "abs-claude-fable-5",
           "abs-claude-opus-5",
@@ -41,6 +45,7 @@ module Clacky
           "abs-claude-sonnet-4-6",
           "abs-claude-sonnet-4-5",
           "abs-claude-haiku-4-5",
+          "dsk-deepseek-flash",
           "dsk-deepseek-v4-pro",
           "dsk-deepseek-v4-flash",
           "dsk-deepseek-v4-flash-vision-exp",
@@ -134,7 +139,7 @@ module Clacky
         # 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.
-        "default_ocr_model" => "dsk-deepseek-v4-flash-vision-exp",
+        "default_ocr_model" => "or-gemini-3-8-flash",
         # Provider-level default: the Claude family served here is vision-capable.
         "capabilities" => { "vision" => true }.freeze,
         # Model-level overrides: DeepSeek models routed through this provider
@@ -143,10 +148,17 @@ module Clacky
         # to disk refs. Gemini 3.1 Pro keeps the provider-default vision=true
         # (it accepts image/audio/video input natively via OpenRouter).
         "model_capabilities" => {
+          "dsk-deepseek-flash"               => { "vision" => true }.freeze,
           "dsk-deepseek-v4-pro"              => { "vision" => false }.freeze,
           "dsk-deepseek-v4-flash"            => { "vision" => false }.freeze,
           "dsk-deepseek-v4-flash-vision-exp" => { "vision" => true }.freeze
         }.freeze,
+        # Bedrock GPT models (abs-gpt-*) are served through the OpenAI
+        # Responses API — their Chat Completions endpoint rejects function
+        # tools for reasoning models (GPT-6 Astra).
+        "model_api_overrides" => {
+          /\Aabs-gpt-/ => "openai-responses"
+        }.freeze,
         # Per-primary lite pairing: keys are "strong" primary models, values
         # are the lite sidekick to auto-inject when that primary is the
         # default. Lite is consumed by some subagents for cheap/fast work;
@@ -163,6 +175,8 @@ module Clacky
           "abs-claude-sonnet-5"   => "abs-claude-haiku-4-5",
           "abs-claude-sonnet-4-6" => "abs-claude-haiku-4-5",
           "abs-claude-sonnet-4-5" => "abs-claude-haiku-4-5",
+          "abs-gpt-5.6-sol"       => "abs-gpt-5.6-luna",
+          "abs-gpt-5.6-terra"     => "abs-gpt-5.6-luna",
           "dsk-deepseek-v4-pro"   => "dsk-deepseek-v4-flash",
           "or-gemini-3-1-pro"     => "or-gemini-3-6-flash"
         },
@@ -266,14 +280,17 @@ module Clacky
         # deprecated on 2026-07-24; they map to deepseek-v4-flash's non-thinking
         # and thinking modes respectively. Prefer deepseek-v4-flash / deepseek-v4-pro.
         "models" => [
+          "deepseek-flash",
           "deepseek-v4-pro",
           "deepseek-v4-flash",
           "deepseek-v4-flash-vision-exp",
         ],
         # DeepSeek V4 API is text-only across all models, except the
-        # flash-vision-exp variant which accepts image input.
+        # flash-vision-exp variant which accepts image input. V4.1 Flash
+        # (deepseek-flash) is natively multimodal.
         "capabilities" => { "vision" => false }.freeze,
         "model_capabilities" => {
+          "deepseek-flash"               => { "vision" => true }.freeze,
           "deepseek-v4-flash-vision-exp" => { "vision" => true }.freeze
         }.freeze,
         "website_url" => "https://platform.deepseek.com/api_keys"
@@ -420,6 +437,7 @@ module Clacky
         "api" => "openai-completions",
         "default_model" => "gpt-5.5",
         "models" => [
+          "gpt-6-astra",
           "gpt-5.6-sol",
           "gpt-5.6-terra",
           "gpt-5.6-luna",
@@ -703,6 +721,23 @@ module Clacky
 
     }.freeze
 
+    # Canonical provider identifiers. Mirror the PRESETS keys above; keep both
+    # in sync when adding or renaming a provider.
+    OPENCLACKY_ID     = "openclacky"
+    OPENROUTER_ID     = "openrouter"
+    DEEPSEEKV4_ID     = "deepseekv4"
+    GLM_ID            = "glm"
+    KIMI_ID           = "kimi"
+    KIMI_CODING_ID    = "kimi-coding"
+    MINIMAX_ID        = "minimax"
+    ANTHROPIC_ID      = "anthropic"
+    OPENAI_ID         = "openai"
+    QWEN_ID           = "qwen"
+    MIMO_ID           = "mimo"
+    VOLCENGINE_ARK_ID = "volcengine-ark"
+    OLLAMA_ID         = "ollama"
+    ORCAROUTER_ID     = "orcarouter"
+
     MEDIA_KINDS = %w[image video audio stt video_understanding].freeze
 
     # Per-model maximum output token limits.

data/lib/clacky/rich_ui/rich_ui_controller.rb

@@ -496,7 +496,7 @@ module Clacky
         when :add
           new_model = show_model_edit_form(nil, test_callback: test_callback)
           if new_model
-            anthropic_format = new_model[:provider] == "anthropic"
+            anthropic_format = new_model[:provider] == Clacky::Providers::ANTHROPIC_ID
             current_config.add_model(
               model: new_model[:model],
               api_key: new_model[:api_key],

data/lib/clacky/search_config.rb

@@ -6,10 +6,10 @@ require "fileutils"
 module Clacky
   # Search provider selection, backed by ~/.clacky/search.yml.
   #
-  # The built-in DuckDuckGo/Bing scrapers need no configuration and stay the
-  # default. Pointing `provider` at a script in ~/.clacky/searchers/ routes
+  # The built-in Parallel/DuckDuckGo/Bing providers need no configuration and
+  # stay the default. Pointing `provider` at a script in ~/.clacky/searchers/ routes
   # web_search through an API-backed engine instead, which is what users who
-  # want higher-quality results (or China-reachable ones) reach for.
+  # want a provider-specific API or policy controls reach for.
   #
   # search.yml schema:
   #   provider: tavily     — basename of a script in ~/.clacky/searchers/;

data/lib/clacky/server/channel/channel_manager.rb

@@ -272,7 +272,7 @@ module Clacky
         end
 
         # Handle built-in commands
-        if text&.match?(KNOWN_COMMAND) || text&.match?(/\A([\?h]|help)\z/i)
+        if text&.match?(KNOWN_COMMAND)
           handle_command(adapter, event, text)
           return
         end
@@ -366,7 +366,7 @@ module Clacky
         key     = channel_key(event)
 
         case text
-        when /\A([\?h]|help)\z/i
+        when %r{\A/([?？]|h|help)\z}i
           adapter.send_text(chat_id, COMMAND_HELP)
 
         when "/new", "/clear"
@@ -506,15 +506,18 @@ module Clacky
           list_sessions(adapter, chat_id)
 
         else
-          adapter.send_text(chat_id, "Unknown command. Type ? for help.")
+          adapter.send_text(chat_id, "Unknown command. Type /? for help.")
         end
       end
 
-      KNOWN_COMMAND = %r{\A/(new|clear|model|skills|bind|stop|unbind|status|list)\b}i
+      # "/?" is anchored with \z instead of \b because \b never matches after
+      # "?" (not a word character), which would let "/?extra" through.
+      # "？" is accepted too since Chinese IMEs produce the full-width form.
+      KNOWN_COMMAND = %r{\A/(?:[?？]\z|(?:h|help|new|clear|model|skills|bind|stop|unbind|status|list)\b)}i
 
       COMMAND_HELP = <<~HELP.strip
         Commands:
-          ? / h / help - show this help
+          /? / /h / /help - show this help
           /new / /clear - start a new session
           /model - show current model, cards & quick-switch list
           /model <n> - switch card by number

data/lib/clacky/server/git_panel.rb

@@ -2,6 +2,8 @@
 
 require "open3"
 
+require_relative "../utils/encoding"
+
 module Clacky
   module Server
     # Read-mostly git operations scoped to a session's working directory, backing
@@ -14,9 +16,15 @@ module Clacky
 
       # Run a git subcommand in `dir` with argv-style args (no shell). Returns
       # [stdout, stderr, success_bool]. Never raises on git failure.
+      #
+      # `core.quotePath=false` keeps git from octal-escaping non-ASCII paths, so
+      # the parsers below (and the path comparisons in `restore`) see the same
+      # bytes the caller passed in. Output is then normalised to UTF-8 because
+      # git inherits the locale, and under a non-UTF-8 locale the raw bytes come
+      # back tagged US-ASCII, where String#split would raise on multibyte paths.
       def git(dir, *args)
-        out, err, status = Open3.capture3("git", "-C", dir.to_s, *args)
-        [out, err, status.success?]
+        out, err, status = Open3.capture3("git", "-C", dir.to_s, "-c", "core.quotePath=false", *args)
+        [Utils::Encoding.to_utf8(out), Utils::Encoding.to_utf8(err), status.success?]
       rescue StandardError => e
         ["", e.message, false]
       end

data/lib/clacky/server/http_server.rb

@@ -20,6 +20,7 @@ require_relative "session_registry"
 require_relative "project_manager"
 require_relative "git_panel"
 require_relative "dir_picker"
+require_relative "preview"
 require_relative "web_ui_controller"
 require_relative "model_prices"
 require_relative "scheduler"
@@ -102,7 +103,7 @@ module Clacky
 
         # Rewrite local image paths to /api/local-image proxy URLs for browser rendering
         rewritten = Utils::FileProcessor.rewrite_local_image_urls(content.to_s)
-        ev = { type: "assistant_message", session_id: @session_id, content: rewritten }
+        ev = { type: "assistant_message", session_id: @session_id, content: rewritten, interim: interim }
         ev[:created_at] = created_at if created_at
         @events << stamp(ev)
       end
@@ -168,6 +169,7 @@ module Clacky
     #   GET  /**                     → static files served from lib/clacky/web/ directory
     class HttpServer
       include DirPicker
+      include Preview
 
       WEB_ROOT = File.expand_path("../web", __dir__)
       # How long shutdown waits for each agent thread to unwind before falling
@@ -496,6 +498,12 @@ module Clacky
             self.send(:serve_agent_avatar, req, res)
           elsif req.path.start_with?("/ext_ui/")
             self.send(:serve_ext_ui, req, res)
+          elsif req.path.start_with?("/preview/p/")
+            self.send(:serve_preview_proxy, req, res)
+          elsif req.path.start_with?("/preview/f/")
+            self.send(:serve_preview_local, req, res)
+          elsif req.path == "/preview" || req.path.start_with?("/preview/")
+            self.send(:serve_preview, req, res)
           else
             file_handler.service(req, res)
             res["Cache-Control"] = "no-store"
@@ -722,6 +730,9 @@ module Clacky
         when ["POST",   "/api/tool/browser"]      then api_tool_browser(req, res)
         when ["POST",   "/api/upload"]            then api_upload_file(req, res)
         when ["POST",   "/api/file-action"]       then api_file_action(req, res)
+        when ["GET",    "/api/file/apps"]         then api_file_apps(req, res)
+        when ["GET",    "/api/file/default-app"]  then api_file_default_app(req, res)
+        when ["GET",    "/api/app-icon"]          then api_app_icon(req, res)
         when ["GET",    "/api/local-image"]       then api_serve_local_image(req, res)
         when ["POST",   "/api/media/image"]       then api_media_image(req, res)
         when ["POST",   "/api/media/video"]       then api_media_video(req, res)
@@ -3471,7 +3482,7 @@ module Clacky
         keys = []
         @agent_config.models.each do |m|
           next unless m.is_a?(Hash)
-          next unless @agent_config.provider_id_for(m) == "openclacky"
+          next unless @agent_config.provider_id_for(m) == Clacky::Providers::OPENCLACKY_ID
 
           key = m["api_key"].to_s.strip
           keys << key unless key.empty?
@@ -4423,12 +4434,87 @@ module Clacky
         json_response(res, 500, { ok: false, error: e.message })
       end
 
+      # GET /api/file/apps?path=/path/to/file.pptx
+      # Lists installed applications that declare support for the file's
+      # extension, so the Web UI can offer "open with" choices for formats it
+      # cannot preview inline. macOS uses MacAppDetector, WSL uses
+      # WindowsAppDetector; other OSes answer with an empty list.
+      def api_file_apps(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
+        ext = File.extname(path).downcase.sub(/\A\./, "")
+
+        apps = if ext.empty?
+          []
+        elsif Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.apps_for_ext(ext)
+        else
+          Utils::MacAppDetector.apps_for_ext(ext)
+        end
+        json_response(res, 200, { ok: true, apps: apps })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
+      # GET /api/file/default-app?path=...
+      # Returns the application the OS would use to open the file.
+      def api_file_default_app(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
+        app = if File.extname(path).empty?
+          nil
+        elsif Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.default_app_for(path)
+        else
+          Utils::MacAppDetector.default_app_for(path)
+        end
+        json_response(res, 200, { ok: true, app: app })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
+      # GET /api/app-icon?path=/Applications/Keynote.app  (macOS)
+      # GET /api/app-icon?path=C:\...\app.exe              (WSL)
+      # Serves an application's icon as a PNG. macOS converts the bundle .icns
+      # via sips; WSL extracts the .exe associated icon via PowerShell. Both are
+      # cached on disk.
+      def api_app_icon(req, res)
+        raw_path = URI.decode_www_form(req.query_string.to_s).to_h["path"].to_s
+        return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
+
+        png = if Utils::EnvironmentDetector.os_type == :wsl
+          Utils::WindowsAppDetector.icon_png(raw_path)
+        else
+          Utils::MacAppDetector.icon_png(Utils::EnvironmentDetector.resolve_local_path(raw_path))
+        end
+        unless png
+          # Never let a failed lookup stick in the browser cache — it would keep
+          # serving a 404 even after the detector is fixed/updated.
+          res["Cache-Control"] = "no-store"
+          return json_response(res, 404, { error: "icon not found" })
+        end
+
+        res.status = 200
+        res["Content-Type"] = "image/png"
+        res["Cache-Control"] = "public, max-age=604800"
+        res["Content-Length"] = File.size(png).to_s
+        res.body = File.binread(png)
+      rescue => e
+        json_response(res, 500, { error: e.message })
+      end
+
       # POST /api/file-action
       # Unified file action endpoint — open locally or download.
-      # Body: { path: String, action: "open" | "download" | "save" }
-      #   open:     opens the file with the OS default handler (local deployments).
-      #   download: returns the file as a download (remote deployments).
-      #   save:     writes content back to the file. Body must include { content: String }.
+      # Body: { path: String, action: "open" | "open_with" | "download" | "save" }
+      #   open:      opens the file with the OS default handler (local deployments).
+      #   open_with: opens the file with the app named in body.app (the app must
+      #              be one returned by /api/file/apps).
+      #   download:  returns the file as a download (remote deployments).
+      #   save:      writes content back to the file. Body must include { content: String }.
       def api_file_action(req, res)
         body = parse_json_body(req)
         path = body["path"]
@@ -4452,6 +4538,15 @@ module Clacky
           result = Utils::EnvironmentDetector.open_file(linux_path)
           return json_response(res, 501, { error: "unsupported OS" }) if result.nil?
           json_response(res, 200, { ok: true })
+        when "open_with"
+          result = if Utils::EnvironmentDetector.os_type == :wsl
+            Utils::WindowsAppDetector.open_with(linux_path, body["app"].to_s)
+          else
+            Utils::MacAppDetector.open_with(linux_path, body["app"].to_s)
+          end
+          return json_response(res, 400, { error: "unknown application" }) if result.nil?
+          return json_response(res, 500, { error: "failed to open with application" }) unless result
+          json_response(res, 200, { ok: true })
         when "reveal"
           Utils::EnvironmentDetector.reveal_file(linux_path)
           json_response(res, 200, { ok: true })
@@ -4467,7 +4562,7 @@ module Clacky
           File.write(linux_path, content, encoding: "UTF-8")
           json_response(res, 200, { ok: true })
         else
-          json_response(res, 400, { error: "invalid action. Must be 'open', 'reveal', 'download', 'display-path' or 'save'" })
+          json_response(res, 400, { error: "invalid action. Must be 'open', 'open_with', 'reveal', 'download', 'display-path' or 'save'" })
         end
       rescue => e
         json_response(res, 500, { ok: false, error: e.message })
@@ -5226,7 +5321,10 @@ module Clacky
           next unless File.exist?(full)
           {
             name:  name,
-            path:  "#{rel}/#{name}".gsub(%r{/+}, "/"),
+            # Root-level entries must NOT get a leading "/" — the client treats
+            # slash-prefixed paths as absolute and passes them to file-action
+            # verbatim, which then fails to find "<root>/<name>".
+            path:  rel.empty? ? name : "#{rel}/#{name}".gsub(%r{/+}, "/"),
             type:  is_dir ? "dir" : "file",
             size:  is_dir ? nil : (File.size(full) rescue nil)
           }
@@ -5358,11 +5456,22 @@ module Clacky
           return json_response(res, 404, { ok: false, error: "SKILL.md not found" })
         end
 
+        raw = File.read(skill_md)
+        frontmatter_match = raw.match(/\A---\n.*?\n---[ \t]*\n?/m)
+        body = frontmatter_match ? raw[frontmatter_match.end(0)..].sub(/\A\n+/, "") : raw
+
         json_response(res, 200, {
           ok:      true,
           name:    skill.identifier,
-          content: File.read(skill_md),
-          path:    skill_md
+          content: raw,
+          path:    skill_md,
+          fields:  {
+            name:           skill.identifier,
+            name_zh:        skill.name_zh.to_s,
+            description:    skill.description.to_s,
+            description_zh: skill.description_zh.to_s,
+            body:           body
+          }
         })
       end
 
@@ -5375,13 +5484,19 @@ module Clacky
           return json_response(res, 403, { ok: false, error: "System skills cannot be edited" })
         end
 
-        data    = parse_json_body(req)
-        content = data["content"].to_s
+        data     = parse_json_body(req)
         skill_md = File.join(skill.directory.to_s, "SKILL.md")
         unless File.exist?(skill_md)
           return json_response(res, 404, { ok: false, error: "SKILL.md not found" })
         end
 
+        fields  = data["fields"]
+        content = if fields.is_a?(Hash)
+                    Clacky::Skill.update_frontmatter_fields(File.read(skill_md), fields)
+                  else
+                    data["content"].to_s
+                  end
+
         File.write(skill_md, content)
         @skill_loader.load_all
         json_response(res, 200, { ok: true, name: skill.identifier })
@@ -6761,15 +6876,47 @@ module Clacky
 
         unless agent
           Clacky::Logger.warn("[messages] agent is nil", session_id: session_id)
+          if query["navigation"] == "1"
+            return json_response(res, 200, { sources: [], total: 0 })
+          end
+          if query["previews"]
+            return json_response(res, 200, { previews: [] })
+          end
+          if query["preview"]
+            return json_response(res, 409, { error: "History location is no longer available" })
+          end
           return json_response(res, 200, { events: [], has_more: false })
         end
 
         # Collect events emitted by replay_history via a lightweight collector UI
+        if query["navigation"] == "1"
+          return json_response(res, 200, agent.history_navigation)
+        end
+        if query["previews"]
+          ids = JSON.parse(query["previews"])
+          raise ArgumentError, "History locations must be an array" unless ids.is_a?(Array)
+
+          return json_response(res, 200, { previews: agent.history_navigation_previews(ids: ids) })
+        end
+        if query["preview"]
+          return json_response(res, 200, agent.history_navigation_preview(id: query["preview"]))
+        end
         collected = []
         collector = HistoryCollector.new(session_id, collected)
-        result    = agent.replay_history(collector, limit: limit, before: before)
+        if query["window"] == "1"
+          result = agent.replay_history_window(collector, limit: limit, around: query["around"],
+            before_id: query["before_id"], after_id: query["after_id"])
+          ids = result.delete(:round_ids)
+          collected.select { |event| event[:type] == "history_user_message" }.each_with_index do |event, index|
+            event[:round_id] = ids[index]
+          end
+        else
+          result = agent.replay_history(collector, limit: limit, before: before)
+        end
 
-        json_response(res, 200, { events: collected, has_more: result[:has_more] })
+        json_response(res, 200, { events: collected }.merge(result))
+      rescue ArgumentError, JSON::ParserError => e
+        json_response(res, 409, { error: e.message })
       end
 
       # ── Project API ───────────────────────────────────────────────────────────