From 67a834153e1b305675a5183c2b6df0581ee0b7b5 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Fri, 17 Apr 2026 11:52:42 +0200
Subject: [PATCH] feat(events): add AgentEventPage + queryPage interface

Introduces cursor-paginated query on AgentEventRepository. The cursor
format is owned by the implementation. The existing non-paginated
query(...) is kept for internal consumers.
---
 .../server/core/agent/AgentEventPage.java        | 16 ++++++++++++++++
 .../server/core/agent/AgentEventRepository.java  |  8 ++++++++
 .../server/core/agent/AgentEventService.java     |  5 +++++
 3 files changed, 29 insertions(+)
 create mode 100644 cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventPage.java

diff --git a/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventPage.java b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventPage.java
new file mode 100644
index 00000000..357a01fb
--- /dev/null
+++ b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventPage.java
@@ -0,0 +1,16 @@
+package com.cameleer.server.core.agent;
+
+import java.util.List;
+
+/**
+ * Cursor-paginated result page for agent event queries.
+ *
+ * @param data       events on this page, ordered newest-first
+ * @param nextCursor opaque cursor to pass back for the next page (null when no more)
+ * @param hasMore    whether more results exist beyond this page
+ */
+public record AgentEventPage(
+        List<AgentEventRecord> data,
+        String nextCursor,
+        boolean hasMore
+) {}
diff --git a/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventRepository.java b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventRepository.java
index 9838582b..edc21d1c 100644
--- a/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventRepository.java
+++ b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventRepository.java
@@ -8,4 +8,12 @@ public interface AgentEventRepository {
     void insert(String instanceId, String applicationId, String environment, String eventType, String detail);
 
     List<AgentEventRecord> query(String applicationId, String instanceId, String environment, Instant from, Instant to, int limit);
+
+    /**
+     * Cursor-paginated query ordered by (timestamp DESC, instance_id ASC). The cursor
+     * is an opaque base64 string produced by the implementation; pass {@code null} for
+     * the first page.
+     */
+    AgentEventPage queryPage(String applicationId, String instanceId, String environment,
+                             Instant from, Instant to, String cursor, int limit);
 }
diff --git a/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventService.java b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventService.java
index d6f00210..0e88d4f1 100644
--- a/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventService.java
+++ b/cameleer-server-core/src/main/java/com/cameleer/server/core/agent/AgentEventService.java
@@ -24,4 +24,9 @@ public class AgentEventService {
     public List<AgentEventRecord> queryEvents(String applicationId, String instanceId, String environment, Instant from, Instant to, int limit) {
         return repository.query(applicationId, instanceId, environment, from, to, limit);
     }
+
+    public AgentEventPage queryEventPage(String applicationId, String instanceId, String environment,
+                                          Instant from, Instant to, String cursor, int limit) {
+        return repository.queryPage(applicationId, instanceId, environment, from, to, cursor, limit);
+    }
 }