Prompt-Caching, Tool-Ergebnis-Kappung und Kostenerfassung

T1 — Prompt-Caching. Bisher wurde bei jedem Schritt eines Runs der komplette
Prompt neu berechnet, inklusive Tool-Definitionen und System-Prompt, die sich nie
aendern. Bei zehn Schritten und einem 15k-Praefix sind das 150.000 statt 15.000
Eingabe-Tokens.

ChatMessage bekommt dafuer einen eigenen JsonConverter: Der Inhalt geht weiterhin
als String raus, bei gesetztem CacheBreakpoint jedoch als Blockarray mit
cache_control. Beim Lesen werden beide Formate akzeptiert, damit bestehende
ChatContext.json weiter geladen werden koennen.

PromptCache setzt zwei Breakpoints: einen auf den System-Prompt (deckt
Tool-Definitionen und System-Prompt ab) und einen rollierenden auf die letzte
Nachricht mit Inhalt. Vorherige Markierungen werden vorher entfernt, damit sie
sich nicht ansammeln. Aktivierung ueber promptCaching: auto (Default, aktiv fuer
Modelle mit Unterstuetzung), on oder off.

Der wichtigste Test dazu prueft die Praefix-Stabilitaet: Der System-Prompt muss
ueber alle Schritte zeichengleich serialisiert werden. Ein einziger Zeitstempel
darin wuerde den Cache still verwerfen — die Kosten blieben unveraendert, ohne
dass es irgendwo auffiele.

T9 — Usage liest prompt_tokens_details.cached_tokens; die Zahl wird bis in
AgentRunResult durchgereicht. Ohne sie liesse sich die Wirkung nicht belegen.

T2 — Tool-Ergebnisse werden jetzt zentral in ExecuteToolCallAsync gekappt
(maxToolResultChars, Default 16.000). Bisher konnte ein einzelner WebFetch mit
dem 512-KB-Standardlimit rund 130.000 Tokens in EINER Antwort erzeugen; die
Compaction griff erst danach, bezahlt war der Request laengst.

T3 — Die Zusammenfassung beim Kompaktieren laeuft ueber ein konfigurierbares
summaryModel (Default gemini-2.5-flash) statt ueber das teure Agentenmodell.

B4 — AgentRunResult fuehrt Prompt- und Completion-Tokens getrennt; die
Kostenanzeige schaetzte bisher 50/50, real liegt das Verhaeltnis eher bei 95:5.
Die veraltete Preistabelle bleibt offen.

Neue Einstellungen sind im PropertyGrid sichtbar und werden vom AgentEditor bei
neuen Agenten mitgeschrieben.

Alle 91 Tests gruen.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/ClawdDotNet.Core/Engine/AgentEngine.cs

@@ -109,13 +109,17 @@ public sealed class AgentEngine : IAgentMessageRouter
             messages.Add(ChatMessage.User(userMessage));
 
             string? finalMessage = null;
-            var totalTokens = 0;
+            var tally = new TokenTally();
+            var cachingEnabled = PromptCache.IsEnabledFor(agentConfig.PromptCaching, agentConfig.Model);
 
             while (true)
             {
                 ct.ThrowIfCancellationRequested();
                 loopGuard.RecordStep();
 
+                if (cachingEnabled)
+                    PromptCache.ApplyBreakpoints(messages);
+
                 var request = new ChatRequest
                 {
                     Model = agentConfig.Model,
@@ -128,7 +132,7 @@ public sealed class AgentEngine : IAgentMessageRouter
                 var promptTokens = 0;
                 if (response.Usage is not null)
                 {
-                    totalTokens += response.Usage.TotalTokens;
+                    tally.Add(response.Usage);
                     promptTokens = response.Usage.PromptTokens;
                     loopGuard.RecordTokens(response.Usage.TotalTokens);
                 }
@@ -174,16 +178,21 @@ public sealed class AgentEngine : IAgentMessageRouter
 
             sw.Stop();
             logger.LogInformation(
-                "Agent run completed: {AgentId}, steps={Steps}, tokens={Tokens}, duration={Duration}ms",
-                agentConfig.AgentId, loopGuard.Steps, totalTokens, sw.ElapsedMilliseconds);
+                "Agent run completed: {AgentId}, steps={Steps}, tokens={Tokens} (davon {Cached} aus Cache), duration={Duration}ms",
+                agentConfig.AgentId, loopGuard.Steps, tally.Total, tally.Cached, sw.ElapsedMilliseconds);
 
             var result = new AgentRunResult(
                 agentConfig.AgentId,
                 AgentRunStatus.Completed,
                 finalMessage,
                 loopGuard.Steps,
-                totalTokens,
-                sw.Elapsed);
+                tally.Total,
+                sw.Elapsed)
+            {
+                PromptTokens = tally.Prompt,
+                CompletionTokens = tally.Completion,
+                CachedTokens = tally.Cached
+            };
             OnRunCompleted?.Invoke(agentConfig.Model, result);
             return result;
         }
