system instructions refinement, agent can now span another aggent

Author: priyanahata

src/main/java/uno/anahata/ai/Chat.java

@@ -28,6 +28,7 @@
 import uno.anahata.ai.tools.MultiPartResponse;
 import uno.anahata.ai.tools.ToolCallOutcome;
 import uno.anahata.ai.tools.ToolCallStatus;
+import uno.anahata.ai.tools.UserFeedback;
 import uno.anahata.ai.internal.GsonUtils;
 import uno.anahata.ai.internal.PartUtils;
 import uno.anahata.ai.status.ChatStatus;
@@ -359,28 +360,10 @@ private boolean processAndReloopForFunctionCalls(ChatMessage modelMessageWithCal
 
         // Always create a feedback message if there were any tool calls proposed.
         if (!processingResult.getOutcomes().isEmpty()) {
-            String toolFeedback = processingResult.getOutcomes().stream()
-                .map(outcome -> {
-                    String toolName = outcome.getIdentifiedCall().getCall().name().orElse("unknown");
-                    String id = outcome.getIdentifiedCall().getId();
-                    String status = outcome.getStatus().name();
-                    /*
-                    if (outcome.getStatus() == ToolCallStatus.YES || outcome.getStatus() == ToolCallStatus.ALWAYS) {
-                        status = "";
-                    } */
-                    
-                    return String.format("[%s id=%s %s]", toolName, id, status);
-                })
-                .collect(Collectors.joining(" "));
-            
-            StringBuilder feedbackText = new StringBuilder("Tool Feedback: ").append(toolFeedback);
-            
-            if (StringUtils.isNotBlank(processingResult.getUserComment())) {
-                feedbackText.append("\nUser Comment: '").append(processingResult.getUserComment()).append("'");
-            }
+            String feedbackText = processingResult.getFeedbackMessage();
 
             List<Part> userFeedbackParts = new ArrayList<>();
-            userFeedbackParts.add(Part.fromText(feedbackText.toString()));
+            userFeedbackParts.add(Part.fromText(feedbackText));
             userFeedbackParts.addAll(extraUserParts);
 
             Content feedbackContent = Content.builder().role("user").parts(userFeedbackParts).build();

src/main/java/uno/anahata/ai/context/provider/spi/ContextSummaryProvider.java

@@ -32,8 +32,7 @@
  * of the entire conversation history into the model's prompt.
  * <p>
  * This summary includes unique IDs for every message and part, allowing the
- * model to perform precise context pruning and management. It also provides
- * instructions on the "Prune-As-You-Go" protocol.
+ * model to perform precise context pruning and management.
  * </p>
  */
 public class ContextSummaryProvider extends ContextProvider {
@@ -106,36 +105,9 @@ public List<Part> getParts(Chat chat) {
                 chat.getContextManager().getTokenThreshold()
         ));
         sb.append("\n");
-        sb.append("The following table is the Output of ContextWindow.getContextSummary() with the unique id of every part, every stateful resource and every tool call pair (request response) in this conversation so you can compress the context *as-you-go* or when explicitely instructed by the user. Dont expect the user to instruct you explicitely and dont expect the user to perform manual prunning either."
-                + "You have to work with the total token count (as given by the api on the last turn) and the threshold (max tokens) to work out how far you can go in adding to the context window."
-                + "Your ultimate optimal goal is to ensure that a conversation can "
-                + "\na)Run indefinetly (without ever hitting max tokens) with the most relevant information in the most relevant postion of the context"
-                + "\nb)Be as efficient as possible in terms of token usage and turns"
-                + "\nc)Be a smooth flowing experience to the point that the user wont even think about manual prunning or ask you to 'compress' the context."
-                
-                + "\n"
-                + "\n\nTool execution results are sent inmeditaly (sometimes without the user having a chance to add a message) so: "
-                + "\n**Prune in this turn if ANY of these two conditions are met**: "
-                + "\n\ta) **you are making other tool calls that are not pruning / context window management related** (i.e. if you are just replying to the user, dont prune unless you are making other non prunning tool calls, otherwise it would waste a turn as the prunning tool calls are inmediatly sent back to the server)"
-                + "\n\tb) the context window has gone so large that you estimate prunning to be essential to stay within max input tokens"
-                + ""
-                + "Whenever ANY part (regardless of the type, the role or the position in the history) becomes redundant (i.e. a task that has been resolved/completed, a duplicate message, a hallucination, etc) OR its semantic meaning can be compressed (i.e. the matter being discussed has been clarified and can be kept in context in much more synthetized manner like when it is part of a resolved trial-and-error process and just the 'gist' of it needs to stay in context). Every token in the context window is -ultimately- your responsability."
-                + "\n\nIf I (the user) explicitely ask you to **compress** the context you must:\n"
-                + "\n1) Work with the me to see what discussions / resources / tool calls to keep and what to discard.  \n"
-                + "\n2) Use the prune tools in ContextWindow like you normally do when you prune-as-you-go"
-                + "\n\n"
-                + "Some prune tools have a reason parameter which is mainly for debugging, pruning logic improvements, diagnostics etc... but will disappear from the conversation -like every other ephemeral tool call- after 5 user turns so dont exepct a reason parameter to stay in context. The *compressed* content of anything you are prunning must be in the text parts from your 'spoken' response (i.e. text parts of this turn).\n"
-                + "\n\n Use your discrimination when choosing prunning tools but take into consideration that some Parts have logical dependencies (e.g. FunctionCall <-> FunctionResponse)"
-                + "\n"
-                + "\n**STRICT PRUNING PROTOCOL**:"
-                + "\n\t1) **Type O (Other)**: Use `pruneOther` for non-tool content (Text, Blob, CodeExecutionResult or ExecutableCode parts). Specify the 'Pruning ID' (MessageId/PartId)."
-                + "\n\t2) **Type S (Stateful)**: Use `pruneStatefulResources` ONLY when you explicitly intend to remove a file's content from your context. Specify the 'Pruning ID' (Full Resource Path) from the FR row."
-                + "\n\t3) **Type E (Ephemeral)**: Use `pruneEphemeralToolCall` for non-stateful tool calls if you dont want to wait 5 user turns for these to be automatically pruned (e.g. a too large ephemeral tool call that is really bloating the context or situations where the context window is bordering max tokens). Specify the 'Pruning ID' (Tool Call ID)."
-                + "\n\t4) Pruning a FunctionResponse will automatically prune its corresponding FunctionCall (and vice versa)."
-                + "\n"
-                + "\nRemember that you can also offload a summary of the conversation to an .md file on disk so it is always up to you and the user whether you want to offload to disk or just onto a simple text part in your next turn"
-                + "\nDo not give text parts less weight than tool calls, if you can summarise all your text parts from the last five or ten turns (or whatever number of turns) onto a single one, that can also help a lot in reducing the total number of tokens (is not always just about pruning stateful resources or tool calls)"
-                + "\n\n");
+        sb.append("The following table provides unique IDs for every part in the conversation history. "
+                + "Use these IDs with the ContextWindow pruning tools to manage your context window efficiency "
+                + "according to the 'PAYG PRUNING PROTOCOL' in your system instructions.\n\n");
 
         List<ChatMessage> messages = chat.getContextManager().getContext();
         if (messages.isEmpty()) {

src/main/java/uno/anahata/ai/swing/SwingFunctionPrompter.java

@@ -47,8 +47,12 @@ public class SwingFunctionPrompter extends JDialog implements FunctionPrompter {
     private String userComment = "";
     private boolean cancelled = false;
 
+    /**
+     * Constructs a new SwingFunctionPrompter.
+     * @param chatPanel The ChatPanel that initiated the prompt.
+     */
     public SwingFunctionPrompter(ChatPanel chatPanel) {
-        super((JFrame) SwingUtilities.getWindowAncestor(chatPanel), "Confirm Proposed Actions", true);
+        super((JFrame) SwingUtilities.getWindowAncestor(chatPanel), "Confirm Proposed Actions - " + chatPanel.getChat().getDisplayName(), true);
         this.chatPanel = chatPanel;
     }
 
@@ -166,4 +170,4 @@ private Map<FunctionCall, FunctionConfirmation> collectResultsFromInteractiveRen
         }
         return results;
     }
-}
+}

