feat(files): add SharePoint file search and site discovery tools

[brandwe]

Problem

Entrabot can operate on a known file or list items already shared with the Agent User, but it cannot discover a relevant file by topic or enumerate accessible SharePoint sites when the user does not already have a URL.

Desired outcome

Add bounded, structured search_files and list_sites tools that use Microsoft Search and SharePoint site discovery without weakening the existing site denylist or permission model.

Recommended priority: P2.

Scope

• Implement search_files through Microsoft Graph Search for driveItem entities.
• Implement list_sites through the supported SharePoint site search endpoint.
• Return typed dataclasses with stable IDs and enough metadata to feed existing file tools.
• Enforce configured site deny rules before returning actionable results.
• Handle pagination, throttling, malformed result entries, and partial pages.
• Document KQL/query limitations and explicit-user-request guidance for tenant-level search.
• Verify existing setup/consent paths include the required Files/Sites permissions.

Non-goals

• Full tenant indexing or a local search crawler.
• Background or speculative searches on every turn.
• Creating sites or document libraries.
• Bypassing access controls or returning results the Agent User cannot access.
• Replacing resolve_file_url or list_recent_files.

Acceptance criteria

• Search and site discovery use stable Graph endpoints and typed result models.
• Results from denied sites are filtered before they reach the model, with a bounded denied count rather than leaked metadata.
• Query, page-size, and maximum-result bounds are validated.
• 429 and transient failures use the established retry helpers and preserve typed errors.
• Pagination and empty/partial result cases are covered by tests.
• Setup documentation and consent scripts are verified against Files.Read.All / Sites.Read.All; no unnecessary permission is added.
• MCP tool docs, configuration guidance, and full pytest/Ruff gates pass.

Sources and related work

• Files platform reference — search and sites
• Deferred Files plan
• Existing direct Graph implementation: src/entrabot/tools/files.py.