Pdf comment agent

.taskfiles/frontend.yml

@@ -239,6 +239,7 @@ tasks:
       - task: typecheck:saas
       - task: typecheck:desktop
       - task: typecheck:scripts
+      - task: typecheck:prototypes
 
   # ============================================================
   # Quality Gate

app/common/src/main/java/stirling/software/common/model/api/comments/AnnotationLocation.java

@@ -0,0 +1,15 @@
+package stirling.software.common.model.api.comments;
+
+/**
+ * Absolute position of a PDF annotation in the document.
+ *
+ * <p>Coordinates are in PDF user-space with the origin at the page's bottom-left, consistent with
+ * PDFBox's {@code PDRectangle} convention.
+ *
+ * @param pageIndex 0-indexed page number the annotation lives on.
+ * @param x bottom-left x coordinate of the annotation rectangle.
+ * @param y bottom-left y coordinate of the annotation rectangle.
+ * @param width width of the annotation rectangle, in user-space units.
+ * @param height height of the annotation rectangle, in user-space units.
+ */
+public record AnnotationLocation(int pageIndex, float x, float y, float width, float height) {}

app/common/src/main/java/stirling/software/common/model/api/comments/StickyNoteSpec.java

@@ -0,0 +1,15 @@
+package stirling.software.common.model.api.comments;
+
+/**
+ * Description of a single sticky-note (PDF Text) annotation to place on a document.
+ *
+ * <p>{@code author} and {@code subject} are optional — callers that pass {@code null} get a default
+ * author/subject from {@code PdfAnnotationService}.
+ *
+ * @param location where to anchor the annotation icon, in PDF user-space.
+ * @param text the comment body shown in the popup (required, non-blank).
+ * @param author optional author label shown in the popup; {@code null} → service default.
+ * @param subject optional subject line shown in the popup; {@code null} → service default.
+ */
+public record StickyNoteSpec(
+        AnnotationLocation location, String text, String author, String subject) {}

app/common/src/main/java/stirling/software/common/service/InternalApiClient.java

