openclacky 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49800afa935670c288d9f421595df4246b61e76ed0f2a74e1a7a754e85e26162
-  data.tar.gz: dba09cac5a79485b743aaad4568ce2e4fe2e13772d6b8c43a360ec11eca7c762
+  metadata.gz: d36230a47c25a8b5fb04dfc14f9359155489a2539d0a699843e140deed1434ba
+  data.tar.gz: c237725ed637d2d7a852d3624611cca101290e2348e0c6befb2650342550ec03
 SHA512:
-  metadata.gz: 2b723771f71d880d99582f6bfd4d23a66f54ee3caa87f7ed228360f015cadb52a20be9d6869c6e35612740ddb889ceb762efa541a41bc25810f5897d47a333e1
-  data.tar.gz: 5c425e94d2bf4c4d68175b740d840b9cd6270ef91f2e68e6d8403fbb6fbc5336b07bd65308907dbb8d8c3cd1cb906c4c5f64ae7710a7e0619ab2aaae0ddc278b
+  metadata.gz: 89c65d848c67dff3ed63ae70cd6a0539a7a8068682d72009b34741ea09c44749f5fa05c5839bc9c02c5c499709c8e5bce321165561bdbf8a43500539d1e4b21c
+  data.tar.gz: 74ebac898a16e090481c8ba423ac7c2d9cafe918f09cdc87066b54c911034b941c713650d24aaa8d71c627c48d3c8c56a780c2ffa6e717448e4712cdd5ca9512

