From 589f45ba329db21111fcfd6c60cdf84d08f7b768 Mon Sep 17 00:00:00 2001
From: cabbage <root@everdream.xyz>
Date: Fri, 27 Mar 2026 04:16:33 +0800
Subject: [PATCH] refactor: remove wait_seconds from get_user_request tool Wait
 time is now fully server-controlled via default_wait_seconds setting. Agents
 can no longer request a different wait duration - only the user controls this
 via the web UI. - Remove wait_seconds param from get_user_request signature -
 Simplify actual_wait to min(cfg.default_wait_seconds, MAX_WAIT) - Update
 Settings panel label from 'Min Wait' to 'Wait (sec)' - Update hint text to
 explain server-only control - Update README: input schema, behavior rules,
 settings description, changelog

---
 README.md         |  9 ++++-----
 app/mcp_server.py | 17 ++++-------------
 2 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index ad616cb..3d96c5e 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,7 @@ local-mcp/
 
 ### `settings`
 
-- `default_wait_seconds` - integer — **minimum** seconds the tool waits before returning empty/default response; agents may request longer but not shorter
+- `default_wait_seconds` - integer — seconds the tool waits before returning an empty/default response; set exclusively by the user via the web UI
 - `default_empty_response` - text, nullable
 - `agent_stale_after_seconds` - integer
 
@@ -154,7 +154,6 @@ All routes are local-only and intended for `localhost` usage.
 ```json
 {
   "agent_id": "optional-string",
-  "wait_seconds": "optional-integer",
   "default_response_override": "optional-string"
 }
 ```
@@ -206,8 +205,8 @@ All routes are local-only and intended for `localhost` usage.
 - Deliver the oldest pending instruction first.
 - Mark the delivered instruction as consumed in the same transaction used to claim it.
 - Never return more than one instruction per call.
-- `default_wait_seconds` is a **minimum** enforced by the server. The actual wait is `max(wait_seconds or 0, server_minimum)`. Agents may request longer waits but cannot go below the floor — this prevents busy-polling.
-- Clamp `actual_wait` to an absolute server maximum (300 s).
+- `default_wait_seconds` is fully server-controlled (set by the user via the web UI). Agents cannot override it.
+- Clamp `actual_wait` to an absolute server maximum (86400 s).
 - Update the agent activity record on every call, even when no instruction is returned.
 - The UI should infer "agent connected" if the latest activity is within `agent_stale_after_seconds`.
 - Agent implementations should continue calling this tool instead of ending their work session on their own, so they can pick up newly added instructions without missing critical follow-up requests.
@@ -487,7 +486,7 @@ Server-Sent Events endpoint for live UI updates.
   - [x] Document title badge showing pending instruction count.
   - [x] SSE reconnecting indicator in the header.
   - [x] Dark / light theme toggle defaulting to OS colour-scheme preference.
-  - [x] `default_wait_seconds` changed to a server-enforced minimum (agents may request longer).
+  - [x] `default_wait_seconds` changed to fully server-controlled (agents can no longer override wait time).
   - [x] Non-blocking `server.ps1` management script (start / stop / restart / status / logs).
   - [x] MCP stateless/stateful mode configurable via `MCP_STATELESS` env var (default `true`).
   - [x] Per-agent generation counter prevents abandoned (timed-out) coroutines from silently consuming instructions meant for newer calls.
diff --git a/app/mcp_server.py b/app/mcp_server.py
index 54e3134..8d000d3 100644
--- a/app/mcp_server.py
+++ b/app/mcp_server.py
@@ -42,21 +42,16 @@ _agent_generations: dict[str, int] = {}
 @mcp.tool()
 async def get_user_request(
     agent_id: str = "unknown",
-    wait_seconds: Optional[int] = None,
     default_response_override: Optional[str] = None,
 ) -> dict:
     """
     Fetch the next pending user instruction from the queue.
 
-    The server enforces a minimum wait time (configurable via the web UI).
-    The agent may request a longer wait via `wait_seconds`, but cannot go
-    below that minimum — this prevents busy-polling when the queue is empty.
-    actual_wait = max(wait_seconds or 0, server_min_wait_seconds).
+    If no instruction is available the tool will wait up to `wait_seconds`
+    (or the server-configured default) before returning an empty / default response.
 
     Args:
         agent_id: An identifier for this agent instance (used to track connectivity).
-        wait_seconds: Desired wait when queue is empty. Actual wait is
-                      max(this, server minimum). Omit to use server minimum only.
         default_response_override: Override the server-default empty response text
                                    for this single call.
 
@@ -66,12 +61,8 @@ async def get_user_request(
     """
     cfg = config_service.get_config()
 
-    # default_wait_seconds is the server-enforced MINIMUM wait time.
-    client_requested = wait_seconds if wait_seconds is not None else 0
-    actual_wait = min(
-        max(client_requested, cfg.default_wait_seconds),  # enforce floor
-        _MAX_WAIT_SECONDS,
-    )
+    # Wait time is entirely server-controlled — the user sets it via the web UI.
+    actual_wait = min(cfg.default_wait_seconds, _MAX_WAIT_SECONDS)
 
     # Register this call as the newest for this agent.  Any older coroutines
     # still lingering (e.g. client timed-out and retried) will see a stale