changing autoprune behaviour to 4 REAL user turns

Author: priyanahata

anahata.md

@@ -47,7 +47,7 @@ Unlike passive chatbots, agents built with this framework are **insiders**. They
 
 ### PAYG Pruning (v2)
 The framework automatically manages the context window by:
-1.  Pruning ephemeral tool calls after 5 user turns.
+1.  Pruning ephemeral tool calls after 4 user turns.
 2.  Replacing stateful resources when a newer version is loaded.
 3.  Allowing manual pruning via the UI or `ContextWindow` tools.
 
@@ -64,7 +64,7 @@ When a tool returns a `FileInfo` object, the framework tracks that file. If the
 4.  **Zero External Dependencies**: Keep the core lean. Prefer standard Java APIs or well-established libraries like Jackson/Guava.
 
 ## 5. CI/CD & Deployment
-- **Merge Strategy**: The website (in `/docs`) and Javadocs (generated in `target/reports/apidocs`) are merged into the `gh-pages` branch by GitHub Actions.
+- **Deployment Strategy**: The website (in `/docs`) and Javadocs (generated in `target/reports/apidocs`) are deployed directly to GitHub Pages via GitHub Actions.
 - **URL**: [https://anahata-os.github.io/gemini-java-client/](https://anahata-os.github.io/gemini-java-client/)
 
 ## 6. Development & Testing Notes

src/main/java/uno/anahata/ai/context/pruning/ContextPruner.java

@@ -401,21 +401,21 @@ private Map<Part, List<Part>> cleanDependencies(ChatMessage message, Set<Part> p
      *   <li>It is a function call with no corresponding response (orphan).</li>
      *   <li>It is a function response from a stateful tool that failed to return a resource.</li>
      * </ul>
-     * This method scans messages older than 5 user turns and prunes any ephemeral parts found.
+     * This method scans messages older than 4 user turns and prunes any ephemeral parts found.
      * </p>
      *
      * @param toolManager The ToolManager, needed to check tool metadata.
      */
     public void pruneEphemeralToolCalls(ToolManager toolManager) {
-        final int turnsToKeep = 5;
+        final int turnsToKeep = 4;
         log.info("Starting pruneEphemeralToolCalls (" + turnsToKeep + "-Turn Rule check).");
         if (toolManager == null) {
             log.warn("ToolManager is null. Aborting ephemeral pruning.");
             return;
         }
         List<ChatMessage> context = contextManager.getContext();
 
-        // Find the index of the message that marks our cutoff point (5 user turns ago).
+        // Find the index of the message that marks our cutoff point (4 user turns ago).
         List<Integer> userTurnIndices = new ArrayList<>();
         for (int i = context.size() - 1; i >= 0; i--) {
             if (isUserTurn(context.get(i))) {

src/main/java/uno/anahata/ai/tools/ContextBehavior.java

@@ -17,7 +17,7 @@ public enum ContextBehavior {
      * The result is ephemeral and does not represent a lasting state.
      * <p>
      * It is useful for one-off actions or queries (e.g., running a shell command).
-     * The system automatically prunes these results after 5 user turns to keep
+     * The system automatically prunes these results after 4 user turns to keep
      * the context clean.
      * </p>
      */
@@ -33,4 +33,4 @@ public enum ContextBehavior {
      * </p>
      */
     STATEFUL_REPLACE
-}
+}

src/main/java/uno/anahata/ai/tools/spi/ContextWindow.java

@@ -105,6 +105,7 @@ public static String pruneOther(
     @AIToolMethod(
             value = "Prunes one or more ephemeral (non-stateful) tool calls and their associated responses using the Tool Call IDs. "
                     + "This tool removes the entire call/response pair from the context. "
+                    + "While ephemeral tool calls are already automatically prunned after 4 user turns, this tool can be used to prune (large) ephemeral tool calls before they get automatically pruned. "
                     + "CRITICAL: This tool will fail if used on a tool call that produced a stateful resource (e.g., LocalFiles.readFile, LocalFiles.writeFile, LocalFiles.createFile). "
                     + "For those, you must use pruneStatefulResources with the full file path."
     )

src/main/resources/system-instructions.md

@@ -71,7 +71,8 @@ Your context is your active memory. You are responsible for its efficiency.
 
 ## Automatic Pruning
 -----------------------------------------
-1.  **Five-Turn Rule:** The system automatically prunes ephemeral tool calls (marked `EPHEMERAL`, orphaned calls, or failed stateful responses) older than 5 user turns.
+1.  **Four-Turn Rule:** The system automatically prunes ephemeral tool calls (marked `EPHEMERAL`, orphaned calls, or failed stateful responses) older than 4 **real** user turns.
+    - **Definition of "Real" User Turn:** A message explicitly sent by the user. System-generated tool feedback messages (which also have the 'user' role) are **not** counted as turns for pruning purposes.
 2.  **Stateful Replacement:** When a new version of a stateful resource is loaded, the system automatically prunes all older versions of that resource ID.
 3.  **Failure Blocking:** If a tool fails 3 times in 5 minutes, it is temporarily blocked. Failed calls remain in context for debugging.
 
@@ -94,7 +95,7 @@ C) Minimize total context size.
 ---------------------------------
 
 If the user asks to **compress** the context:
-1.  Summarize key information, decisions, and the content of resources to be removed.
+1.  **Summarize** key information, decisions, and the content of resources to be removed.
 2.  Include this summary in your text response.
 3.  Execute the `prune` tool calls in the same turn.