src/main/java/uno/anahata/ai/swing/UICapture.java

@@ -12,17 +12,14 @@
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
-import java.util.logging.Level;
 import javax.imageio.ImageIO;
 import javax.swing.JFrame;
 import javax.swing.JOptionPane;
 import lombok.extern.slf4j.Slf4j;
 import uno.anahata.ai.AnahataConfig;
-import uno.anahata.ai.config.ChatConfig;
 
 /**
- *
- * @author anahata
+ * Utility class for capturing screenshots of screen devices and application windows.
  */
 @Slf4j
 public class UICapture {
@@ -31,22 +28,18 @@ public class UICapture {
 
     public static final File SCREENSHOTS_DIR = AnahataConfig.getWorkingFolder("screenshots");
 
+    /**
+     * Captures a screenshot of all available screen devices.
+     * @return A list of files containing the screenshots.
+     */
     public static List<File> screenshotAllScreenDevices() {
         List<File> ret = new ArrayList<>();
         try {
             GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();
             GraphicsDevice[] screens = ge.getScreenDevices();
 
             for (int i = 0; i < screens.length; i++) {
-                Rectangle screenBounds = screens[i].getDefaultConfiguration().getBounds();
-                BufferedImage screenshot = new Robot().createScreenCapture(screenBounds);
-
-                String timestamp = TIMESTAMP_FORMAT.format(new Date());
-                String filename = "screen-" + i + "-" + timestamp;
-                File tempFile = new File (SCREENSHOTS_DIR, filename);
-                tempFile.deleteOnExit();
-                ImageIO.write(screenshot, "png", tempFile);
-                ret.add(tempFile);
+                ret.add(screenshotScreenDevice(i));
             }
         } catch (Exception ex) {
             log.error("Screenshot capture failed", ex);
@@ -55,6 +48,34 @@ public static List<File> screenshotAllScreenDevices() {
         return ret;
     }
 
+    /**
+     * Captures a screenshot of a specific screen device by its index.
+     * @param index The index of the screen device.
+     * @return The file containing the screenshot.
+     * @throws Exception if the capture fails or the index is invalid.
+     */
+    public static File screenshotScreenDevice(int index) throws Exception {
+        GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();
+        GraphicsDevice[] screens = ge.getScreenDevices();
+        if (index < 0 || index >= screens.length) {
+            throw new IllegalArgumentException("Invalid screen device index: " + index);
+        }
+
+        Rectangle screenBounds = screens[index].getDefaultConfiguration().getBounds();
+        BufferedImage screenshot = new Robot().createScreenCapture(screenBounds);
+
+        String timestamp = TIMESTAMP_FORMAT.format(new Date());
+        String filename = "screen-" + index + "-" + timestamp + ".png";
+        File tempFile = new File(SCREENSHOTS_DIR, filename);
+        tempFile.deleteOnExit();
+        ImageIO.write(screenshot, "png", tempFile);
+        return tempFile;
+    }
+
+    /**
+     * Captures a screenshot of all visible JFrames in the application.
+     * @return A list of files containing the screenshots.
+     */
     public static List<File> screenshotAllJFrames() {
         log.debug("Starting screenshot capture of all JFrames.");
         List<File> ret = new ArrayList<>();
@@ -76,7 +97,7 @@ public static List<File> screenshotAllJFrames() {
                     // Sanitize title for use in filename
                     String sanitizedTitle = title.replaceAll("[^a-zA-Z0-9.-]", "_");
                     String timestamp = TIMESTAMP_FORMAT.format(new Date());
-                    String fileName = sanitizedTitle + "-" + timestamp;
+                    String fileName = sanitizedTitle + "-" + timestamp + ".png";
                     File tempFile = new File (SCREENSHOTS_DIR, fileName);
                     tempFile.deleteOnExit();
                     ImageIO.write(image, "png", tempFile);
@@ -96,6 +117,5 @@ public static List<File> screenshotAllJFrames() {
         }
 
         return ret;
-
     }
-}
+}

src/main/java/uno/anahata/ai/swing/tools/spi/ScreenCapture.java

@@ -11,24 +11,30 @@
 import uno.anahata.ai.swing.UICapture;
 
 /**
- *
- * @author anahata
+ * Tool provider for capturing screenshots of the host system and application windows.
  */
 public class ScreenCapture {
 
-    @AIToolMethod(value = "Takes a screenshot of all host systems graphics devices as in GraphicsEnvironment.getScreenDevices() "
+    /**
+     * Takes a screenshot of a specific graphics device.
+     * @param deviceIdx The index of the device to capture.
+     * @return The absolute path to the captured screenshot file.
+     * @throws Exception if the capture fails.
+     */
+    @AIToolMethod(value = "Takes a screenshot of a specific host system graphics device as in GraphicsEnvironment.getScreenDevices() "
             + "And returns a String with the absolute path ")
     public static String takeDeviceScreenshot(
             @AIToolParam(value = "The device index in GraphicsEnvironment.getScreenDevices()")
-            int deviceIdx) {
-        List<File> files = UICapture.screenshotAllScreenDevices();
-        String ret = "";
-        for (File file : files) {
-            ret += file.getAbsolutePath();
-        }
-        return ret;
+            int deviceIdx) throws Exception {
+        File file = UICapture.screenshotScreenDevice(deviceIdx);
+        return file.getAbsolutePath();
     }
 
+    /**
+     * Takes a screenshot of all visible application windows.
+     * @return A MultiPartResponse containing the paths to the captured screenshots.
+     * @throws IOException if the capture fails.
+     */
     @AIToolMethod(value = "Takes a screenshot of all visible JFrames, saves them to temporary files, "
             + "and returns a response object containing the absolute paths to those files.")
     public static MultiPartResponse attachWindowCaptures() throws IOException {
@@ -38,4 +44,4 @@ public static MultiPartResponse attachWindowCaptures() throws IOException {
                 .collect(Collectors.toList());
         return new MultiPartResponse(filePaths);
     }
-}
+}

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

@@ -34,4 +34,15 @@ public class FunctionProcessingResult {
      * Any text the user entered in the comment box of the confirmation dialog.
      */
     public final String userComment;
-}
+
+    /**
+     * Indicates whether the tool confirmation dialog was actually displayed to the user.
+     */
+    public final boolean dialogShown;
+
+    /**
+     * The complete, system-generated user feedback message summarizing the 
+     * outcomes of all proposed tool calls and any user comments.
+     */
+    public final String feedbackMessage;
+}

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

@@ -3,6 +3,7 @@
 
 import lombok.AllArgsConstructor;
 import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
 
 /**
  * A data class that represents the final outcome of a single proposed tool call.
@@ -26,4 +27,49 @@ public class ToolCallOutcome {
      * The final status of the call after user interaction (e.g., YES, NO, ALWAYS).
      */
     private final ToolCallStatus status;
-}
+
+    /**
+     * Optional feedback or comments collected during the tool's execution 
+     * (e.g., from a specialized dialog like a diff viewer).
+     */
+    private final String executionFeedback;
+
+    /**
+     * Generates a concise, bracketed string summarizing the outcome of this tool call.
+     * @param dialogShown Whether the general tool confirmation dialog was displayed.
+     * @return The formatted feedback string.
+     */
+    public String toFeedbackString(boolean dialogShown) {
+        String toolName = identifiedCall.getCall().name().orElse("unknown");
+        String id = identifiedCall.getId();
+        
+        String statusLabel;
+        switch(status) {
+            case ALWAYS: 
+                statusLabel = dialogShown ? "EXECUTED (User-confirmed)" : "EXECUTED (Auto-approved)"; 
+                break;
+            case YES: 
+                statusLabel = "EXECUTED (User-confirmed)"; 
+                break;
+            case NO: 
+                statusLabel = "NOT_EXECUTED (User-denied)"; 
+                break;
+            case NEVER: 
+                statusLabel = "NOT_EXECUTED (Auto-denied)"; 
+                break;
+            case CANCELLED: 
+                statusLabel = "NOT_EXECUTED (Dialog-cancelled)"; 
+                break;
+            default: 
+                statusLabel = "NOT_EXECUTED";
+        }
+        
+        StringBuilder sb = new StringBuilder();
+        sb.append("[").append(toolName).append(" id=").append(id).append(" ").append(statusLabel);
+        if (StringUtils.isNotBlank(executionFeedback)) {
+            sb.append(" User Feedback: '").append(executionFeedback).append("'");
+        }
+        sb.append("]");
+        return sb.toString();
+    }
+}