@@ -34,11 +34,17 @@
 @Slf4j
 public class InternalApiClient {
 
-    // Allowlist for internal dispatch. Matches a fixed namespace prefix,
+    // Allowlist for internal dispatch. Matches fixed namespace prefixes,
     // but rejects traversal (..), URL-encoding (%), query/fragment, backslashes, and any other
     // character that could alter the resolved endpoint on the local Spring server.
+    //
+    // The second alternation carves out `/api/v1/ai/tools/*` specifically — AI tools are
+    // dispatchable, but the broader `/api/v1/ai/` surface (orchestrate, health, etc.) is
+    // intentionally NOT permitted to avoid plan steps re-entering the orchestrator.
     private static final Pattern ALLOWED_ENDPOINT_PATH =
-            Pattern.compile("^/api/v1/(general|misc|security|convert|filter)(/[A-Za-z0-9_-]+)+$");
+            Pattern.compile(
+                    "^/api/v1/(general|misc|security|convert|filter)(/[A-Za-z0-9_-]+)+$"
+                            + "|^/api/v1/ai/tools(/[A-Za-z0-9_-]+)+$");
 
     private final ServletContext servletContext;
     private final UserServiceInterface userService;

app/common/src/main/java/stirling/software/common/service/PdfAnnotationService.java

@@ -0,0 +1,157 @@
+package stirling.software.common.service;
+
+import java.util.Calendar;
+import java.util.List;
+
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.graphics.color.PDColor;
+import org.apache.pdfbox.pdmodel.graphics.color.PDDeviceRGB;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationText;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.api.comments.AnnotationLocation;
+import stirling.software.common.model.api.comments.StickyNoteSpec;
+
+/**
+ * Shared primitive for adding sticky-note (PDF Text) annotations to a document.
+ *
+ * <p>Used by:
+ *
+ * <ul>
+ *   <li>{@code /api/v1/misc/add-comments} — a deterministic, reusable tool.
+ *   <li>AI-agent flows that generate comment specs (e.g. PDF review agent, math auditor review
+ *       mode) and hand them off to this service for deterministic placement.
+ * </ul>
+ */
+@Slf4j
+@Service
+public class PdfAnnotationService {
+
+    /** Yellow sticky-note fill colour (R, G, B in 0..1 range). */
+    private static final float[] STICKY_NOTE_COLOR_RGB = {1f, 0.95f, 0.4f};
+
+    /** Opacity for the sticky-note icon. */
+    private static final float ANNOTATION_OPACITY = 0.9f;
+
+    /** PDF Text-annotation icon name — {@code "Comment"} is one of the standard icons. */
+    private static final String ANNOTATION_ICON_NAME = "Comment";
+
+    /** Default subject shown in the annotation popup when a spec does not supply one. */
+    private static final String DEFAULT_SUBJECT = "Stirling AI Comment";
+
+    /** Default author label shown in the annotation popup when a spec does not supply one. */
+    private static final String DEFAULT_AUTHOR = "Stirling AI";
+
+    /**
+     * Cap on sticky-note text length. PDF annotation bodies can technically be much longer, but
+     * anything beyond this is almost certainly pathological (accidental document-dump or malicious
+     * payload) and would bloat the output file.
+     */
+    private static final int MAX_COMMENT_TEXT_LENGTH = 100_000;
+
+    /**
+     * Add a list of sticky notes to {@code doc}. Specs that reference an out-of-range page or
+     * contain blank text are logged and skipped; this method never throws for a single bad spec.
+     *
+     * @return the number of annotations actually applied
+     */
+    public int addStickyNotes(PDDocument doc, List<StickyNoteSpec> specs) {
+        if (specs == null || specs.isEmpty()) {
+            return 0;
+        }
+        int totalPages = doc.getNumberOfPages();
+        Calendar now = Calendar.getInstance();
+        int applied = 0;
+        for (int i = 0; i < specs.size(); i++) {
+            StickyNoteSpec spec = specs.get(i);
+            if (!isValid(spec, totalPages, i)) {
+                continue;
+            }
+            apply(doc, spec, now);
+            applied++;
+        }
+        if (applied < specs.size()) {
+            log.warn(
+                    "Applied {}/{} sticky notes; {} skipped due to invalid specs.",
+                    applied,
+                    specs.size(),
+                    specs.size() - applied);
+        }
+        return applied;
+    }
+
+    /**
+     * Add a single sticky note. Convenience wrapper; prefer {@link #addStickyNotes(PDDocument,
+     * List)} when placing multiple annotations so log output is batched.
+     */
+    public void addStickyNote(PDDocument doc, StickyNoteSpec spec) {
+        addStickyNotes(doc, List.of(spec));
+    }
+
+    private boolean isValid(StickyNoteSpec spec, int totalPages, int index) {
+        if (spec == null || spec.location() == null) {
+            log.warn("Skipping sticky-note[{}]: spec or location is null.", index);
+            return false;
+        }
+        if (spec.text() == null || spec.text().isBlank()) {
+            log.warn("Skipping sticky-note[{}]: text is blank.", index);
+            return false;
+        }
+        if (spec.text().length() > MAX_COMMENT_TEXT_LENGTH) {
+            log.warn(
+                    "Skipping sticky-note[{}]: text length {} exceeds limit {}.",
+                    index,
+                    spec.text().length(),
+                    MAX_COMMENT_TEXT_LENGTH);
+            return false;
+        }
+        AnnotationLocation loc = spec.location();
+        if (loc.width() <= 0f || loc.height() <= 0f) {
+            log.warn(
+                    "Skipping sticky-note[{}]: non-positive dimensions width={} height={}.",
+                    index,
+                    loc.width(),
+                    loc.height());
+            return false;
+        }
+        int page = loc.pageIndex();
+        if (page < 0 || page >= totalPages) {
+            log.warn(
+                    "Skipping sticky-note[{}]: pageIndex={} out of range [0, {}).",
+                    index,
+                    page,
+                    totalPages);
+            return false;
+        }
+        return true;
+    }
+
+    private void apply(PDDocument doc, StickyNoteSpec spec, Calendar now) {
+        AnnotationLocation loc = spec.location();
+
+        PDAnnotationText annot = new PDAnnotationText();
+        annot.setContents(spec.text());
+        annot.setRectangle(new PDRectangle(loc.x(), loc.y(), loc.width(), loc.height()));
+        annot.setSubject(nonBlankOr(spec.subject(), DEFAULT_SUBJECT));
+        annot.setTitlePopup(nonBlankOr(spec.author(), DEFAULT_AUTHOR));
+        annot.setColor(new PDColor(STICKY_NOTE_COLOR_RGB, PDDeviceRGB.INSTANCE));
+        annot.setCreationDate(now);
+        annot.setConstantOpacity(ANNOTATION_OPACITY);
+        annot.getCOSObject().setName(COSName.NAME, ANNOTATION_ICON_NAME);
+
+        try {
+            doc.getPage(loc.pageIndex()).getAnnotations().add(annot);
+        } catch (java.io.IOException e) {
+            log.warn(
+                    "Failed to attach sticky note to page {}: {}", loc.pageIndex(), e.getMessage());
+        }
+    }
+
+    private static String nonBlankOr(String value, String fallback) {
+        return value != null && !value.isBlank() ? value : fallback;
+    }
+}

app/common/src/main/java/stirling/software/common/util/PdfTextLocator.java

@@ -0,0 +1,139 @@
+package stirling.software.common.util;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.apache.pdfbox.text.TextPosition;
+import org.springframework.stereotype.Component;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Locate text on a specific PDF page and return its bounding box in PDF user-space (bottom-left
+ * origin). Used by tools that receive "anchor by text" hints — e.g. {@code
+ * /api/v1/misc/add-comments} when callers supply an {@code anchorText} instead of explicit
+ * coordinates.
+ *
+ * <p>Matching is tolerant: case-insensitive with punctuation/whitespace stripped on both sides, so
+ * a caller-supplied needle of {@code "215000"} matches page text {@code "$215,000"}, and {@code
+ * "Total Revenue"} matches {@code "Total Revenue."}.
+ */
+@Slf4j
+@Component
+public class PdfTextLocator {
+
+    /** One found line of text with its user-space bounding box. */
+    public record MatchedBox(float x, float y, float width, float height) {}
+
+    /**
+     * Find the first line on {@code pageIndex} (0-indexed) whose text contains {@code needle} under
+     * the tolerant match. Returns empty when no match, when the page index is out of range, or when
+     * the needle is blank.
+     */
+    public Optional<MatchedBox> findOnPage(PDDocument doc, int pageIndex, String needle) {
+        if (doc == null
+                || needle == null
+                || needle.isBlank()
+                || pageIndex < 0
+                || pageIndex >= doc.getNumberOfPages()) {
+            return Optional.empty();
+        }
+        String normalizedNeedle = normalize(needle);
+        if (normalizedNeedle.isEmpty()) {
+            return Optional.empty();
+        }
+
+        List<CapturedLine> lines = new ArrayList<>();
+        LineCapturingStripper stripper;
+        try {
+            stripper = new LineCapturingStripper(lines);
+            stripper.setStartPage(pageIndex + 1);
+            stripper.setEndPage(pageIndex + 1);
+            stripper.setSortByPosition(true);
+            // Side effect: populates `lines`. We don't need the concatenated text.
+            stripper.getText(doc);
+        } catch (IOException e) {
+            log.warn(
+                    "PdfTextLocator failed to extract text on page {}: {}",
+                    pageIndex,
+                    e.getMessage());
+            return Optional.empty();
+        }
+
+        PDRectangle mediaBox = doc.getPage(pageIndex).getMediaBox();
+        float pageHeight = mediaBox.getHeight();
+
+        for (CapturedLine line : lines) {
+            if (normalize(line.text).contains(normalizedNeedle)) {
+                // PDFBox's *DirAdj coords descend from the top of the page; convert to PDF
+                // user-space (origin = bottom-left) so the bbox can feed a PDRectangle directly.
+                float userSpaceY = pageHeight - line.yTopDown - line.height;
+                return Optional.of(new MatchedBox(line.x, userSpaceY, line.width, line.height));
+            }
+        }
+        return Optional.empty();
+    }
+
+    /** Strip everything non-alphanumeric and lowercase for tolerant matching. */
+    private static String normalize(String s) {
+        return s.replaceAll("[^A-Za-z0-9]", "").toLowerCase(Locale.ROOT);
+    }
+
+    private static final class CapturedLine {
+        String text;
+        float x;
+        float yTopDown;
+        float width;
+        float height;
+    }
+
+    private static final class LineCapturingStripper extends PDFTextStripper {
+        private final List<CapturedLine> lines;
+
+        LineCapturingStripper(List<CapturedLine> sink) throws IOException {
+            super();
+            this.lines = sink;
+        }
+
+        @Override
+        protected void writeString(String text, List<TextPosition> textPositions)
+                throws IOException {
+            if (textPositions != null && !textPositions.isEmpty()) {
+                CapturedLine line = new CapturedLine();
+                line.text = text;
+
+                float minX = Float.MAX_VALUE;
+                float maxRight = 0f;
+                float minY = Float.MAX_VALUE;
+                float maxHeight = 0f;
+                for (TextPosition p : textPositions) {
+                    float x = p.getXDirAdj();
+                    float y = p.getYDirAdj();
+                    float w = p.getWidthDirAdj();
+                    float h = p.getHeightDir();
+                    if (h == 0f) {
+                        // Workaround: some fonts report 0 height via TextPosition; fall back to
+                        // the nominal font size so downstream bboxes are never zero-height.
+                        h = p.getFontSizeInPt();
+                    }
+                    if (x < minX) minX = x;
+                    if (x + w > maxRight) maxRight = x + w;
+                    if (y < minY) minY = y;
+                    if (h > maxHeight) maxHeight = h;
+                }
+                line.x = minX;
+                line.width = maxRight - minX;
+                line.yTopDown = minY;
+                line.height = maxHeight;
+                lines.add(line);
+            }
+            super.writeString(text, textPositions);
+        }
+    }
+}