[Bug]: Oversized search limits return HTTP 500 instead of validation errors

[enyst]

Bug Description

Four Agent Server search endpoints declare Query(gt=0, lte=100) for their limit parameter. The supported upper-bound keyword is le, so FastAPI does not enforce the intended maximum. A request with limit=101 reaches assert limit <= 100 and returns HTTP 500. The generated OpenAPI schema also omits maximum: 100.

Affected endpoints:

• GET /api/conversations/search
• GET /api/conversations/{conversation_id}/events/search
• GET /api/bash/bash_events/search
• GET /api/file/search_subdirs

Actual Behavior

On upstream main at b5c8ab950401996f171b29c076900fa22fc80e21, run make build, then reproduce without an LLM or a running server:

uv run python - <<'PY'
from tempfile import TemporaryDirectory

from fastapi import FastAPI
from fastapi.testclient import TestClient

from openhands.agent_server.file_router import file_discovery_router

app = FastAPI()
app.include_router(file_discovery_router, prefix="/api")
with TemporaryDirectory() as directory:
    with TestClient(app, raise_server_exceptions=False) as client:
        for limit in (100, 101, 0):
            response = client.get(
                "/api/file/search_subdirs",
                params={"path": directory, "limit": limit},
            )
            print(f"limit={limit}: HTTP {response.status_code}")

parameters = app.openapi()["paths"]["/api/file/search_subdirs"]["get"]["parameters"]
print(next(p["schema"] for p in parameters if p["name"] == "limit"))
PY

Observed status codes:

limit=100: HTTP 200
limit=101: HTTP 500
limit=0: HTTP 422

The limit schema contains lte: 100 instead of maximum: 100. The other three handlers use the same misspelled constraint and upper-bound assertion. Oversized page requests therefore appear to clients and monitoring as server failures.

Expected Behavior

Requests outside the existing range of 1 through 100 return HTTP 422 with a validation error for the limit query parameter. Valid requests keep working, and OpenAPI publishes the maximum of 100.

Acceptance Criteria

• All four endpoints publish maximum: 100 and an exclusive minimum of 0 for the limit query parameter.
• Requests with limit=0 or limit=101 return HTTP 422 instead of reaching an assertion in the handler.
• The default limit and explicit limit=100 remain valid.

Installation Method

Source checkout with make build / uv sync --dev.

SDK Version

Upstream main at b5c8ab950401996f171b29c076900fa22fc80e21 (1.47.0).

Python Version

3.13.11.

Screenshots and Additional Context

PR #4991 implements this fix. PR #5032 adds the narrowly scoped REST compatibility-check exception for publishing the already enforced upper bound.

[github-actions]

✅ ready-for-dev label applied

This issue meets the readiness criteria and is ready for contribution.
A contributor can now open a PR that links this issue (Fixes #<number>).

This is an automated check — no AI was used to generate this comment.