Skip to content
Python

fix: bound Outlook message pagination

zhouzhuozhzh-makerf209513f4eff
diff --git a/coworker/connectors/integration_tools.py b/coworker/connectors/integration_tools.py
index f0f18d0b..a773b85c 100644
--- a/coworker/connectors/integration_tools.py
+++ b/coworker/connectors/integration_tools.py
@@ -14,7 +14,7 @@ import re
from email.message import EmailMessage
from html.parser import HTMLParser
from typing import Any, Callable, Optional
-from urllib.parse import quote
+from urllib.parse import quote, urlsplit
import aisuite as ai
@@ -135,6 +135,51 @@ _GEN_ACCOUNT_PROP = {
"description": "Which connected account to use (default account when empty)",
}
+_OUTLOOK_SEARCH_MAX_RESULTS = 100
+_OUTLOOK_SEARCH_MAX_PAGES = 100
+_OUTLOOK_MESSAGE_SUMMARY_FIELDS = (
+ "id",
+ "subject",
+ "from",
+ "sender",
+ "receivedDateTime",
+ "sentDateTime",
+ "isRead",
+ "hasAttachments",
+ "importance",
+ "conversationId",
+ "webLink",
+)
+_OUTLOOK_MESSAGE_DETAIL_FIELDS = (
+ *_OUTLOOK_MESSAGE_SUMMARY_FIELDS,
+ "toRecipients",
+ "ccRecipients",
+ "replyTo",
+ "body",
+ "bodyPreview",
+)
+
+
+def _outlook_message_summary(message: Any) -> dict[str, Any]:
+ """Keep mailbox listings compact; full content belongs to get-message."""
+ if not isinstance(message, dict):
+ return {}
+ return {
+ key: message[key]
+ for key in _OUTLOOK_MESSAGE_SUMMARY_FIELDS
+ if key in message
+ }
+
+
+def _is_outlook_graph_url(url: str) -> bool:
+ """Only forward mailbox credentials to the Graph origin we started on."""
+ parsed = urlsplit(url)
+ return (
+ parsed.scheme == "https"
+ and parsed.netloc == "graph.microsoft.com"
+ and parsed.path.startswith("/v1.0/")
+ )
+
def _gmail_profile(
secrets: SecretStore, account: str = ""
@@ -1345,17 +1390,92 @@ def make_integration_tools(
)
if err:
return err
- params = {"$top": max(1, min(int(max_results or 10), 20))}
+ limit = _clamp(
+ max_results, default=10, ceiling=_OUTLOOK_SEARCH_MAX_RESULTS
+ )
+ params = {
+ "$top": limit,
+ "$select": ",".join(_OUTLOOK_MESSAGE_SUMMARY_FIELDS),
+ }
if query:
params["$search"] = f'"{query}"'
+
+ headers = _graph_headers(profile["access_token"])
+ next_url = "https://graph.microsoft.com/v1.0/me/messages"
+ next_params: Optional[dict[str, Any]] = params
+ seen_page_urls: set[str] = set()
+ seen_message_ids: set[str] = set()
+ messages: list[dict[str, Any]] = []
+ pagination_warning = ""
+ pages_fetched = 0
+ page_truncated = False
+
+ while next_url and len(messages) < limit:
+ if next_url in seen_page_urls:
+ pagination_warning = "Microsoft Graph repeated a pagination URL"
+ break
+ if not _is_outlook_graph_url(next_url):
+ pagination_warning = "Microsoft Graph returned an unsafe pagination URL"
+ break
+ if pages_fetched >= _OUTLOOK_SEARCH_MAX_PAGES:
+ pagination_warning = "Microsoft Graph pagination exceeded the page limit"
+ break
+ seen_page_urls.add(next_url)
+ pages_fetched += 1
+ page = _request(
+ "GET",
+ next_url,
+ headers=headers,
+ params=next_params,
+ )
+ if not page.get("ok"):
+ if not messages:
+ return _acct_result(aid, page)
+ pagination_warning = str(
+ page.get("error") or "Microsoft Graph pagination failed"
+ )
+ break
+
+ data = page.get("data")
+ if not isinstance(data, dict):
+ pagination_warning = "Microsoft Graph returned an invalid message page"
+ break
+
+ raw_messages = data.get("value")
+ if not isinstance(raw_messages, list):
+ pagination_warning = "Microsoft Graph returned an invalid message list"
+ break
+
+ for index, raw_message in enumerate(raw_messages):
+ summary = _outlook_message_summary(raw_message)
+ message_id = str(summary.get("id") or "")
+ if message_id and message_id in seen_message_ids:
+ continue
+ if message_id:
+ seen_message_ids.add(message_id)
+ if summary:
+ messages.append(summary)
+ if len(messages) >= limit:
+ page_truncated = index < len(raw_messages) - 1
+ break
+
+ raw_next = data.get("@odata.nextLink")
+ next_url = raw_next if isinstance(raw_next, str) else ""
+ # Graph's nextLink is opaque and already contains the original query.
+ next_params = None
+
+ has_more = bool(next_url) or page_truncated
+ result_data: dict[str, Any] = {
+ "value": messages,
+ "returned_count": len(messages),
+ "has_more": has_more,
+ "query_complete": not has_more,
+ }
+ if pagination_warning:
+ result_data["pagination_warning"] = pagination_warning
return _acct_result(
aid,
- _request(
- "GET",
- "https://graph.microsoft.com/v1.0/me/messages",
- headers=_graph_headers(profile["access_token"]),
- params=params,
- ),
+ {"ok": True, "data": result_data},
)
outlook_search_messages.__name__ = "outlook_search_messages"
@@ -1364,10 +1484,21 @@ def make_integration_tools(
outlook_search_messages,
_schema(
"outlook_search_messages",
- "Search or list Outlook messages through Microsoft Graph.",
+ "Search Outlook and return up to 100 compact message summaries. "
+ "This tool follows Microsoft Graph pagination and deduplicates results. "
+ "When query_complete is false, report that the limit was reached and "
+ "ask the user to narrow the query; do not repeat or broaden the same "
+ "query to paginate. Use outlook_get_message to read a full body.",
{
- "query": {"type": "string"},
- "max_results": {"type": "integer"},
+ "query": {
+ "type": "string",
+ "description": "Microsoft Outlook search expression; keep the user's requested scope unchanged.",
+ },
+ "max_results": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": _OUTLOOK_SEARCH_MAX_RESULTS,
+ },
"account": _GEN_ACCOUNT_PROP,
},
[],
@@ -1376,6 +1507,41 @@ def make_integration_tools(
)
)
+ def outlook_get_message(message_id: str, account: str = "") -> dict[str, Any]:
+ aid, profile, err = _account_profile(
+ secrets, "outlook", account, "access_token"
+ )
+ if err:
+ return err
+ return _acct_result(
+ aid,
+ _request(
+ "GET",
+ "https://graph.microsoft.com/v1.0/me/messages/"
+ f"{quote(message_id, safe='')}",
+ headers=_graph_headers(profile["access_token"]),
+ params={"$select": ",".join(_OUTLOOK_MESSAGE_DETAIL_FIELDS)},
+ ),
+ )
+
+ outlook_get_message.__name__ = "outlook_get_message"
+ tools.append(
+ _attach(
+ outlook_get_message,
+ _schema(
+ "outlook_get_message",
+ "Read one Outlook message, including its body, by the ID returned "
+ "from outlook_search_messages.",
+ {
+ "message_id": {"type": "string"},
+ "account": _GEN_ACCOUNT_PROP,
+ },
+ ["message_id"],
+ ),
+ caps=["outlook", "read"],
+ )
+ )
+
def outlook_send_mail(
to: str, subject: str, body: str, account: str = ""
) -> dict[str, Any]:
diff --git a/coworker/connectors/tool_defs.py b/coworker/connectors/tool_defs.py
index d8b365eb..89ea6df9 100644
--- a/coworker/connectors/tool_defs.py
+++ b/coworker/connectors/tool_defs.py
@@ -250,6 +250,13 @@ TOOL_DEFS: tuple[ConnectorToolDef, ...] = (
"read",
"Search Outlook messages.",
),
+ ConnectorToolDef(
+ "outlook",
+ "outlook_get_message",
+ "Read Outlook message",
+ "read",
+ "Read one Outlook message by ID.",
+ ),
ConnectorToolDef(
"outlook",
"outlook_send_mail",
diff --git a/tests/test_connectors.py b/tests/test_connectors.py
index cb155fa6..20ce3a56 100644
--- a/tests/test_connectors.py
+++ b/tests/test_connectors.py
@@ -1333,6 +1333,183 @@ def test_outlook_managed_multi_account_keys_by_email(tmp_path, monkeypatch):
assert calls[-1]["url"] == "https://graph.microsoft.com/v1.0/me/calendarView"
+def _managed_outlook_tools(tmp_path, monkeypatch, fake_request):
+ import coworker.connectors.integration_tools as it
+ from coworker.cloud import managed_profile_from_callback
+ from coworker.connectors.setup import managed_connect_connector
+
+ secrets = SecretStore(tmp_path / "secrets.json")
+ managed_connect_connector(
+ secrets,
+ "outlook",
+ managed_profile_from_callback(
+ {
+ "access_token": "tok",
+ "account": "[email protected]",
+ "provider": "microsoft",
+ }
+ ),
+ )
+ monkeypatch.setattr(it, "_request", fake_request)
+ return {t.__name__: t for t in it.make_integration_tools(secrets)}
+
+
+def test_outlook_search_paginates_deduplicates_and_reports_completion(
+ tmp_path, monkeypatch
+):
+ """Search owns Graph pagination instead of making the model guess at nextLink."""
+ next_url = "https://graph.microsoft.com/v1.0/me/messages?$skiptoken=opaque"
+ responses = [
+ {
+ "ok": True,
+ "data": {
+ "value": [
+ {"id": "m1", "subject": "One", "body": {"content": "large"}},
+ {"id": "m2", "subject": "Two"},
+ ],
+ "@odata.nextLink": next_url,
+ },
+ },
+ {
+ "ok": True,
+ "data": {
+ "value": [
+ {"id": "m2", "subject": "Two"},
+ {"id": "m3", "subject": "Three"},
+ ]
+ },
+ },
+ ]
+ calls = []
+
+ def fake_request(method, url, *, headers=None, params=None, json=None, auth=None):
+ calls.append({"method": method, "url": url, "params": params})
+ return responses.pop(0)
+
+ tools = _managed_outlook_tools(tmp_path, monkeypatch, fake_request)
+
+ out = tools["outlook_search_messages"](
+ "received:2026-08-06", max_results=3
+ )
+
+ assert [m["id"] for m in out["data"]["value"]] == ["m1", "m2", "m3"]
+ assert "body" not in out["data"]["value"][0]
+ assert out["data"]["returned_count"] == 3
+ assert out["data"]["has_more"] is False
+ assert out["data"]["query_complete"] is True
+ assert "@odata.nextLink" not in out["data"]
+ assert calls[0]["params"]["$top"] == 3
+ assert "$select" in calls[0]["params"]
+ assert calls[1] == {"method": "GET", "url": next_url, "params": None}
+
+
+def test_outlook_search_honors_bounded_result_limit_and_exposes_truncation(
+ tmp_path, monkeypatch
+):
+ calls = []
+
+ def fake_request(method, url, *, headers=None, params=None, json=None, auth=None):
+ calls.append({"url": url, "params": params})
+ return {
+ "ok": True,
+ "data": {
+ "value": [{"id": f"m{i}", "subject": str(i)} for i in range(100)],
+ "@odata.nextLink": "https://graph.microsoft.com/next",
+ },
+ }
+
+ tools = _managed_outlook_tools(tmp_path, monkeypatch, fake_request)
+
+ out = tools["outlook_search_messages"]("q", max_results=1_000)
+
+ assert calls[0]["params"]["$top"] == 100
+ assert out["data"]["returned_count"] == 100
+ assert out["data"]["has_more"] is True
+ assert out["data"]["query_complete"] is False
+ assert len(calls) == 1
+
+
+def test_outlook_search_marks_unconsumed_final_page_as_truncated(
+ tmp_path, monkeypatch
+):
+ responses = [
+ {
+ "ok": True,
+ "data": {
+ "value": [{"id": "m1"}, {"id": "m2"}],
+ "@odata.nextLink": "https://graph.microsoft.com/v1.0/next",
+ },
+ },
+ {
+ "ok": True,
+ "data": {"value": [{"id": "m3"}, {"id": "m4"}, {"id": "m5"}]},
+ },
+ ]
+
+ def fake_request(method, url, *, headers=None, params=None, json=None, auth=None):
+ return responses.pop(0)
+
+ tools = _managed_outlook_tools(tmp_path, monkeypatch, fake_request)
+
+ out = tools["outlook_search_messages"]("q", max_results=3)
+
+ assert [m["id"] for m in out["data"]["value"]] == ["m1", "m2", "m3"]
+ assert out["data"]["has_more"] is True
+ assert out["data"]["query_complete"] is False
+
+
+def test_outlook_search_rejects_untrusted_pagination_url(tmp_path, monkeypatch):
+ calls = []
+
+ def fake_request(method, url, *, headers=None, params=None, json=None, auth=None):
+ calls.append(url)
+ return {
+ "ok": True,
+ "data": {
+ "value": [],
+ "@odata.nextLink": "https://attacker.example/steal-token",
+ },
+ }
+
+ tools = _managed_outlook_tools(tmp_path, monkeypatch, fake_request)
+
+ out = tools["outlook_search_messages"]("no matches")
+
+ assert calls == ["https://graph.microsoft.com/v1.0/me/messages"]
+ assert out["data"]["value"] == []
+ assert out["data"]["query_complete"] is False
+ assert out["data"]["pagination_warning"] == (
+ "Microsoft Graph returned an unsafe pagination URL"
+ )
+
+
+def test_outlook_get_message_fetches_one_full_message(tmp_path, monkeypatch):
+ calls = []
+
+ def fake_request(method, url, *, headers=None, params=None, json=None, auth=None):
+ calls.append({"method": method, "url": url, "params": params})
+ return {"ok": True, "data": {"id": "a/b", "body": {"content": "hello"}}}
+
+ tools = _managed_outlook_tools(tmp_path, monkeypatch, fake_request)
+
+ out = tools["outlook_get_message"]("a/b")
+
+ assert out["data"]["body"]["content"] == "hello"
+ assert calls == [
+ {
+ "method": "GET",
+ "url": "https://graph.microsoft.com/v1.0/me/messages/a%2Fb",
+ "params": {
+ "$select": (
+ "id,subject,from,sender,receivedDateTime,sentDateTime,isRead,"
+ "hasAttachments,importance,conversationId,webLink,toRecipients,"
+ "ccRecipients,replyTo,body,bodyPreview"
+ )
+ },
+ }
+ ]
+
+
def test_outlook_calendar_tools_hit_the_right_graph_endpoints(tmp_path, monkeypatch):
"""The calendar CRUD + invite-response tools map onto Microsoft Graph:
create carries attendees/location/Teams flags, update PATCHes only the