@@ -318,13 +327,17 @@ public sealed class AgentEngine : IAgentMessageRouter
             AddChatEntry(agentConfig.AgentId, "user", userMessage, source);
 
             string? finalMessage = null;
-            var totalTokens = 0;
+            var tally = new TokenTally();
+            var cachingEnabled = PromptCache.IsEnabledFor(agentConfig.PromptCaching, agentConfig.Model);
 
             while (true)
             {
                 ct.ThrowIfCancellationRequested();
                 loopGuard.RecordStep();
 
+                if (cachingEnabled)
+                    PromptCache.ApplyBreakpoints(messages);
+
                 var request = new ChatRequest
                 {
                     Model = agentConfig.Model,
@@ -337,7 +350,7 @@ public sealed class AgentEngine : IAgentMessageRouter
                 var promptTokens = 0;
                 if (response.Usage is not null)
                 {
-                    totalTokens += response.Usage.TotalTokens;
+                    tally.Add(response.Usage);
                     promptTokens = response.Usage.PromptTokens;
                     loopGuard.RecordTokens(response.Usage.TotalTokens);
                 }
@@ -386,7 +399,12 @@ public sealed class AgentEngine : IAgentMessageRouter
             sw.Stop();
             var result = new AgentRunResult(
                 agentConfig.AgentId, AgentRunStatus.Completed, finalMessage,
-                loopGuard.Steps, totalTokens, sw.Elapsed);
+                loopGuard.Steps, tally.Total, sw.Elapsed)
+            {
+                PromptTokens = tally.Prompt,
+                CompletionTokens = tally.Completion,
+                CachedTokens = tally.Cached
+            };
             OnRunCompleted?.Invoke(agentConfig.Model, result);
             return result;
         }
@@ -786,9 +804,18 @@ public sealed class AgentEngine : IAgentMessageRouter
 
             logger.LogDebug("Tool {Tool} completed: success={Success}", toolName, result.Success);
 
-            return result.Success
-                ? result.Content
-                : JsonSerializer.Serialize(new { error = result.ErrorMessage });
+            if (!result.Success)
+                return JsonSerializer.Serialize(new { error = result.ErrorMessage });
+
+            var content = TruncateToolResult(result.Content, agentConfig.MaxToolResultChars);
+            if (content.Length != result.Content.Length)
+            {
+                logger.LogInformation(
+                    "Tool-Ergebnis von {Tool} gekürzt: {Original} → {Limit} Zeichen",
+                    toolName, result.Content.Length, agentConfig.MaxToolResultChars);
+            }
+
+            return content;
         }
         catch (ToolAccessDeniedException ex)
         {
@@ -808,6 +835,42 @@ public sealed class AgentEngine : IAgentMessageRouter
         }
     }
 
+    /// <summary>Sammelt die Token-Zahlen über alle Schritte eines Runs.</summary>
+    private sealed class TokenTally
+    {
+        public int Total { get; private set; }
+        public int Prompt { get; private set; }
+        public int Completion { get; private set; }
+        public int Cached { get; private set; }
+
+        public void Add(Usage usage)
+        {
+            Total += usage.TotalTokens;
+            Prompt += usage.PromptTokens;
+            Completion += usage.CompletionTokens;
+            Cached += usage.CachedTokens;
+        }
+    }
+
+    /// <summary>
+    /// Kürzt ein Tool-Ergebnis, bevor es in den Kontext wandert.
+    ///
+    /// Ohne diese Grenze kann ein einzelner Aufruf den Kontext sprengen — ein WebFetch
+    /// mit dem Standardlimit von 512 KB entspricht rund 130.000 Tokens in EINER
+    /// Tool-Antwort. Die Compaction greift erst danach, der teure Request ist zu dem
+    /// Zeitpunkt längst bezahlt.
+    /// </summary>
+    internal static string TruncateToolResult(string result, int maxChars)
+    {
+        if (maxChars <= 0 || result.Length <= maxChars)
+            return result;
+
+        var omitted = result.Length - maxChars;
+        return result[..maxChars] +
+               $"\n\n[… {omitted:N0} Zeichen gekürzt. Das Ergebnis war zu groß für den Kontext. " +
+               "Grenze die Abfrage ein, wenn du den Rest brauchst.]";
+    }
+
     private static List<ToolDefinition> BuildToolDefinitions(IReadOnlyList<IAgentTool> tools)
     {
         return tools.Select(t => new ToolDefinition

src/ClawdDotNet.Core/Engine/AgentRunResult.cs

@@ -8,7 +8,20 @@ public sealed record AgentRunResult(
     int TokensUsed,
     TimeSpan Duration,
     Exception? Error = null
-);
+)
+{
+    /// <summary>Summe der Eingabe-Tokens über alle Schritte des Runs.</summary>
+    public int PromptTokens { get; init; }
+
+    /// <summary>Summe der Ausgabe-Tokens über alle Schritte des Runs.</summary>
+    public int CompletionTokens { get; init; }
+
+    /// <summary>
+    /// Anteil der Eingabe-Tokens, der aus dem Prompt-Cache kam. Diese Tokens sind bereits
+    /// in <see cref="PromptTokens"/> enthalten, kosten aber nur einen Bruchteil.
+    /// </summary>
+    public int CachedTokens { get; init; }
+}
 
 public enum AgentRunStatus
 {

src/ClawdDotNet.Core/Engine/ContextCompactor.cs

@@ -69,8 +69,12 @@ public sealed class ContextCompactor
                 return true;
         }
 
-        // Stufe 2: Auto-Compaction via LLM
-        await CompactViaLlmAsync(messages, model, ct);
+        // Stufe 2: Auto-Compaction via LLM — bewusst mit dem günstigen Modell.
+        var summaryModel = string.IsNullOrWhiteSpace(guard.SummaryModel)
+            ? model
+            : guard.SummaryModel;
+
+        await CompactViaLlmAsync(messages, summaryModel, ct);
         return true;
     }
 

