diff --git a/Models/AgentSettingsViewModel.cs b/Models/AgentSettingsViewModel.cs index a1c7253..05eedfb 100644 --- a/Models/AgentSettingsViewModel.cs +++ b/Models/AgentSettingsViewModel.cs @@ -3,6 +3,16 @@ using ClawdDotNet.Core.Config; namespace ClawdDotNet.Models; +/// Bietet die drei gültigen Prompt-Caching-Werte als Auswahlliste an. +public sealed class PromptCachingConverter : StringConverter +{ + public override bool GetStandardValuesSupported(ITypeDescriptorContext? context) => true; + public override bool GetStandardValuesExclusive(ITypeDescriptorContext? context) => true; + + public override StandardValuesCollection GetStandardValues(ITypeDescriptorContext? context) + => new(new[] { "auto", "on", "off" }); +} + [TypeConverter(typeof(ExpandableObjectConverter))] public sealed class AgentSettingsViewModel { @@ -106,6 +116,42 @@ public sealed class AgentSettingsViewModel set => _config.LoopGuard.CompactionThreshold = Math.Clamp(value, 50, 95) / 100.0; } + [Category("3 - Kontext-Management")] + [DisplayName("Modell für Zusammenfassungen")] + [Description("Modell, mit dem beim Kompaktieren zusammengefasst wird. Leer = Modell des Agenten. " + + "Zusammenfassen ist anspruchslos — ein günstiges Modell spart hier deutlich, " + + "da bis zu 30.000 Zeichen verarbeitet werden.")] + public string SummaryModel + { + get => _config.LoopGuard.SummaryModel; + set => _config.LoopGuard.SummaryModel = value ?? ""; + } + + [Category("3 - Kontext-Management")] + [DisplayName("Max. Zeichen pro Tool-Ergebnis")] + [Description("Längere Tool-Ergebnisse werden gekürzt, bevor sie in den Kontext gelangen. " + + "Ohne Grenze kann ein einzelner Abruf den Kontext sprengen — 512 KB entsprechen " + + "etwa 130.000 Tokens in einer einzigen Antwort.")] + public int MaxToolResultChars + { + get => _config.MaxToolResultChars; + set => _config.MaxToolResultChars = Math.Max(1_000, value); + } + + // ──────────────── Kosten ──────────────── + + [Category("5 - Kosten")] + [DisplayName("Prompt-Caching")] + [Description("auto = für Modelle aktivieren, die es unterstützen; on = erzwingen; off = aus. " + + "Spart erheblich, weil jeder Schritt eines Runs den kompletten Prompt erneut sendet — " + + "System-Prompt und Tool-Definitionen also dutzendfach.")] + [TypeConverter(typeof(PromptCachingConverter))] + public string PromptCaching + { + get => _config.PromptCaching; + set => _config.PromptCaching = string.IsNullOrWhiteSpace(value) ? "auto" : value; + } + // ──────────────── Tools (Read-Only) ──────────────── [Category("4 - Tools")] diff --git a/docs/Bestandsaufnahme-2026-07.md b/docs/Bestandsaufnahme-2026-07.md index f2282d2..e16b787 100644 --- a/docs/Bestandsaufnahme-2026-07.md +++ b/docs/Bestandsaufnahme-2026-07.md @@ -532,11 +532,14 @@ Siehe K3. 5. S3 API-Key-Leak **Kurzfristig — größter Nutzen pro Aufwand** -6. T1 Prompt-Caching -7. T2 Tool-Ergebnisse kappen (= B5) -8. T3 Günstiges Compaction-Modell -9. B4 Kostenerfassung korrigieren +6. ~~T1 Prompt-Caching~~ ✅ umgesetzt (inkl. T9 `cached_tokens`) +7. ~~T2 Tool-Ergebnisse kappen (= B5)~~ ✅ umgesetzt +8. ~~T3 Günstiges Compaction-Modell~~ ✅ umgesetzt +9. ~~B4 Kostenerfassung korrigieren~~ ✅ teilweise: Prompt/Completion werden jetzt + getrennt erfasst statt 50/50 geschätzt. Offen bleibt die veraltete, hartcodierte + Preistabelle (`ModelPricing`) — Preise sollten vom `/models`-Endpoint kommen. 10. B12 Retry/Backoff +11. T4 Proaktiv statt reaktiv kompaktieren **Mittelfristig — Fundament** 11. S1 DatabaseTool absichern diff --git a/frm_main.cs b/frm_main.cs index cc8bed2..8821e26 100644 --- a/frm_main.cs +++ b/frm_main.cs @@ -289,7 +289,10 @@ public partial class frm_main : Form /// private void OnEngineRunCompleted(string model, AgentRunResult result) { - _statusService?.RecordUsage(model, result.TokensUsed / 2, result.TokensUsed / 2); + // Echte Aufteilung statt 50/50: In Agenten-Loops liegt das Verhältnis eher bei + // 95:5, und da Ausgabe-Tokens ein Vielfaches kosten, war die alte Schätzung + // um ein Mehrfaches daneben. + _statusService?.RecordUsage(model, result.PromptTokens, result.CompletionTokens); if (IsDisposed || !IsHandleCreated) return; BeginInvoke(() => diff --git a/src/ClawdDotNet.Core/Api/Models/ChatMessage.cs b/src/ClawdDotNet.Core/Api/Models/ChatMessage.cs index 6f57dfc..2d5007e 100644 --- a/src/ClawdDotNet.Core/Api/Models/ChatMessage.cs +++ b/src/ClawdDotNet.Core/Api/Models/ChatMessage.cs @@ -1,24 +1,33 @@ +using System.Text.Json; using System.Text.Json.Serialization; namespace ClawdDotNet.Core.Api.Models; +[JsonConverter(typeof(ChatMessageConverter))] public sealed class ChatMessage { - [JsonPropertyName("role")] public string Role { get; set; } = ""; - [JsonPropertyName("content")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string? Content { get; set; } - [JsonPropertyName("tool_calls")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public List? ToolCalls { get; set; } - [JsonPropertyName("tool_call_id")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string? ToolCallId { get; set; } + /// + /// Setzt einen Prompt-Caching-Breakpoint auf diese Nachricht. + /// + /// Alles, was im Prompt VOR dem Breakpoint steht (Tool-Definitionen, System-Prompt, + /// vorherige Nachrichten), wird beim nächsten Aufruf aus dem Cache gelesen und + /// kostet nur einen Bruchteil. Der Inhalt wird dann als Block-Array statt als + /// einfacher String serialisiert. + /// + /// Wichtig: Der Prompt-Abschnitt vor dem Breakpoint muss zwischen zwei Aufrufen + /// zeichengenau identisch sein, sonst greift der Cache nicht. + /// + [JsonIgnore] + public bool CacheBreakpoint { get; set; } + public static ChatMessage System(string content) => new() { Role = "system", Content = content }; public static ChatMessage User(string content) => new() { Role = "user", Content = content }; public static ChatMessage Assistant(string content) => new() { Role = "assistant", Content = content }; @@ -36,3 +45,136 @@ public sealed class ChatMessage Content = content }; } + +/// +/// Serialisiert . Der Inhalt geht normalerweise als einfacher +/// String raus; ist ein gesetzt, stattdessen +/// als Block-Array mit cache_control — das Format, das Anbieter für Prompt-Caching +/// erwarten. +/// +/// Beim Lesen werden beide Formate akzeptiert: Antworten liefern den Inhalt als String, +/// gespeicherte Kontexte können ihn als Array enthalten. +/// +public sealed class ChatMessageConverter : JsonConverter +{ + public override ChatMessage Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) + { + if (reader.TokenType != JsonTokenType.StartObject) + throw new JsonException("ChatMessage: Objekt erwartet."); + + var message = new ChatMessage(); + + while (reader.Read()) + { + if (reader.TokenType == JsonTokenType.EndObject) + return message; + + if (reader.TokenType != JsonTokenType.PropertyName) + continue; + + var propertyName = reader.GetString(); + reader.Read(); + + switch (propertyName) + { + case "role": + message.Role = reader.GetString() ?? ""; + break; + + case "content": + message.Content = ReadContent(ref reader); + break; + + case "tool_calls": + message.ToolCalls = reader.TokenType == JsonTokenType.Null + ? null + : JsonSerializer.Deserialize>(ref reader, options); + break; + + case "tool_call_id": + message.ToolCallId = reader.GetString(); + break; + + default: + reader.Skip(); + break; + } + } + + throw new JsonException("ChatMessage: unerwartetes Ende."); + } + + /// Nimmt den Inhalt als String oder als Block-Array entgegen. + private static string? ReadContent(ref Utf8JsonReader reader) + { + if (reader.TokenType == JsonTokenType.Null) + return null; + + if (reader.TokenType == JsonTokenType.String) + return reader.GetString(); + + if (reader.TokenType != JsonTokenType.StartArray) + { + reader.Skip(); + return null; + } + + // Block-Array: die text-Anteile zusammenführen. + var parts = new List(); + while (reader.Read() && reader.TokenType != JsonTokenType.EndArray) + { + if (reader.TokenType != JsonTokenType.StartObject) + { + reader.Skip(); + continue; + } + + using var block = JsonDocument.ParseValue(ref reader); + if (block.RootElement.TryGetProperty("text", out var text) && + text.GetString() is { } value) + { + parts.Add(value); + } + } + + return parts.Count > 0 ? string.Join("", parts) : null; + } + + public override void Write(Utf8JsonWriter writer, ChatMessage value, JsonSerializerOptions options) + { + writer.WriteStartObject(); + writer.WriteString("role", value.Role); + + if (value.Content is not null) + { + if (value.CacheBreakpoint) + { + // [{ "type": "text", "text": "…", "cache_control": { "type": "ephemeral" } }] + writer.WriteStartArray("content"); + writer.WriteStartObject(); + writer.WriteString("type", "text"); + writer.WriteString("text", value.Content); + writer.WriteStartObject("cache_control"); + writer.WriteString("type", "ephemeral"); + writer.WriteEndObject(); + writer.WriteEndObject(); + writer.WriteEndArray(); + } + else + { + writer.WriteString("content", value.Content); + } + } + + if (value.ToolCalls is { Count: > 0 }) + { + writer.WritePropertyName("tool_calls"); + JsonSerializer.Serialize(writer, value.ToolCalls, options); + } + + if (value.ToolCallId is not null) + writer.WriteString("tool_call_id", value.ToolCallId); + + writer.WriteEndObject(); + } +} diff --git a/src/ClawdDotNet.Core/Api/Models/ChatResponse.cs b/src/ClawdDotNet.Core/Api/Models/ChatResponse.cs index 70bb504..f10b057 100644 --- a/src/ClawdDotNet.Core/Api/Models/ChatResponse.cs +++ b/src/ClawdDotNet.Core/Api/Models/ChatResponse.cs @@ -42,6 +42,23 @@ public sealed class Usage [JsonPropertyName("total_tokens")] public int TotalTokens { get; set; } + + [JsonPropertyName("prompt_tokens_details")] + public PromptTokensDetails? PromptTokensDetails { get; set; } + + /// + /// Anteil der Prompt-Tokens, der aus dem Cache gelesen wurde. Nur damit lässt sich + /// belegen, ob das Prompt-Caching tatsächlich greift — ein still wirkungsloser + /// Cache wäre sonst nicht zu bemerken. + /// + [JsonIgnore] + public int CachedTokens => PromptTokensDetails?.CachedTokens ?? 0; +} + +public sealed class PromptTokensDetails +{ + [JsonPropertyName("cached_tokens")] + public int CachedTokens { get; set; } } public sealed class ApiError diff --git a/src/ClawdDotNet.Core/ClawdDotNet.Core.csproj b/src/ClawdDotNet.Core/ClawdDotNet.Core.csproj index 70c7d29..a92ce0f 100644 --- a/src/ClawdDotNet.Core/ClawdDotNet.Core.csproj +++ b/src/ClawdDotNet.Core/ClawdDotNet.Core.csproj @@ -7,6 +7,10 @@ ClawdDotNet.Core + + + + diff --git a/src/ClawdDotNet.Core/Config/AgentConfig.cs b/src/ClawdDotNet.Core/Config/AgentConfig.cs index ef4658f..0365fd9 100644 --- a/src/ClawdDotNet.Core/Config/AgentConfig.cs +++ b/src/ClawdDotNet.Core/Config/AgentConfig.cs @@ -88,6 +88,24 @@ public sealed class AgentConfig [JsonPropertyName("loopGuard")] public LoopGuardConfig LoopGuard { get; set; } = new(); + + /// + /// Prompt-Caching: "auto" (Default), "on" oder "off". + /// + /// Bei "auto" wird es für Modelle aktiviert, die cache_control unterstützen. + /// Der Nutzen ist erheblich, weil jeder Schritt eines Runs den kompletten Prompt + /// erneut sendet — System-Prompt und Tool-Definitionen also dutzendfach. + /// + [JsonPropertyName("promptCaching")] + public string PromptCaching { get; set; } = "auto"; + + /// + /// Maximale Länge eines einzelnen Tool-Ergebnisses in Zeichen, bevor es gekürzt in + /// den Kontext wandert. Ohne Grenze kann ein einziger Abruf den gesamten Kontext + /// sprengen (ein WebFetch mit 512 KB entspricht etwa 130.000 Tokens). + /// + [JsonPropertyName("maxToolResultChars")] + public int MaxToolResultChars { get; set; } = 16_000; } public sealed class SchedulerConfig @@ -137,6 +155,16 @@ public sealed class LoopGuardConfig [JsonPropertyName("compactionThreshold")] public double CompactionThreshold { get; set; } = 0.80; + /// + /// Modell für die Zusammenfassung beim Kompaktieren. Leer = Modell des Agenten. + /// + /// Zusammenfassen ist eine anspruchslose Aufgabe; sie mit einem teuren Modell zu + /// erledigen kostet leicht mehr als der halbe Run, weil bis zu 30.000 Zeichen + /// verarbeitet werden. + /// + [JsonPropertyName("summaryModel")] + public string SummaryModel { get; set; } = "google/gemini-2.5-flash"; + [JsonIgnore] public TimeSpan Timeout => TimeSpan.FromSeconds(TimeoutSeconds); } diff --git a/src/ClawdDotNet.Core/Engine/AgentEngine.cs b/src/ClawdDotNet.Core/Engine/AgentEngine.cs index 4f2d993..d93c067 100644 --- a/src/ClawdDotNet.Core/Engine/AgentEngine.cs +++ b/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 } } + /// Sammelt die Token-Zahlen über alle Schritte eines Runs. + 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; + } + } + + /// + /// 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. + /// + 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 BuildToolDefinitions(IReadOnlyList tools) { return tools.Select(t => new ToolDefinition diff --git a/src/ClawdDotNet.Core/Engine/AgentRunResult.cs b/src/ClawdDotNet.Core/Engine/AgentRunResult.cs index 66dffc4..42978bb 100644 --- a/src/ClawdDotNet.Core/Engine/AgentRunResult.cs +++ b/src/ClawdDotNet.Core/Engine/AgentRunResult.cs @@ -8,7 +8,20 @@ public sealed record AgentRunResult( int TokensUsed, TimeSpan Duration, Exception? Error = null -); +) +{ + /// Summe der Eingabe-Tokens über alle Schritte des Runs. + public int PromptTokens { get; init; } + + /// Summe der Ausgabe-Tokens über alle Schritte des Runs. + public int CompletionTokens { get; init; } + + /// + /// Anteil der Eingabe-Tokens, der aus dem Prompt-Cache kam. Diese Tokens sind bereits + /// in enthalten, kosten aber nur einen Bruchteil. + /// + public int CachedTokens { get; init; } +} public enum AgentRunStatus { diff --git a/src/ClawdDotNet.Core/Engine/ContextCompactor.cs b/src/ClawdDotNet.Core/Engine/ContextCompactor.cs index 0fc099d..469c189 100644 --- a/src/ClawdDotNet.Core/Engine/ContextCompactor.cs +++ b/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; } diff --git a/src/ClawdDotNet.Core/Engine/PromptCache.cs b/src/ClawdDotNet.Core/Engine/PromptCache.cs new file mode 100644 index 0000000..d9548b0 --- /dev/null +++ b/src/ClawdDotNet.Core/Engine/PromptCache.cs @@ -0,0 +1,67 @@ +using ClawdDotNet.Core.Api.Models; + +namespace ClawdDotNet.Core.Engine; + +/// +/// 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. +/// +public static class PromptCache +{ + /// + /// Modelle, bei denen "auto" das Caching einschaltet. Andere Anbieter ignorieren + /// cache_control entweder oder cachen ohnehin automatisch. + /// + 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)) + }; + + /// + /// Setzt die Breakpoints neu. Vorherige werden entfernt, damit sich pro Schritt + /// nie mehr als die beabsichtigten Markierungen ansammeln. + /// + public static void ApplyBreakpoints(List 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; + } + } +} diff --git a/src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs b/src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs index d533ea2..80a183c 100644 --- a/src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs +++ b/src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs @@ -326,13 +326,16 @@ public sealed class AgentEditorTool : IAgentTool tools = new Dictionary(), scheduler = (object?)null, toolJobs = Array.Empty(), + promptCaching = "auto", + maxToolResultChars = 16000, loopGuard = new { maxSteps = 20, maxCumulativeTokens = 500000, timeoutSeconds = 600, maxContextTokens = 100000, - compactionThreshold = 0.8 + compactionThreshold = 0.8, + summaryModel = "google/gemini-2.5-flash" } }; await File.WriteAllTextAsync( diff --git a/tests/ClawdDotNet.Core.Tests/Api/ChatMessageSerializationTests.cs b/tests/ClawdDotNet.Core.Tests/Api/ChatMessageSerializationTests.cs new file mode 100644 index 0000000..47028a2 --- /dev/null +++ b/tests/ClawdDotNet.Core.Tests/Api/ChatMessageSerializationTests.cs @@ -0,0 +1,149 @@ +using System.Text.Json; +using ClawdDotNet.Core.Api.Models; +using Shouldly; + +namespace ClawdDotNet.Core.Tests.Api; + +public sealed class ChatMessageSerializationTests +{ + private static string Serialize(ChatMessage m) => JsonSerializer.Serialize(m); + private static ChatMessage Deserialize(string json) => JsonSerializer.Deserialize(json)!; + + // ═══════════════════════════════════════════════════════════ + // Standardformat + // ═══════════════════════════════════════════════════════════ + + [Fact] + public void Ohne_Breakpoint_bleibt_der_Inhalt_ein_einfacher_String() + { + var json = Serialize(ChatMessage.User("Hallo")); + + json.ShouldBe("""{"role":"user","content":"Hallo"}"""); + } + + [Fact] + public void Nullwerte_werden_weggelassen() + { + var json = Serialize(ChatMessage.Assistant("Antwort")); + + json.ShouldNotContain("tool_calls"); + json.ShouldNotContain("tool_call_id"); + } + + [Fact] + public void ToolAntwort_traegt_ihre_ToolCallId() + { + var json = Serialize(ChatMessage.ToolResponse("call_42", "Ergebnis")); + + json.ShouldBe("""{"role":"tool","content":"Ergebnis","tool_call_id":"call_42"}"""); + } + + [Fact] + public void AssistantMitToolCalls_serialisiert_die_Aufrufe() + { + var msg = ChatMessage.AssistantWithToolCalls([ + new ToolCall { Id = "c1", Function = new ToolCallFunction { Name = "FileRW", Arguments = "{}" } } + ]); + + var json = Serialize(msg); + + json.ShouldContain("tool_calls"); + json.ShouldContain("FileRW"); + json.ShouldNotContain("\"content\"", Case.Sensitive); + } + + // ═══════════════════════════════════════════════════════════ + // Cache-Breakpoint + // ═══════════════════════════════════════════════════════════ + + [Fact] + public void Mit_Breakpoint_wird_der_Inhalt_zum_Block_mit_cache_control() + { + var msg = ChatMessage.System("Du bist ein Agent."); + msg.CacheBreakpoint = true; + + var json = Serialize(msg); + + json.ShouldBe( + """{"role":"system","content":[{"type":"text","text":"Du bist ein Agent.","cache_control":{"type":"ephemeral"}}]}"""); + } + + [Fact] + public void Der_Breakpoint_selbst_wird_nicht_als_Feld_serialisiert() + { + var msg = ChatMessage.User("Text"); + msg.CacheBreakpoint = true; + + Serialize(msg).ShouldNotContain("CacheBreakpoint", Case.Insensitive); + } + + // ═══════════════════════════════════════════════════════════ + // Deserialisierung: beide Formate + // ═══════════════════════════════════════════════════════════ + + [Fact] + public void Inhalt_als_String_wird_gelesen() + { + var msg = Deserialize("""{"role":"assistant","content":"Antwort"}"""); + + msg.Role.ShouldBe("assistant"); + msg.Content.ShouldBe("Antwort"); + } + + [Fact] + public void Inhalt_als_Blockarray_wird_gelesen() + { + // So sieht ein persistierter Kontext aus, der mit Breakpoint geschrieben wurde. + var msg = Deserialize( + """{"role":"system","content":[{"type":"text","text":"Prompt","cache_control":{"type":"ephemeral"}}]}"""); + + msg.Content.ShouldBe("Prompt"); + } + + [Fact] + public void Mehrere_Textbloecke_werden_zusammengefuehrt() + { + var msg = Deserialize( + """{"role":"user","content":[{"type":"text","text":"Teil A"},{"type":"text","text":" Teil B"}]}"""); + + msg.Content.ShouldBe("Teil A Teil B"); + } + + [Fact] + public void Fehlender_Inhalt_wird_zu_null() + { + var msg = Deserialize("""{"role":"assistant","tool_calls":[]}"""); + + msg.Content.ShouldBeNull(); + } + + [Fact] + public void Unbekannte_Felder_stoeren_nicht() + { + var msg = Deserialize("""{"role":"user","content":"Text","reasoning":"…","annotations":[1,2]}"""); + + msg.Content.ShouldBe("Text"); + } + + [Fact] + public void RoundTrip_erhaelt_alle_Felder() + { + var original = ChatMessage.ToolResponse("call_7", "Das Ergebnis"); + + var restored = Deserialize(Serialize(original)); + + restored.Role.ShouldBe("tool"); + restored.Content.ShouldBe("Das Ergebnis"); + restored.ToolCallId.ShouldBe("call_7"); + } + + [Fact] + public void RoundTrip_erhaelt_Umlaute_und_Emoji() + { + var original = ChatMessage.User("Grüße aus München 🦀 — größer & schöner"); + + var restored = Deserialize(Serialize(original)); + + restored.Content.ShouldBe("Grüße aus München 🦀 — größer & schöner"); + } +} diff --git a/tests/ClawdDotNet.Core.Tests/Engine/PromptCacheTests.cs b/tests/ClawdDotNet.Core.Tests/Engine/PromptCacheTests.cs new file mode 100644 index 0000000..62abf57 --- /dev/null +++ b/tests/ClawdDotNet.Core.Tests/Engine/PromptCacheTests.cs @@ -0,0 +1,159 @@ +using System.Text.Json; +using ClawdDotNet.Core.Api.Models; +using ClawdDotNet.Core.Engine; +using ClawdDotNet.Core.Tests.Infrastructure; +using Shouldly; + +namespace ClawdDotNet.Core.Tests.Engine; + +public sealed class PromptCacheTests +{ + // ═══════════════════════════════════════════════════════════ + // Aktivierung + // ═══════════════════════════════════════════════════════════ + + [Theory] + [InlineData("auto", "anthropic/claude-sonnet-4-5", true)] + [InlineData("auto", "anthropic/claude-haiku-4.5", true)] + [InlineData("auto", "openai/gpt-4o", false)] + [InlineData("auto", "google/gemini-2.5-flash", false)] + [InlineData("on", "openai/gpt-4o", true)] + [InlineData("off", "anthropic/claude-sonnet-4-5", false)] + [InlineData("OFF", "anthropic/claude-sonnet-4-5", false)] + public void Aktivierung_richtet_sich_nach_Einstellung_und_Modell(string setting, string model, bool expected) + { + PromptCache.IsEnabledFor(setting, model).ShouldBe(expected); + } + + // ═══════════════════════════════════════════════════════════ + // Platzierung der Breakpoints + // ═══════════════════════════════════════════════════════════ + + [Fact] + public void Der_SystemPrompt_bekommt_einen_Breakpoint() + { + var messages = Conversation.Start("System").User("Frage").Build(); + + PromptCache.ApplyBreakpoints(messages); + + messages[0].Role.ShouldBe("system"); + messages[0].CacheBreakpoint.ShouldBeTrue(); + } + + [Fact] + public void Die_letzte_Nachricht_mit_Inhalt_bekommt_einen_rollierenden_Breakpoint() + { + var messages = Conversation.Start().User("A").Assistant("B").User("C").Build(); + + PromptCache.ApplyBreakpoints(messages); + + messages[^1].CacheBreakpoint.ShouldBeTrue(); + messages[^1].Content.ShouldBe("C"); + } + + [Fact] + public void Eine_AssistantNachricht_ohne_Inhalt_traegt_keinen_Breakpoint() + { + // assistant mit tool_calls hat keinen Textinhalt und kann keinen Block tragen. + var messages = Conversation.Start().User("A").Build(); + messages.Add(ChatMessage.AssistantWithToolCalls([ + new ToolCall { Id = "c1", Function = new ToolCallFunction { Name = "T", Arguments = "{}" } } + ])); + + PromptCache.ApplyBreakpoints(messages); + + messages[^1].CacheBreakpoint.ShouldBeFalse(); + messages.Count(m => m.CacheBreakpoint).ShouldBeGreaterThan(0, "der System-Breakpoint muss bleiben"); + } + + [Fact] + public void Es_werden_hoechstens_zwei_Breakpoints_gesetzt() + { + // Anbieter erlauben nur eine begrenzte Zahl — sie dürfen sich nicht ansammeln. + var messages = Conversation.Start().Repeat(10).Build(); + + PromptCache.ApplyBreakpoints(messages); + + messages.Count(m => m.CacheBreakpoint).ShouldBeLessThanOrEqualTo(2); + } + + [Fact] + public void Wiederholtes_Anwenden_sammelt_keine_Breakpoints_an() + { + var messages = Conversation.Start().Repeat(3).Build(); + + PromptCache.ApplyBreakpoints(messages); + messages.Add(ChatMessage.User("Noch eine Frage")); + PromptCache.ApplyBreakpoints(messages); + messages.Add(ChatMessage.User("Und noch eine")); + PromptCache.ApplyBreakpoints(messages); + + messages.Count(m => m.CacheBreakpoint).ShouldBeLessThanOrEqualTo(2); + messages[^1].CacheBreakpoint.ShouldBeTrue("der Breakpoint muss mitwandern"); + } + + [Fact] + public void Eine_leere_Liste_fuehrt_nicht_zu_einem_Fehler() + { + var messages = new List(); + + Should.NotThrow(() => PromptCache.ApplyBreakpoints(messages)); + } + + // ═══════════════════════════════════════════════════════════ + // Präfix-Stabilität — der entscheidende Test + // ═══════════════════════════════════════════════════════════ + + /// + /// Der gecachte Prompt-Abschnitt muss zwischen zwei Schritten zeichengenau identisch + /// sein. Ein einziger Zeitstempel im System-Prompt würde den Cache bei jedem Schritt + /// verwerfen — die Kosten blieben unverändert, ohne dass es irgendwo auffiele. + /// Genau davor schützt dieser Test. + /// + [Fact] + public async Task Der_Praefix_bleibt_ueber_alle_Schritte_zeichengleich() + { + var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok")); + var agent = fixture.AddAgent("agent-cache", "TestTool"); + agent.Model = "anthropic/claude-sonnet-4-5"; + agent.PromptCaching = "on"; + + // Acht Tool-Schritte, dann eine Textantwort. + for (var i = 0; i < 8; i++) + fixture.Client.RespondsWithToolCall("TestTool"); + fixture.Client.RespondsWithText("Fertig"); + + await fixture.Engine.ChatAsync(agent, "Los", "test-instance", default); + + fixture.Client.ReceivedRequests.Count.ShouldBe(9); + + // Die system-Nachricht ist der stabile Präfix — sie muss in jedem Request + // byte-identisch serialisiert werden. + var systemPayloads = fixture.Client.ReceivedRequests + .Select(r => JsonSerializer.Serialize(r.Messages[0])) + .Distinct() + .ToList(); + + systemPayloads.Count.ShouldBe(1, + "der System-Prompt muss über alle Schritte hinweg identisch serialisiert werden:\n" + + string.Join("\n", systemPayloads)); + + systemPayloads[0].ShouldContain("cache_control"); + } + + [Fact] + public async Task Ohne_Caching_enthaelt_der_Request_kein_cache_control() + { + var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok")); + var agent = fixture.AddAgent("agent-nocache", "TestTool"); + agent.Model = "openai/gpt-4o"; + agent.PromptCaching = "auto"; // bei diesem Modell also aus + + fixture.Client.RespondsWithText("Fertig"); + + await fixture.Engine.ChatAsync(agent, "Los", "test-instance", default); + + var json = JsonSerializer.Serialize(fixture.Client.ReceivedRequests[0].Messages); + json.ShouldNotContain("cache_control"); + } +} diff --git a/tests/ClawdDotNet.Core.Tests/Engine/TokenAccountingTests.cs b/tests/ClawdDotNet.Core.Tests/Engine/TokenAccountingTests.cs new file mode 100644 index 0000000..c8e70c1 --- /dev/null +++ b/tests/ClawdDotNet.Core.Tests/Engine/TokenAccountingTests.cs @@ -0,0 +1,161 @@ +using ClawdDotNet.Core.Api.Models; +using ClawdDotNet.Core.Config; +using ClawdDotNet.Core.Engine; +using ClawdDotNet.Core.Tests.Infrastructure; +using Shouldly; + +namespace ClawdDotNet.Core.Tests.Engine; + +public sealed class TokenAccountingTests +{ + // ═══════════════════════════════════════════════════════════ + // B4 — Prompt und Completion getrennt erfassen + // ═══════════════════════════════════════════════════════════ + + [Fact] + public async Task Prompt_und_Completion_werden_getrennt_aufsummiert() + { + // Bisher schätzte die UI 50/50. Real liegt das Verhältnis eher bei 95:5 — + // und da Ausgabe-Tokens ein Vielfaches kosten, war die Kostenanzeige + // um ein Mehrfaches daneben. + var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok")); + var agent = fixture.AddAgent("agent-tokens", "TestTool"); + + fixture.Client + .RespondsWithText("Fertig", new Usage + { + PromptTokens = 9_500, + CompletionTokens = 500, + TotalTokens = 10_000 + }); + + var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default); + + result.PromptTokens.ShouldBe(9_500); + result.CompletionTokens.ShouldBe(500); + result.TokensUsed.ShouldBe(10_000); + } + + [Fact] + public async Task Ueber_mehrere_Schritte_wird_korrekt_summiert() + { + var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok")); + var agent = fixture.AddAgent("agent-sum", "TestTool"); + + fixture.Client + .RespondsWithToolCall("TestTool") // 100 / 20 / 120 laut Fake + .RespondsWithToolCall("TestTool") + .RespondsWithText("Fertig"); + + var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default); + + result.StepCount.ShouldBe(3); + result.PromptTokens.ShouldBe(300); + result.CompletionTokens.ShouldBe(60); + result.TokensUsed.ShouldBe(360); + } + + // ═══════════════════════════════════════════════════════════ + // T9 — Cache-Wirkung messbar machen + // ═══════════════════════════════════════════════════════════ + + [Fact] + public async Task Gecachte_Tokens_werden_durchgereicht() + { + // Ohne diese Zahl liesse sich nicht belegen, ob das Prompt-Caching greift — + // ein still wirkungsloser Cache wäre sonst nicht zu bemerken. + var fixture = new EngineFixture(); + var agent = fixture.AddAgent("agent-cached"); + + fixture.Client.RespondsWithText("Fertig", new Usage + { + PromptTokens = 20_000, + CompletionTokens = 300, + TotalTokens = 20_300, + PromptTokensDetails = new PromptTokensDetails { CachedTokens = 18_000 } + }); + + var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default); + + result.CachedTokens.ShouldBe(18_000); + } + + [Fact] + public void Fehlende_Cache_Angaben_ergeben_null_statt_eines_Fehlers() + { + var usage = new Usage { PromptTokens = 100, CompletionTokens = 10, TotalTokens = 110 }; + + usage.CachedTokens.ShouldBe(0); + } + + // ═══════════════════════════════════════════════════════════ + // T3 — Compaction läuft mit dem günstigen Modell + // ═══════════════════════════════════════════════════════════ + + [Fact] + public async Task Die_Zusammenfassung_nutzt_das_guenstige_Modell() + { + var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung."); + var compactor = new ContextCompactor(client, TestLogging.Factory); + + var guard = new LoopGuardConfig + { + MaxContextTokens = 1_000, + CompactionThreshold = 0.5, + SummaryModel = "google/gemini-2.5-flash" + }; + + var messages = Conversation.Start().Repeat(10).Build(); + + await compactor.CompactIfNeededAsync(messages, 50_000, guard, "anthropic/claude-opus-4", default); + + client.ReceivedRequests.ShouldNotBeEmpty(); + client.ReceivedRequests[0].Model.ShouldBe("google/gemini-2.5-flash", + "Zusammenfassen ist anspruchslos und darf nicht das teure Agentenmodell belegen"); + } + + [Fact] + public async Task Ohne_konfiguriertes_SummaryModel_wird_das_Agentenmodell_verwendet() + { + var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung."); + var compactor = new ContextCompactor(client, TestLogging.Factory); + + var guard = new LoopGuardConfig + { + MaxContextTokens = 1_000, + CompactionThreshold = 0.5, + SummaryModel = "" + }; + + var messages = Conversation.Start().Repeat(10).Build(); + + await compactor.CompactIfNeededAsync(messages, 50_000, guard, "anthropic/claude-opus-4", default); + + client.ReceivedRequests[0].Model.ShouldBe("anthropic/claude-opus-4"); + } + + // ═══════════════════════════════════════════════════════════ + // Nur der wegfallende Teil wird zusammengefasst + // ═══════════════════════════════════════════════════════════ + + [Fact] + public async Task Der_erhaltene_Tail_geht_nicht_in_den_Zusammenfassungs_Aufruf() + { + // Der Tail bleibt wörtlich erhalten — ihn zusätzlich zusammenzufassen + // wäre doppelt bezahlter Kontext. + var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung."); + var compactor = new ContextCompactor(client, TestLogging.Factory); + + var guard = new LoopGuardConfig { MaxContextTokens = 1_000, CompactionThreshold = 0.5 }; + + var messages = Conversation.Start() + .Repeat(8) + .User("EINZIGARTIGE-LETZTE-NACHRICHT") + .Build(); + + await compactor.CompactIfNeededAsync(messages, 50_000, guard, "test/model", default); + + var summaryPrompt = client.ReceivedRequests[0].Messages.Last().Content!; + summaryPrompt.ShouldNotContain("EINZIGARTIGE-LETZTE-NACHRICHT"); + } +} diff --git a/tests/ClawdDotNet.Core.Tests/Engine/ToolResultTruncationTests.cs b/tests/ClawdDotNet.Core.Tests/Engine/ToolResultTruncationTests.cs new file mode 100644 index 0000000..e8bddeb --- /dev/null +++ b/tests/ClawdDotNet.Core.Tests/Engine/ToolResultTruncationTests.cs @@ -0,0 +1,79 @@ +using ClawdDotNet.Core.Engine; +using ClawdDotNet.Core.Tests.Infrastructure; +using Shouldly; + +namespace ClawdDotNet.Core.Tests.Engine; + +/// +/// T2 aus der Token-Analyse: Ein einzelnes Tool-Ergebnis konnte den Kontext sprengen. +/// Ein WebFetch mit dem Standardlimit von 512 KB entspricht rund 130.000 Tokens in +/// EINER Antwort — die Compaction greift erst danach, bezahlt ist der Request längst. +/// +public sealed class ToolResultTruncationTests +{ + [Fact] + public async Task Ein_riesiges_Toolergebnis_wird_gekappt_bevor_es_in_den_Kontext_geht() + { + var riesig = new string('x', 500_000); + var fixture = new EngineFixture().WithTool(FakeTool.Returning(riesig)); + var agent = fixture.AddAgent("agent-trunc", "TestTool"); + agent.MaxToolResultChars = 16_000; + + fixture.Client + .RespondsWithToolCall("TestTool") + .RespondsWithText("Fertig"); + + await fixture.Engine.ChatAsync(agent, "Hol die Daten", "test-instance", default); + + var context = fixture.Engine.GetChatContext(agent.AgentId); + var toolMessage = context.Single(m => m.Role == "tool"); + + toolMessage.Content!.Length.ShouldBeLessThan(20_000); + toolMessage.Content.ShouldContain("gekürzt"); + } + + [Fact] + public async Task Ein_kleines_Toolergebnis_bleibt_unveraendert() + { + const string klein = "Alles in Ordnung."; + var fixture = new EngineFixture().WithTool(FakeTool.Returning(klein)); + var agent = fixture.AddAgent("agent-klein", "TestTool"); + + fixture.Client + .RespondsWithToolCall("TestTool") + .RespondsWithText("Fertig"); + + await fixture.Engine.ChatAsync(agent, "Prüfe", "test-instance", default); + + var context = fixture.Engine.GetChatContext(agent.AgentId); + context.Single(m => m.Role == "tool").Content.ShouldBe(klein); + } + + [Theory] + [InlineData(100, 50)] + [InlineData(1_000, 999)] + [InlineData(50_000, 16_000)] + public void Gekappte_Ergebnisse_nennen_die_Menge_der_entfallenen_Zeichen(int length, int limit) + { + var result = AgentEngine.TruncateToolResult(new string('a', length), limit); + + result.ShouldStartWith(new string('a', limit)); + result.ShouldContain((length - limit).ToString("N0")); + } + + [Fact] + public void Ohne_Limit_wird_nicht_gekappt() + { + var original = new string('a', 100_000); + + AgentEngine.TruncateToolResult(original, 0).ShouldBe(original); + } + + [Fact] + public void Genau_auf_der_Grenze_wird_nicht_gekappt() + { + var original = new string('a', 1_000); + + AgentEngine.TruncateToolResult(original, 1_000).ShouldBe(original); + } +} diff --git a/tests/ClawdDotNet.Core.Tests/Infrastructure/FakeChatClient.cs b/tests/ClawdDotNet.Core.Tests/Infrastructure/FakeChatClient.cs index a70c164..2c696bc 100644 --- a/tests/ClawdDotNet.Core.Tests/Infrastructure/FakeChatClient.cs +++ b/tests/ClawdDotNet.Core.Tests/Infrastructure/FakeChatClient.cs @@ -151,6 +151,8 @@ internal sealed class FakeChatClient : IChatCompletionClient Role = m.Role, Content = m.Content, ToolCallId = m.ToolCallId, + // Muss mitkopiert werden, sonst prüfen Caching-Tests am Wire-Format vorbei. + CacheBreakpoint = m.CacheBreakpoint, ToolCalls = m.ToolCalls?.Select(tc => new ToolCall { Id = tc.Id,