data/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] - 2026-05-07
+
+### Added
+- **Multi-region provider endpoints.** Providers can now expose multiple endpoint variants (e.g. global vs. CN-optimized Anthropic), and you can switch between them from both the onboarding flow and the Settings page. Bundled with updated model pricing data so cost estimates stay accurate across regions. (#67)
+- **Pre-installed platform-recommended skills during onboarding.** New users get a curated set of skills automatically during onboard — downloaded concurrently with dual-host fallback and a hard deadline so onboarding never hangs on a slow mirror. (#68)
+- **Builtin skills served via platform API.** Recommended skills are now fetched through `/api/v1/skills/builtin`, making the list easier to update without shipping a new gem. (#72)
+- **Feishu group chats: respond only when @-mentioned.** The Feishu adapter now parses the mentions array and ignores group messages that don't @ the bot, so the bot no longer replies to every message in a busy group. Sessions are also isolated per (chat, user) pair by default (`:chat_user` binding mode), preventing context leaks between DMs and groups. (#71)
+
+### Fixed
+- **Recover from truncated upstream tool calls.** When an upstream LLM response cuts off mid tool-call, the agent now detects the truncation and recovers automatically instead of getting stuck. Covered by extensive new tests.
+- **Feedback option click now sends the message.** Clicking a suggested feedback option previously set the input text but silently failed to send (due to a `sendMessage` vs `_sendMessage` scope bug). Now it dispatches immediately as expected. (#69)
+- **Sidebar footer and input area heights aligned.** Introduced a shared `--footer-height` CSS variable (56px) and reworked the stop button to use a pseudo-element square for pixel-perfect centering — both columns now line up cleanly. (#70)
+- **Feishu bot fails closed on API outage.** If `/open-apis/bot/v3/info` fails and `bot_open_id` can't be resolved, the adapter now drops group messages (with a warning) instead of spamming every group message as a fallback.
+- **`preview.md` no longer pollutes user project directories.** Preview files are written to the system tmpdir, and plain text formats (md/log/csv) skip preview generation entirely since they're already readable as-is.
+
+### More
+- Added agent stop logging to make interrupt / stop chains easier to debug.
+
+## [1.0.1] - 2026-05-06
+
+### Added
+- **OpenRouter Anthropic API support.** You can now route Claude model requests through OpenRouter, giving access to Anthropic models via a single OpenRouter API key — useful when Anthropic direct access is limited in your region.
+- **GPT provider support.** Direct GPT provider configuration is now available alongside other providers, making it easier to switch between different OpenAI-compatible endpoints.
+- **OCR-powered PDF reading.** PDF files that contain scanned images (non-text PDFs) are now readable via OCR, allowing the agent to extract content from scanned documents, invoices, and image-heavy PDFs.
+- **Terminal output size control.** The agent now limits terminal output to a configurable size, preventing token overflows when running commands that produce very long output.
+- **Memories & Trash manager in Web UI.** A new management panel lets you browse, review, and delete agent memories and trashed files directly from the Web UI.
+- **Watchdog for interrupt messages.** A background watchdog ensures interrupt signals reliably stop the agent even when it's deep in a tool execution loop.
+- **Skill import with category directory scanning.** When importing skills from openclaw packages, nested category directories are now scanned automatically, so all skills in a category bundle are imported at once.
+
+### Improved
+- **Deploy skill simplified.** The deploy skill now uses Railway CLI directly without custom helper tools, making deployments more reliable and the codebase significantly lighter.
+- **Fix double-render of progress indicators.** Progress spinners and status lines no longer render twice in quick succession, keeping the Web UI output clean.
+- **Session idle status tracking and file descriptor cleanup.** Sessions now correctly report idle state when the agent finishes, and open file descriptors are properly closed to avoid resource leaks.
+- **GPT-4.1 and GPT-5 pricing added.** Model cost tracking now includes the latest GPT-4.1 and GPT-5 pricing tiers.
+
+### Fixed
+- **UTF-8 encoding error in file preview.** Opening files with non-UTF-8 characters no longer crashes the preview — they are now handled gracefully.
+- **Expand `~` in openfile path.** The "open file in editor" API endpoint now correctly expands `~` to the user's home directory.
+
 ## [1.0.0] - 2026-04-30
 
 ### Added

data/README.md

@@ -6,77 +6,79 @@
 [![Downloads](https://img.shields.io/gem/dt/openclacky?label=downloads&style=flat-square&color=brightgreen)](https://rubygems.org/gems/openclacky)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE.txt)
 
-**From expertise to business — turn your professional knowledge into a monetizable OpenClaw Skill.**
+**The most Token-efficient open-source AI Agent.**
 
-OpenClacky is the creator-side platform for the OpenClaw ecosystem. Package your methods and workflows into encrypted, white-labeled Skills that your clients install and use — under your name, your brand, your price.
+OpenClacky matches Claude Code on capability at comparable cost, and saves significantly against other open-source agents (~50% vs OpenClaw, ~3× cheaper than Hermes). 100% open source (MIT), BYOK with any OpenAI-compatible model, built on two years of Agentic R&D and harness engineering.
 
-## Why OpenClacky?
+> Website: https://www.openclacky.com/ · Backed by **MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital**
 
-The OpenClaw ecosystem has 5,700+ Skills and growing. But almost all of them are open-sourced, free, and easily copied. The real scarcity isn't more Skills — it's **expertise-backed, production-grade Skills worth paying for**.
+## Why OpenClacky?
 
-OpenClacky is built for the people who have that expertise.
+Same task, how much do you pay? Under comparable agent workloads, OpenClacky saves a large amount of Token spend compared to mainstream alternatives.
 
-|  | **Openclaw** | **OpenClacky** |
+| Agent | Relative cost | Notes |
 |---|---|---|
-| **Core model** | Open sharing | Encrypted & protected |
-| **Primary users** | Users who install Skills | Creators who sell Skills |
-| **Revenue** | None | Creator-defined pricing |
-| **Brand** | Platform brand | Your own brand |
-| **Driven by** | Technical contributors | Domain expertise |
+| **OpenClacky** | **~0.8–1.2×** | 16 tools · ~100% cache hit · subagent routing |
+| Claude Code | 1.0× (baseline) | World-class harness, closed-source subscription |
+| OpenClaw | ~1.5× | Comparable harness agent |
+| Hermes | ~3× | 52 built-in tools — schema bloat ~3–4× |
 
-## How It Works
+*Numbers are averages measured on internal common agent tasks, using Claude Code as the baseline. Full benchmark reports will be published on GitHub.*
 
-**Four steps from capability to business:**
+## Feature comparison
 
-1. **Craft your Skill** — Turn your domain methodology into a repeatable AI workflow
-2. **Encrypt & protect** — Your logic stays yours; clients can't inspect or copy it
-3. **Package your brand** — Ship under your name, your logo, your onboarding experience
-4. **Launch & acquire** — One-click sales page, built-in SEO, start converting traffic
+Core agent capability is roughly on par across the field — the real differentiators are **cost, openness, Skill evolution, and integrations**.
 
-## Who It's For
+| Feature | Claude Code | OpenClaw | Hermes | **OpenClacky** |
+|---|:---:|:---:|:---:|:---:|
+| Token cost | 1.0× | ~1.5× | ~3× | **~0.8–1.2×** |
+| Open source | ❌ Closed | ✅ Open | ✅ Open | ✅ MIT |
+| BYOK / model freedom | ❌ Anthropic only | ✅ | ✅ | ✅ |
+| Skill self-evolution | ❌ | ❌ | ✅ | ✅ |
+| IM integration (Feishu / WeCom / WeChat) | ❌ | ✅ | ✅ | ✅ |
 
-OpenClacky is built for domain experts whose knowledge can be expressed as *information processing + executable actions*:
+## How we get the cost down
 
-- **SEO specialists** — keyword research, content scoring, rank monitoring
-- **Lawyers** — contract review, case retrieval, risk flagging
-- **Traders** — signal detection, strategy backtesting, automated execution
-- **Data analysts** — cleaning, modeling, report generation
-- **Content strategists** — topic selection, outlines, drafts at scale
+Not by cutting features — by compounding the right choice at every layer.
 
-## Features
+### 1. Ultra-high cache hit rate
+Sessions never restart, double cache markers, **Insert-then-Compress** — the system prompt is never mutated, so compression still reuses the cache. **Measured cache hit rate: near 100%.**
 
-- [x] **Skill builder** — Create AI workflows via conversation or UI, iterate and ship fast
-- [x] **Encryption** — Protect your knowledge assets; end users cannot read your Skill source
-- [x] **White-label packaging** — Your brand, your product line, your client experience
-- [x] **Auto-update delivery** — Push updates to all users seamlessly, with version control
-- [x] **Cross-platform distribution** — Windows, macOS, Linux — one Skill, every platform
-- [x] **Sales page generator** — Launch your storefront fast, with built-in SEO foundations
-- [x] **Cost monitoring** — Real-time token tracking, automatic compression (up to 90% savings)
-- [x] **Multi-provider support** — OpenAI, Anthropic, DeepSeek, and any OpenAI-compatible API
-- [ ] **Skill marketplace** — Discover and distribute premium Skills *(coming soon)*
+### 2. Minimal tool set
+Only **16 core tools**. Capabilities are offloaded to the Skill ecosystem via a single `invoke_skill` meta-tool. Tool count is not the metric — task completion rate is.
 
-## Coding Support
+| OpenClacky | Claude Code | OpenClaw | Hermes |
+|:--:|:--:|:--:|:--:|
+| **16** | 40+ | 23 | 52 |
 
-OpenClacky also works as a general AI coding assistant — scaffold full-stack Rails apps, add features, or explore an unfamiliar codebase:
+### 3. Idle-time auto-compression
+Go to a meeting, grab coffee — the agent compresses long context in the background and pre-warms the cache. Your first message back hits the cache directly. **Cold-start first-token cost reduced by 50%+.**
 
-```bash
-$ openclacky
-> /new my-app        # scaffold a full-stack Rails app
-> Add user auth with email and password
-> How does the payment module work?
-```
+### 4. BYOK — you pick the model, you set the cost
+Any OpenAI-compatible API, plug and play. Official direct, aggregate routing, compatible relays — the choice is 100% yours. Use Claude for code, auto-route subtasks to DeepSeek, save another chunk of tokens.
+
+Built on **2 years · 3 generations of agentic architecture · 6 core harness engineering decisions**.
+
+## Skills — the soul of the agent
 
-Built on a production-ready Rails architecture with one-click deployment, dev/prod isolation, and automatic backups.
+- **Invoke with `/`** — instant browse, fuzzy search, direct call. Hundreds of Skills at your fingertips.
+- **Create Skills in natural language** — just describe what you want; the agent drafts `SKILL.md`, breaks down steps, and runs validation. No code required.
+- **Self-evolving** — after each run, the agent updates the Skill based on execution context and results. The next call is more stable and more accurate.
+- **Open & compatible** — supports Claude Skills / Markdown Pack / custom formats.
+- **Monetizable** — polished Skills can be packaged for sale, with encrypted distribution, License management, and creator-defined pricing.
 
 ## Installation
 
-### Method 1: One-line Install (Recommended)
+### Desktop installer (recommended)
 
-```bash
-/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
-```
+Double-click to install — environment, dependencies, and Skills all set up automatically.
+
+- **macOS** — [Download `.dmg`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.dmg) (Apple Silicon / Intel)
+- **Windows** — [Download `.exe`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.exe) (Windows 10 2004+ / Windows 11)
 
-### Method 2: RubyGems
+More options: https://www.openclacky.com/
+
+### Command line
 
 **Requirements:** Ruby >= 3.1.0
 
@@ -84,6 +86,12 @@ Built on a production-ready Rails architecture with one-click deployment, dev/pr
 gem install openclacky
 ```
 
+Or one-line install:
+
+```bash
+/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
+```
+
 ## Quick Start
 
 ### Terminal (CLI)
@@ -95,16 +103,16 @@ openclacky            # start interactive agent in current directory
 ### Web UI
 
 ```bash
-openclacky server     # start the web server (default: http://localhost:7070)
+openclacky server     # default: http://localhost:7070
 ```
 
-Then open **http://localhost:7070** in your browser. You'll get a full-featured chat interface with multi-session support — run separate sessions for coding, copywriting, research, and more, all in parallel.
+Open **http://localhost:7070** for a full chat interface with multi-session support — run coding, copywriting, research sessions in parallel.
 
 Options:
 
 ```bash
-openclacky server --port 8080          # custom port
-openclacky server --host 0.0.0.0      # listen on all interfaces (e.g. remote access)
+openclacky server --port 8080        # custom port
+openclacky server --host 0.0.0.0     # listen on all interfaces (remote access)
 ```
 
 ## Configuration
@@ -114,7 +122,26 @@ $ openclacky
 > /config
 ```
 
-You'll be prompted to set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
+Set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
+
+Supported out of the box: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter** — or any custom endpoint.
+
+## Coding use case
+
+OpenClacky works as a general AI coding assistant — scaffold full-stack apps, add features, or explore unfamiliar codebases:
+
+```bash
+$ openclacky
+> /new my-app        # scaffold a new project
+> Add user auth with email and password
+> How does the payment module work?
+```
+
+## Advanced — Creator Program
+
+Already power users are turning their workflows into vertical AI experts on OpenClacky — encrypted distribution, License management, self-set pricing. Legal, healthcare, financial planning, and more.
+
+Learn more: https://www.openclacky.com/ → Creators
 
 ## Install from Source
 
@@ -125,6 +152,13 @@ bundle install
 bin/clacky
 ```
 
+## Trust & Credibility
+
+- **100% open source** — MIT License, all code public, all decisions traceable
+- **2 years of Agentic R&D** — 3 generations of architecture
+- **16 core tools** — minimal by design
+- **Backed by** MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/clacky-ai/openclacky. Contributors are expected to adhere to the [code of conduct](https://github.com/clacky-ai/openclacky/blob/main/CODE_OF_CONDUCT.md).

data/lib/clacky/agent/cost_tracker.rb

@@ -105,8 +105,25 @@ module Clacky
         cache_write = usage[:cache_creation_input_tokens] || 0
         cache_read = usage[:cache_read_input_tokens] || 0
 
-        # Calculate token delta from previous iteration
-        delta_tokens = total_tokens - @previous_total_tokens
+        # Calculate token delta from previous iteration.
+        #
+        # Two conventions exist for total_tokens across providers:
+        #   - OpenAI (default):    cumulative per-request input+output (grows
+        #                          with history every turn). Delta = total - prev.
+        #   - Anthropic direct:    already the per-turn new compute
+        #                          (raw_input + cache_creation + output).
+        #                          The MessageFormat sets :total_is_per_turn so
+        #                          we use total_tokens directly as the delta.
+        #
+        # Without this branch, Anthropic's per-turn total would be treated as
+        # cumulative and produce negative / nonsensical deltas whenever cached
+        # prefixes make the per-turn new-compute smaller than the previous turn.
+        delta_tokens =
+          if usage[:total_is_per_turn]
+            total_tokens
+          else
+            total_tokens - @previous_total_tokens
+          end
         @previous_total_tokens = total_tokens  # Update for next iteration
 
         {

data/lib/clacky/agent/llm_caller.rb

@@ -54,6 +54,20 @@ module Clacky
         max_retries = 10
         retry_delay = 5
         retries = 0
+
+        # Track whether any of the retry/fallback branches below opened a
+        # "retrying" progress slot via show_progress(progress_type:
+        # "retrying", phase: "active"). If so, we MUST close it before
+        # leaving call_llm — otherwise the UI's legacy shim in
+        # UI2::UIController keeps the :quiet ProgressHandle alive, its
+        # ticker thread keeps running, and the user sees a frozen
+        # "Network failed: ... (681s)" line long after the task finished.
+        #
+        # The close is done in the outer ensure below so it runs on:
+        #   - normal success (response returned)
+        #   - unrecoverable failure (raise propagates out)
+        #   - BadRequestError reasoning-content retry success
+        retrying_progress_opened = false
         # One-shot flag set by the BadRequestError rescue below when the server
         # complained about missing reasoning_content. The subsequent retry will
         # pad every assistant message's reasoning_content, which satisfies
@@ -67,6 +81,7 @@ module Clacky
         thinking_retry_attempted = false
 
         begin
+          begin
           # Use active_messages (Time Machine) when undone, otherwise send full history.
           # to_api strips internal fields and handles orphaned tool_calls.
           messages_to_send = if respond_to?(:active_messages)
@@ -86,6 +101,19 @@ module Clacky
           # Successful response — if we were probing, confirm primary is healthy.
           handle_probe_success if @config.probing?
 
+          # ── Upstream truncation detector ──────────────────────────────────
+          # OpenRouter / Bedrock and other routers sometimes close the SSE
+          # stream mid-tool_use: we receive finish_reason="stop" together with
+          # a syntactically valid tool_call whose `arguments` JSON is empty,
+          # "{}" (placeholder before any key was streamed), or otherwise
+          # unparseable. Treat this as retryable — otherwise the agent would
+          # execute a tool with empty args (often failing cryptically) or
+          # silently exit thinking the task is done.
+          #
+          # Raises UpstreamTruncatedError (a RetryableError) so the rescue
+          # block below handles retry + fallback identically to 5xx/429.
+          detect_upstream_truncation!(response)
+
         rescue Faraday::TimeoutError => e
           # ── Read-timeout path (distinct from connection-level failures) ──
           # Faraday::TimeoutError on our non-streaming POST almost always means
@@ -118,6 +146,7 @@ module Clacky
               phase: "active",
               metadata: { attempt: retries, total: max_retries }
             )
+            retrying_progress_opened = true
             sleep retry_delay
             retry
           else
@@ -144,6 +173,7 @@ module Clacky
               phase: "active",
               metadata: { attempt: retries, total: max_retries }
             )
+            retrying_progress_opened = true
             sleep retry_delay
             retry
           else
@@ -180,6 +210,7 @@ module Clacky
               phase: "active",
             metadata: { attempt: retries, total: current_max }
           )
+          retrying_progress_opened = true
           sleep retry_delay
           retry
         else
@@ -212,7 +243,65 @@ module Clacky
         token_data = track_cost(response[:usage], raw_api_usage: response[:raw_api_usage])
         response[:token_usage] = token_data
 
+        # [DIAG] Log raw client response shape. Only emit when we see the
+        # "finish_reason=stop + non-empty tool_calls" combo, or when any
+        # tool_call's arguments look empty/unparseable — both indicate the
+        # upstream (Bedrock/relay/model) cut the tool_use stream short.
+        # Normal responses produce no log line (too noisy).
+        begin
+          tool_calls = response[:tool_calls] || []
+          if !tool_calls.empty?
+            raw_tcs = tool_calls.map do |c|
+              args_str = c[:arguments].is_a?(String) ? c[:arguments] : c[:arguments].to_s
+              parseable = begin
+                JSON.parse(args_str)
+                true
+              rescue StandardError
+                false
+              end
+              {
+                name: c[:name].to_s,
+                args_len: args_str.length,
+                args_parseable: parseable,
+                args_head: args_str[0, 120]
+              }
+            end
+            truncated_call = raw_tcs.any? { |t| t[:args_len] == 0 || t[:args_len] == 2 || !t[:args_parseable] }
+            suspicious     = response[:finish_reason] == "stop"
+
+            if suspicious || truncated_call
+              Clacky::Logger.warn("llm.response_suspicious",
+                model: current_model,
+                finish_reason: response[:finish_reason].to_s,
+                tool_calls_count: raw_tcs.size,
+                tool_calls: raw_tcs,
+                completion_tokens: token_data[:completion_tokens],
+                ttft_ms: response.dig(:latency, :ttft_ms),
+                combo_stop_with_toolcalls: suspicious,
+                has_truncated_args: truncated_call
+              )
+            end
+          end
+        rescue StandardError => e
+          Clacky::Logger.warn("llm.response_log_failed", error: e.message)
+        end
+
         response
+        ensure
+          # Close any "retrying" progress slot that was opened during the
+          # retry/fallback loop above. The legacy UI shim allocates a
+          # separate :quiet ProgressHandle under the "retrying" key; if it
+          # is never finished its ticker thread keeps running and the user
+          # sees a stale "Network failed: ... (NNN s)" line long after the
+          # task has completed. This ensure runs on:
+          #   - successful retry → close the slot, message is "Recovered"
+          #     so the final frame is informative rather than blank
+          #   - unrecoverable failure that raises out → close the slot so
+          #     the spinner doesn't linger while the error bubbles up
+          if retrying_progress_opened
+            @ui&.show_progress(progress_type: "retrying", phase: "done")
+          end
+        end
       end
 
       # Attempt to activate the provider fallback model for the given primary model.
@@ -269,6 +358,87 @@ module Clacky
            msg.include?("must be provided"))
       end
 
+      # Detect upstream tool-call truncation and raise UpstreamTruncatedError
+      # so the standard RetryableError rescue (with fallback model support)
+      # handles retry identically to 5xx/429.
+      #
+      # Background: OpenRouter routes to Anthropic/Bedrock/etc. and passes
+      # through whatever the upstream sends. If the upstream closes the SSE
+      # stream mid-tool_use (observed with Anthropic at ~127 s TTFT under
+      # load), OpenRouter does NOT surface an error — it emits a valid
+      # `tool_calls[]` whose `arguments` is empty, `"{}"`, or non-parseable
+      # JSON. Without this check the agent would either execute the tool with
+      # empty args or (worse) silently exit thinking the task finished.
+      #
+      # Rule is deliberately narrow: we only intercept the case where the
+      # model streamed literally nothing into the tool_call arguments —
+      # i.e. `nil`, empty string, or the placeholder `"{}"`. Partial/invalid
+      # JSON (e.g. `{"path": "/tmp/x"`) is left to the existing
+      # ArgumentsParser → BadArgumentsError path, because the model already
+      # committed to specific values and feeding the parse error back as a
+      # tool_result lets it self-correct in one round-trip (faster than a
+      # blind retry from scratch).
+      private def detect_upstream_truncation!(response)
+        tool_calls = response[:tool_calls]
+        return if tool_calls.nil? || tool_calls.empty?
+
+        truncated = tool_calls.find { |tc| tool_call_args_truncated?(tc[:arguments]) }
+        return unless truncated
+
+        args_str = truncated[:arguments].is_a?(String) ? truncated[:arguments] : truncated[:arguments].to_s
+        Clacky::Logger.warn("llm.upstream_truncation_detected",
+          model: current_model,
+          tool_name: truncated[:name].to_s,
+          args_len: args_str.length,
+          args_head: args_str[0, 80],
+          finish_reason: response[:finish_reason].to_s,
+          completion_tokens: response.dig(:token_usage, :completion_tokens),
+          ttft_ms: response.dig(:latency, :ttft_ms)
+        )
+
+        # Inject a one-shot [SYSTEM] hint so a plain retry isn't doomed to the
+        # same fate when the truncation correlates with large tool_call args
+        # (e.g. writing a 5000-char file in one go). For infrastructure-level
+        # blips this hint is harmless — the retry usually succeeds on its own
+        # and the hint just sits in history without affecting behaviour.
+        inject_upstream_truncation_hint_if_first(truncated)
+
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Upstream truncated tool_call `#{truncated[:name]}` " \
+          "(args=#{args_str[0, 40].inspect}). Retrying..."
+      end
+
+      # True when a tool_call's arguments field looks COMPLETELY empty —
+      # i.e. the upstream stream was cut before the model wrote any real
+      # content into the arguments JSON.
+      #
+      # Rules:
+      #   - nil / non-String / empty string  → truncated (nothing at all)
+      #   - parses to {} (empty object)      → truncated (placeholder only)
+      #   - anything else (including partial/invalid JSON like `{"path":
+      #     "/tmp/x"` where the model already started writing) → NOT
+      #     truncated by this detector
+      #
+      # Partial-JSON cases are deliberately left to the existing
+      # ArgumentsParser → BadArgumentsError path, which surfaces the parse
+      # error back to the LLM as a tool_result so it can self-correct. That
+      # is more efficient than a blind retry when the model already wrote
+      # most of the args.
+      private def tool_call_args_truncated?(args)
+        return true if args.nil?
+        return true unless args.is_a?(String)
+        return true if args.empty?
+
+        parsed = begin
+          JSON.parse(args)
+        rescue JSON::ParserError
+          # Partial/invalid JSON — let ArgumentsParser handle it downstream.
+          return false
+        end
+
+        parsed.is_a?(Hash) && parsed.empty?
+      end
+
       # On the FIRST Faraday::TimeoutError within a task, append a [SYSTEM]
       # user message to the history instructing the model to break its work
       # into smaller steps. Subsequent timeouts in the same task are ignored
@@ -312,6 +482,54 @@ module Clacky
           "LLM response timed out — asking model to break the task into smaller steps and retrying..."
         )
       end
+
+      # On the FIRST upstream-truncation detection within a task, append a
+      # [SYSTEM] user message nudging the model toward smaller tool_call args.
+      # This guards against the (real but rare) case where the upstream SSE
+      # cut correlates with large tool_call payloads — a plain retry on the
+      # same oversized args would keep tripping the same wire.
+      #
+      # For purely infrastructural truncations (Anthropic edge blip, router
+      # hiccup), the hint is harmless — the retry will succeed and the hint
+      # just sits unused in history. Cheaper than letting the agent burn
+      # through its retry budget on the same oversized payload.
+      #
+      # Same plumbing as inject_large_output_hint_if_first_timeout: one-shot
+      # per task, carries `system_injected: true` so it's hidden from UI
+      # replay and skipped by compression/caching placement logic. Reset per
+      # task via Agent#run (see @task_upstream_truncation_hint_injected).
+      private def inject_upstream_truncation_hint_if_first(truncated_call)
+        return if @task_upstream_truncation_hint_injected
+
+        @task_upstream_truncation_hint_injected = true
+
+        tool_name = truncated_call[:name].to_s
+        hint = "[SYSTEM] The previous response was cut short by the upstream provider " \
+               "before the `#{tool_name}` tool_call finished streaming. " \
+               "The partial tool_call has been discarded. To avoid the same problem on retry, " \
+               "please adapt your approach:\n" \
+               "- Prefer smaller tool_call arguments — large single-shot payloads are more likely to be truncated.\n" \
+               "- For long file content: create the file first with a minimal skeleton via `write`, " \
+               "then append sections one at a time with `edit`.\n" \
+               "- Break large tasks into multiple smaller tool calls instead of one big one.\n" \
+               "- Keep each tool-call argument comfortably under ~2000 characters when possible."
+
+        @history.append({
+          role: "user",
+          content: hint,
+          system_injected: true,
+          task_id: @current_task_id
+        })
+
+        Clacky::Logger.info(
+          "[llm_caller] Upstream truncation — injected 'smaller tool_call args' hint " \
+          "(tool=#{tool_name.inspect})"
+        )
+
+        @ui&.show_warning(
+          "Upstream response was truncated mid tool-call — asking model to use smaller steps and retrying..."
+        )
+      end
     end
   end
 end

data/lib/clacky/agent/message_compressor_helper.rb

@@ -47,11 +47,41 @@ module Clacky
             handle_compression_response(response, compression_context, progress: handle)
             true
           rescue Clacky::AgentInterrupted => e
-            @ui&.log("Idle compression canceled: #{e.message}", level: :info)
+            # User cancelled the idle compression — finish the quiet progress
+            # slot in place so the user sees exactly what happened (rather
+            # than the "Idle detected..." line being silently removed).
+            final = "Idle compression cancelled: #{e.message}"
+            if handle
+              handle.finish(final_message: final)
+            else
+              @ui&.log(final, level: :info)
+            end
             @history.rollback_before(compression_message)
+            Clacky::Logger.info("[idle-compress] cancelled: #{e.message}")
             false
           rescue => e
-            @ui&.log("Idle compression failed: #{e.message}", level: :error)
+            # Compression failed (most commonly: network errors after all
+            # LlmCaller retries exhausted). Previously this only wrote an
+            # @ui.log(:error) that was easy to miss — especially when no
+            # other output followed. Now we:
+            #   1. Replace the active quiet progress line with the error so
+            #      the user always sees *something* where the spinner was.
+            #   2. Emit a show_warning for a more prominent entry.
+            #   3. Persist to Clacky::Logger so post-mortem is possible even
+            #      if the terminal scrollback has rolled past.
+            final = "Idle compression failed: #{e.message}"
+            if handle
+              handle.finish(final_message: final)
+            else
+              @ui&.log(final, level: :error)
+            end
+            @ui&.show_warning(final)
+            Clacky::Logger.warn(
+              "[idle-compress] failed",
+              error_class: e.class.name,
+              error_message: e.message,
+              backtrace: e.backtrace&.first(5)
+            )
             @history.rollback_before(compression_message)
             false
           end