src/ClawdDotNet.Core/Engine/PromptCache.cs

@@ -0,0 +1,67 @@
+using ClawdDotNet.Core.Api.Models;
+
+namespace ClawdDotNet.Core.Engine;
+
+/// <summary>
+/// Setzt Prompt-Caching-Breakpoints in die Nachrichtenliste.
+///
+/// Hintergrund: In einem Agenten-Run wird bei JEDEM Schritt der komplette Prompt erneut
+/// gesendet und voll berechnet — inklusive Tool-Definitionen und System-Prompt, die sich
+/// nie ändern. Bei zehn Schritten und einem 15k-Präfix sind das 150.000 Eingabe-Tokens
+/// statt 15.000.
+///
+/// Ein Breakpoint markiert das Ende eines stabilen Prompt-Abschnitts. Alles davor wird
+/// beim nächsten Aufruf aus dem Cache gelesen und kostet nur einen Bruchteil.
+///
+/// Zwei Breakpoints werden gesetzt:
+/// 1. auf den System-Prompt — deckt Tool-Definitionen und System-Prompt ab,
+/// 2. rollierend auf die letzte Nachricht — deckt den bereits gelaufenen Gesprächsverlauf ab.
+/// </summary>
+public static class PromptCache
+{
+    /// <summary>
+    /// Modelle, bei denen "auto" das Caching einschaltet. Andere Anbieter ignorieren
+    /// cache_control entweder oder cachen ohnehin automatisch.
+    /// </summary>
+    private static readonly string[] AutoEnabledPrefixes = ["anthropic/"];
+
+    public static bool IsEnabledFor(string setting, string model) => setting?.ToLowerInvariant() switch
+    {
+        "on" => true,
+        "off" => false,
+        _ => AutoEnabledPrefixes.Any(p => model.StartsWith(p, StringComparison.OrdinalIgnoreCase))
+    };
+
+    /// <summary>
+    /// Setzt die Breakpoints neu. Vorherige werden entfernt, damit sich pro Schritt
+    /// nie mehr als die beabsichtigten Markierungen ansammeln.
+    /// </summary>
+    public static void ApplyBreakpoints(List<ChatMessage> messages)
+    {
+        foreach (var msg in messages)
+            msg.CacheBreakpoint = false;
+
+        if (messages.Count == 0)
+            return;
+
+        // 1. System-Prompt — der stabilste Teil überhaupt.
+        var system = messages[0].Role == "system" ? messages[0] : null;
+        if (system?.Content is not null)
+            system.CacheBreakpoint = true;
+
+        // 2. Letzte Nachricht mit Inhalt. Beim nächsten Schritt ist alles bis hierher
+        //    unverändert und wird aus dem Cache gelesen.
+        //    Eine assistant-Nachricht mit tool_calls hat keinen Textinhalt und kann
+        //    deshalb keinen Block tragen — in dem Fall bleibt es beim System-Breakpoint.
+        for (var i = messages.Count - 1; i >= 1; i--)
+        {
+            if (messages[i].Content is null)
+                continue;
+
+            if (!ReferenceEquals(messages[i], system))
+                messages[i].CacheBreakpoint = true;
+
+            break;
+        }
+    }
+}