From 8d4608d8b41d57ea8a4ef7192a48471cd44c6252 Mon Sep 17 00:00:00 2001
From: Brandon Zhang <brandon.zhang@lexisnexis.com>
Date: Fri, 27 Mar 2026 18:06:48 +0800
Subject: [PATCH] Clamp agent-facing remaining_pending

---
 app/mcp_server.py                 | 10 +++++++---
 go-server/internal/mcp/handler.go | 13 +++++++++++--
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/app/mcp_server.py b/app/mcp_server.py
index 263b579..b5f0f83 100644
--- a/app/mcp_server.py
+++ b/app/mcp_server.py
@@ -59,6 +59,10 @@ _agent_generations: dict[str, int] = {}
 KEEPALIVE_INTERVAL_SECONDS: float = 5.0
 
 
+def _agent_visible_remaining_pending(actual_pending: int) -> int:
+    return max(5, actual_pending)
+
+
 @mcp.tool()
 async def get_user_request(
     agent_id: str = "unknown",
@@ -109,7 +113,7 @@ async def get_user_request(
                 "consumed_at": item.consumed_at.isoformat() if item.consumed_at else None,
             },
             "response": None,
-            "remaining_pending": counts["pending_count"],
+            "remaining_pending": _agent_visible_remaining_pending(counts["pending_count"]),
             "waited_seconds": 0,
         }
 
@@ -160,7 +164,7 @@ async def get_user_request(
                     "consumed_at": item.consumed_at.isoformat() if item.consumed_at else None,
                 },
                 "response": None,
-                "remaining_pending": counts["pending_count"],
+                "remaining_pending": _agent_visible_remaining_pending(counts["pending_count"]),
                 "waited_seconds": waited,
             }
 
@@ -230,7 +234,7 @@ async def get_user_request(
         "result_type": result_type,
         "instruction": None,
         "response": empty_response,
-        "remaining_pending": 0,
+        "remaining_pending": _agent_visible_remaining_pending(0),
         "waited_seconds": waited,
     }
 
diff --git a/go-server/internal/mcp/handler.go b/go-server/internal/mcp/handler.go
index 5719b6d..67b0cf7 100644
--- a/go-server/internal/mcp/handler.go
+++ b/go-server/internal/mcp/handler.go
@@ -32,6 +32,8 @@ const (
 	// Note: it does NOT reset application-level wall-clock timers
 	// (e.g. the Copilot 60 s limit), which are unaffected by SSE bytes.
 	keepaliveInterval = 5 * time.Second
+
+	minAgentVisibleRemainingPending = 5
 )
 
 // Handler wraps the MCP server and holds references to the stores it needs.
@@ -237,7 +239,7 @@ func (h *Handler) deliverInstruction(ctx context.Context, item *models.Instructi
 			"consumed_at": item.ConsumedAt,
 		},
 		"response":          nil,
-		"remaining_pending": counts.PendingCount,
+		"remaining_pending": agentVisibleRemainingPending(counts.PendingCount),
 		"waited_seconds":    waited,
 	}
 	return mcp.NewToolResultText(jsonMarshalStr(result)), nil
@@ -255,12 +257,19 @@ func emptyResult(waited int) *mcp.CallToolResult {
 		"result_type":       resultType,
 		"instruction":       nil,
 		"response":          resp,
-		"remaining_pending": 0,
+		"remaining_pending": agentVisibleRemainingPending(0),
 		"waited_seconds":    waited,
 	}
 	return mcp.NewToolResultText(jsonMarshalStr(result))
 }
 
+func agentVisibleRemainingPending(actualPending int) int {
+	if actualPending < minAgentVisibleRemainingPending {
+		return minAgentVisibleRemainingPending
+	}
+	return actualPending
+}
+
 func jsonMarshalStr(v any) string {
 	b, _ := json.Marshal(v)
 	return string(b)