Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

116 KB
Raw Blame
import json
import os
import re
from pathlib import Path

import pytest
import requests

from xagent.web.tools.mcp import utils


def test_naive_day_bounds_accepts_a_z_suffixed_datetime():
    assert utils.naive_day_bounds("2026-08-27T23:30:00Z") == (
        "2026-08-27T00:00:00",
        "2026-08-28T00:00:00",
    )


def test_naive_day_bounds_converts_an_instant_before_selecting_the_day():
    assert utils.naive_day_bounds("2026-08-27T20:00:00Z", "Asia/Singapore") == (
        "2026-08-28T00:00:00",
        "2026-08-29T00:00:00",
    )


def test_require_clean_identifier_rejects_empty_and_whitespace():
    with pytest.raises(ValueError, match="record_id"):
        utils.require_clean_identifier("", "record_id")
    with pytest.raises(ValueError, match="record_id"):
        utils.require_clean_identifier(" 001xx ", "record_id")
    assert utils.require_clean_identifier("001xx", "record_id") == "001xx"


def test_require_clean_identifier_rejects_non_string():
    """A truthy non-str (e.g. an int) previously slipped past `not value`
    and crashed on `.strip()` with a raw AttributeError instead of a clean
    ValueError."""
    with pytest.raises(ValueError, match="record_id"):
        utils.require_clean_identifier(12345, "record_id")


def test_require_clean_text_rejects_empty_and_whitespace():
    with pytest.raises(ValueError, match="summary"):
        utils.require_clean_text("", "summary")
    with pytest.raises(ValueError, match="summary"):
        utils.require_clean_text("  padded  ", "summary")
    assert utils.require_clean_text("Fix the bug", "summary") == "Fix the bug"


def test_require_clean_text_rejects_non_string():
    with pytest.raises(ValueError, match="summary"):
        utils.require_clean_text(12345, "summary")


def test_require_clean_text_message_does_not_call_the_field_an_id():
    # The whole point of this helper (vs. require_clean_identifier) is a
    # message phrased for a human-facing field like a title or name, not an
    # id -- regressing back to "id" wording defeats that.
    with pytest.raises(ValueError) as excinfo:
        utils.require_clean_text("", "summary")
    assert "id" not in str(excinfo.value)


def test_url_path_id_percent_encodes_reserved_characters():
    # A literal ".." blocklist misses "/" and "?", which redirect the
    # request to a different endpoint or inject query params without ever
    # containing "..". Percent-encoding closes off all of them at once.
    assert utils.url_path_id("Account/001abc", "sobject_type") == ("Account%2F001abc")
    assert utils.url_path_id("001x?fields=Id", "record_id") == ("001x%3Ffields%3DId")
    with pytest.raises(ValueError):
        utils.url_path_id("", "record_id")


def test_url_path_id_rejects_exact_dot_segments():
    # "." and ".." are always-unreserved characters -- quote() never
    # touches them, and requests/urllib3 collapse dot-segments out of the
    # final URL before sending it, so percent-encoding alone can't close
    # this off the way it does for "/" and "?".
    with pytest.raises(ValueError, match="record_id"):
        utils.url_path_id("..", "record_id")
    with pytest.raises(ValueError, match="record_id"):
        utils.url_path_id(".", "record_id")


@pytest.mark.parametrize(
    "limit,expected",
    [
        (50, 50),  # within range, passed through unchanged
        (1, 1),  # lower boundary, passed through unchanged
        (200, 200),  # exactly max_limit, passed through unchanged
        (201, 200),  # just above max_limit, clamped down
        (10**9, 200),  # extreme, clamped down the same as a mild overage
        (0, 1),  # zero would slice to an empty page forever -- clamped up
        (-1, 1),  # mild negative, clamped up
        (-(10**9), 1),  # extreme negative, clamped up the same as mild
    ],
)
def test_clamp_limit_boundaries(limit, expected):
    assert utils.clamp_limit(limit, max_limit=200) == expected


@pytest.mark.parametrize(
    "offset,expected",
    [
        (0, 0),
        (5, 5),
        (-1, 0),  # mild negative -- would slice from the end unclamped
        (-(10**9), 0),  # extreme negative, clamped the same as mild
    ],
)
def test_clamp_offset_boundaries(offset, expected):
    assert utils.clamp_offset(offset) == expected


_TEST_URL_ID_PATTERN = re.compile(r"/d/([a-zA-Z0-9_-]+)")


def test_resolve_id_from_url_extracts_id_from_matching_url():
    assert (
        utils.resolve_id_from_url(
            "https://docs.google.com/document/d/abc123/edit",
            _TEST_URL_ID_PATTERN,
            "document_id",
        )
        == "abc123"
    )


def test_resolve_id_from_url_passes_through_bare_id():
    assert (
        utils.resolve_id_from_url(" abc123 ", _TEST_URL_ID_PATTERN, "document_id")
        == "abc123"
    )


def test_resolve_id_from_url_rejects_non_string():
    """Mirrors require_clean_identifier's fix: pattern.search() would
    otherwise raise a raw TypeError on a non-string value instead of a
    clean ValueError."""
    with pytest.raises(ValueError, match="document_id"):
        utils.resolve_id_from_url(12345, _TEST_URL_ID_PATTERN, "document_id")


def test_parse_rrule_extracts_components():
    parts = utils.parse_rrule(
        "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;UNTIL=20260911T235959Z",
        "2026-08-26T07:00:00+08:00",
    )
    assert parts == {
        "FREQ": "WEEKLY",
        "BYDAY": "MO,TU,WE,TH,FR",
        "UNTIL": "20260911T235959Z",
    }


def test_parse_rrule_accepts_and_strips_rrule_prefix():
    parts = utils.parse_rrule("RRULE:FREQ=DAILY;COUNT=5", "2026-08-26T07:00:00+08:00")
    assert parts == {"FREQ": "DAILY", "COUNT": "5"}


def test_ensure_rrule_prefix_adds_prefix_and_uppercases():
    assert utils.ensure_rrule_prefix("FREQ=DAILY;COUNT=5") == "RRULE:FREQ=DAILY;COUNT=5"


def test_ensure_rrule_prefix_keeps_existing_prefix_and_uppercases():
    assert (
        utils.ensure_rrule_prefix("rrule:freq=weekly;byday=mo,tu")
        == "RRULE:FREQ=WEEKLY;BYDAY=MO,TU"
    )


def test_ensure_rrule_prefix_rejects_embedded_newlines():
    with pytest.raises(ValueError, match="embedded newlines"):
        utils.ensure_rrule_prefix("FREQ=DAILY\nEXDATE:20260902")


def test_is_bare_date_accepts_a_bare_date():
    assert utils.is_bare_date("2026-08-26")


def test_is_bare_date_rejects_a_datetime():
    assert not utils.is_bare_date("2026-08-26T07:00:00")


def test_is_bare_date_rejects_a_space_separated_datetime():
    assert not utils.is_bare_date("2026-08-26 07:00:00")


def test_is_bare_date_accepts_surrounding_whitespace():
    assert utils.is_bare_date("  2026-08-26  ")


@pytest.mark.parametrize(
    "value",
    ["2026-2-3", "2026-02-30", "2026-13-01", "0000-01-01"],
)
def test_is_bare_date_rejects_noncanonical_or_impossible_dates(value):
    assert not utils.is_bare_date(value)


def test_is_bare_date_rejects_non_ascii_digit_lookalikes():
    """Confirmed bug: str.isdigit() also accepts non-ASCII digit
    lookalikes (superscript, Thai, fullwidth, ...), unlike the ASCII-only
    _DIGITS_ONLY_RE this file already uses elsewhere for the identical
    risk (see parse_rrule's INTERVAL/COUNT validation). A misclassified
    value here reaches a Google Calendar request body's "date" field with
    no further local validation, unlike parse_rrule's own path."""
    assert not utils.is_bare_date("²⁰²⁶-08-26")
    assert not utils.is_bare_date("๒๐๒๖-08-26")


def test_ensure_rrule_prefix_normalizes_lowercase_rrule():
    """RFC 5545's RRULE grammar has no case-sensitive free-text values, so
    a fully lowercase rule (which parse_rrule's dateutil-backed validation
    tolerates) must still reach the calendar API canonicalized to
    uppercase - not sent verbatim in whatever case an LLM happened to
    produce."""
    assert (
        utils.ensure_rrule_prefix(
            "freq=weekly;byday=mo,tu,we,th,fr;until=20260911t235959z"
        )
        == "RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;UNTIL=20260911T235959Z"
    )


def test_parse_rrule_rejects_empty_string():
    with pytest.raises(ValueError, match="must not be empty"):
        utils.parse_rrule("", "2026-08-26T07:00:00+08:00")
    with pytest.raises(ValueError, match="must not be empty"):
        utils.parse_rrule("RRULE:", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_missing_freq():
    with pytest.raises(ValueError, match="FREQ"):
        utils.parse_rrule("BYDAY=MO,TU", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_malformed_component():
    with pytest.raises(ValueError, match="invalid recurrence rule component"):
        utils.parse_rrule("FREQ=DAILY;BOGUS", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_duplicate_keys():
    """A duplicate key (e.g. FREQ specified twice) would otherwise
    silently keep only the last occurrence in the returned dict for local
    validation, while the raw text - still containing BOTH occurrences -
    reaches Google's API close to verbatim, where its behavior is
    unspecified rather than matching whatever this function validated."""
    with pytest.raises(ValueError, match="FREQ is specified more than once"):
        utils.parse_rrule("FREQ=DAILY;FREQ=WEEKLY", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_unparseable_rule():
    """A syntactically plausible but semantically invalid rule (an unknown
    FREQ value) must be rejected, not silently accepted as valid RFC 5545
    - this is exactly the class of bug the connector shipped with before:
    a recurrence rule that only ever looks valid, never actually works."""
    with pytest.raises(ValueError, match="invalid recurrence rule"):
        utils.parse_rrule("FREQ=FORTNIGHTLY", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_bad_dtstart():
    with pytest.raises(ValueError, match="invalid start time"):
        utils.parse_rrule("FREQ=DAILY", "not-a-date")


def test_parse_rrule_rejects_an_extended_iso8601_until_with_a_clean_message():
    """Confirmed bug: dateutil's own isoparse is lenient enough to accept
    ISO8601's extended form for UNTIL (dashes/colons, e.g.
    "2026-09-11T23:59:59+08:00"), which RFC 5545 never permits - UNTIL
    must be RFC 5545's basic form. dateutil.rrule.rrulestr's own RFC 5545
    line parser chokes on the extended form with a raw, uninformative
    "too many values to unpack" instead of this function's own clean
    error - must be caught here directly."""
    with pytest.raises(ValueError, match="must be RFC 5545's basic form"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=2026-09-11T23:59:59+08:00",
            "2026-09-01T07:00:00+08:00",
        )


def test_parse_rrule_accepts_a_floating_local_time_until():
    """Confirmed bug: the previous fix for the extended-ISO8601 UNTIL
    problem was too strict - RFC 5545 permits UNTIL as a floating "DATE
    WITH LOCAL TIME" (no "Z") whenever DTSTART is also floating local
    time, not only the aware "DATE WITH UTC TIME" form. This combination
    was wrongly rejected with no test catching the regression."""
    parts = utils.parse_rrule("FREQ=DAILY;UNTIL=20260911T235959", "2026-08-26T07:00:00")
    assert parts["UNTIL"] == "20260911T235959"


def test_parse_rrule_uppercases_component_values_not_just_keys():
    """Confirmed bug: only the FREQ/UNTIL/etc. *keys* were uppercased, not
    their values - a lowercase "freq=daily" produced {"FREQ": "daily"}.
    RFC 5545's RRULE grammar has no case-sensitive free-text values (the
    same reasoning ensure_rrule_prefix already applies to the whole rule
    text), and this returned dict is what a future Outlook translator
    would key lookups against."""
    parts = utils.parse_rrule("freq=daily;count=3", "2026-08-26T07:00:00")
    assert parts == {"FREQ": "DAILY", "COUNT": "3"}


def test_parse_rrule_accepts_a_datetime_object_directly():
    """A caller that already has a datetime (e.g. after localizing a naive
    Outlook start time) shouldn't need to format it back into a string
    just to have it reparsed here."""
    from datetime import datetime, timezone

    parts = utils.parse_rrule(
        "FREQ=DAILY;UNTIL=20260911T235959Z",
        datetime(2026, 8, 26, 7, 0, 0, tzinfo=timezone.utc),
    )
    assert parts == {"FREQ": "DAILY", "UNTIL": "20260911T235959Z"}


def test_parse_rrule_rejects_until_before_dtstart():
    """dateutil's own rrulestr validation does NOT catch this - an UNTIL
    before dtstart parses fine and just silently yields zero occurrences,
    which would otherwise report status=success for a "recurring" event
    that never actually recurs. This must be checked explicitly."""
    from datetime import datetime, timezone

    with pytest.raises(ValueError, match="before the start time"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260101T000000Z",
            datetime(2026, 6, 1, tzinfo=timezone.utc),
        )


def test_parse_rrule_allows_until_after_dtstart():
    from datetime import datetime, timezone

    parts = utils.parse_rrule(
        "FREQ=DAILY;UNTIL=20260601T000000Z",
        datetime(2026, 1, 1, tzinfo=timezone.utc),
    )
    assert parts["UNTIL"] == "20260601T000000Z"


def test_parse_rrule_naive_dtstart_with_utc_until_is_rejected_by_dateutil_itself():
    """A naive dtstart combined with a "Z"-suffixed (UTC/aware) UNTIL is
    already rejected by dateutil's own rrulestr validation before this
    function's explicit UNTIL-vs-dtstart check ever runs - documented here
    so the anchor.tzinfo guard in that check (added for exactly this kind
    of aware/naive mismatch) isn't mistaken for dead code: dateutil catches
    this shape first, with its own message."""
    from datetime import datetime

    with pytest.raises(ValueError, match="invalid recurrence rule"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260101T000000Z",
            datetime(2026, 6, 1),
        )


def test_parse_rrule_all_day_bare_date_until_is_accepted():
    """Confirmed bug: a bare (no-time) UNTIL is the RFC 5545-correct value
    type for a DATE (all-day) DTSTART, but localizing a naive anchor
    whenever `timezone` was given - added to fix the "Z"-suffixed-UNTIL
    case above - broke this opposite case by forcing the anchor aware
    while UNTIL stayed naive, a new mismatch. The anchor must only be
    localized when UNTIL itself is aware."""
    parts = utils.parse_rrule(
        "FREQ=DAILY;UNTIL=20260911", "2026-08-26", timezone="Asia/Shanghai"
    )
    assert parts["UNTIL"] == "20260911"


def test_parse_rrule_all_day_bare_date_until_before_start_is_still_rejected():
    """The before-start guard must still catch this now-naive-vs-naive
    comparison, not just the aware-vs-aware case."""
    with pytest.raises(ValueError, match="before the start time"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260101", "2026-08-26", timezone="Asia/Shanghai"
        )


@pytest.mark.parametrize(
    "until",
    ["20260911T235959", "20260911T235959Z"],
)
def test_parse_rrule_rejects_datetime_until_for_all_day_start(until):
    with pytest.raises(ValueError, match="same DATE or DATE-TIME value type"):
        utils.parse_rrule(
            f"FREQ=DAILY;UNTIL={until}",
            "2026-08-26",
            timezone="Asia/Shanghai",
        )


def test_parse_rrule_rejects_date_until_for_floating_timed_start():
    with pytest.raises(ValueError, match="same DATE or DATE-TIME value type"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260911",
            "2026-08-26T07:00:00",
        )


@pytest.mark.parametrize("part", ["BYSECOND=10", "BYMINUTE=30", "BYHOUR=9"])
def test_parse_rrule_rejects_time_parts_for_all_day_start(part):
    with pytest.raises(ValueError, match="all-day DATE start"):
        utils.parse_rrule(f"FREQ=DAILY;{part};COUNT=3", "2026-08-26")


@pytest.mark.parametrize(
    ("rule", "message"),
    [
        ("FREQ=DAILY;BYDAY=1MO;COUNT=3", "numeric BYDAY"),
        ("FREQ=YEARLY;BYWEEKNO=1;BYDAY=1MO;COUNT=3", "numeric BYDAY"),
        ("FREQ=WEEKLY;BYMONTHDAY=1;COUNT=3", "BYMONTHDAY"),
        ("FREQ=DAILY;BYYEARDAY=1;COUNT=3", "BYYEARDAY"),
        ("FREQ=MONTHLY;BYWEEKNO=1;COUNT=3", "BYWEEKNO"),
        ("FREQ=MONTHLY;BYSETPOS=1;COUNT=3", "BYSETPOS"),
    ],
)
def test_parse_rrule_rejects_invalid_frequency_combinations(rule, message):
    with pytest.raises(ValueError, match=message):
        utils.parse_rrule(rule, "2026-08-26T07:00:00")


@pytest.mark.parametrize(
    ("rule", "expected"),
    [
        (
            "FREQ=MONTHLY;BYDAY=1MO;COUNT=3",
            {"FREQ": "MONTHLY", "BYDAY": "1MO", "COUNT": "3"},
        ),
        (
            "FREQ=YEARLY;BYWEEKNO=1;BYDAY=MO;COUNT=3",
            {"FREQ": "YEARLY", "BYWEEKNO": "1", "BYDAY": "MO", "COUNT": "3"},
        ),
        (
            "FREQ=YEARLY;BYYEARDAY=1;COUNT=3",
            {"FREQ": "YEARLY", "BYYEARDAY": "1", "COUNT": "3"},
        ),
        (
            "FREQ=MONTHLY;BYMONTHDAY=1;BYSETPOS=1;COUNT=3",
            {
                "FREQ": "MONTHLY",
                "BYMONTHDAY": "1",
                "BYSETPOS": "1",
                "COUNT": "3",
            },
        ),
    ],
)
def test_parse_rrule_accepts_valid_frequency_combinations(rule, expected):
    assert utils.parse_rrule(rule, "2026-08-26T07:00:00") == expected


def test_parse_rrule_strips_string_dtstart_before_parsing():
    assert utils.parse_rrule("FREQ=DAILY;COUNT=3", "  2026-08-26T07:00:00  ") == {
        "FREQ": "DAILY",
        "COUNT": "3",
    }


def test_parse_rrule_reports_invalid_byday_without_calling_it_numeric():
    with pytest.raises(ValueError, match="invalid recurrence rule") as exc_info:
        utils.parse_rrule("FREQ=FORTNIGHTLY;BYDAY=MOO", "2026-08-26T07:00:00")
    assert "numeric BYDAY" not in str(exc_info.value)


def test_parse_rrule_rejects_space_separated_dtstart_paired_with_bare_date_until():
    """Confirmed bug: RFC3339 permits a space in place of "T" as the
    date/time separator, so a check that only looked for the absence of
    "t" misclassified a timed dtstart like "2026-08-26 07:00:00" as an
    all-day DATE. That let it silently pair with a floating (bare-date)
    UNTIL instead of being rejected as the DATE-TIME-dtstart/floating-
    UNTIL mismatch it actually is."""
    with pytest.raises(ValueError, match="invalid recurrence rule"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260911",
            "2026-08-26 07:00:00",
            timezone="Asia/Shanghai",
        )


def test_parse_rrule_timezone_localizes_naive_dtstart_for_utc_until():
    """Confirmed bug: unlike the previous test (no timezone given), passing
    a resolvable IANA timezone must localize a naive dtstart so it can be
    compared against a "Z"-suffixed UNTIL instead of dateutil rejecting the
    aware/naive mismatch."""
    parts = utils.parse_rrule(
        "FREQ=DAILY;UNTIL=20260911T235959Z",
        "2026-08-26T07:00:00",
        timezone="Asia/Shanghai",
    )
    assert parts["UNTIL"] == "20260911T235959Z"


def test_parse_rrule_timezone_still_rejects_until_before_dtstart():
    with pytest.raises(ValueError, match="before the start time"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260101T000000Z",
            "2026-08-26T07:00:00",
            timezone="Asia/Shanghai",
        )


def test_parse_rrule_rejects_unknown_timezone():
    with pytest.raises(ValueError, match="recognized IANA zone name"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260911T235959Z",
            "2026-08-26T07:00:00",
            timezone="Not/ARealZone",
        )


def test_parse_rrule_rejects_non_positive_interval():
    with pytest.raises(ValueError, match="INTERVAL must be a positive integer"):
        utils.parse_rrule("FREQ=DAILY;INTERVAL=0", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_non_integer_interval():
    with pytest.raises(ValueError, match="INTERVAL must be an integer"):
        utils.parse_rrule("FREQ=DAILY;INTERVAL=abc", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_non_positive_count():
    with pytest.raises(ValueError, match="COUNT must be a positive integer"):
        utils.parse_rrule("FREQ=DAILY;COUNT=0", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_non_integer_count():
    with pytest.raises(ValueError, match="COUNT must be an integer"):
        utils.parse_rrule("FREQ=DAILY;COUNT=abc", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_signed_interval():
    """RFC 5545 defines INTERVAL as `1*DIGIT` - plain unsigned digits only.
    Python's int() is more permissive than that grammar (accepts a leading
    "+"/"-"), and the raw string (not the parsed int) is what reaches
    Google's API almost verbatim - so a value int() accepts but RFC 5545
    doesn't must still be rejected here, not just range-checked once
    parsed."""
    with pytest.raises(ValueError, match="INTERVAL must be an integer"):
        utils.parse_rrule("FREQ=DAILY;INTERVAL=+2", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_rejects_underscore_separated_count():
    """Python's int() accepts PEP 515 "_" digit separators ("1_0" == 10),
    which isn't valid RFC 5545 RRULE syntax and would reach Google's API as
    literal, malformed text."""
    with pytest.raises(ValueError, match="COUNT must be an integer"):
        utils.parse_rrule("FREQ=DAILY;COUNT=1_0", "2026-08-26T07:00:00+08:00")


def test_parse_rrule_accepts_interval_with_leading_zeros():
    """Unlike a sign or underscore separator, leading zeros ARE valid under
    RFC 5545's `1*DIGIT` grammar and must still be accepted."""
    parts = utils.parse_rrule("FREQ=DAILY;INTERVAL=007", "2026-08-26T07:00:00+08:00")
    assert parts["INTERVAL"] == "007"


def test_parse_rrule_rejects_until_and_count_together():
    """RFC 5545 treats UNTIL and COUNT as mutually exclusive ways to end a
    series - dateutil's own rrulestr validation does not catch this
    (COUNT simply wins), so it must be checked explicitly."""
    with pytest.raises(ValueError, match="must not specify both UNTIL and COUNT"):
        utils.parse_rrule(
            "FREQ=DAILY;UNTIL=20260911T235959Z;COUNT=5",
            "2026-08-26T07:00:00+08:00",
        )


def test_parse_rrule_rejects_embedded_newline():
    """A newline could smuggle an extra RRULE/EXDATE/RDATE line into the
    calendar API request past this connector's single-RRULE validation."""
    with pytest.raises(ValueError, match="embedded newlines"):
        utils.parse_rrule(
            "FREQ=DAILY\nEXDATE:20260101T000000Z",
            "2026-08-26T07:00:00+08:00",
        )


def test_resolve_zoneinfo_returns_zoneinfo_for_valid_iana_name():
    from zoneinfo import ZoneInfo

    assert utils.resolve_zoneinfo("Asia/Shanghai") == ZoneInfo("Asia/Shanghai")


@pytest.mark.parametrize(
    ("windows_name", "iana_name"),
    [
        ("China Standard Time", "Asia/Shanghai"),
        ("Central Asia Standard Time", "Asia/Bishkek"),
        ("E. Europe Standard Time", "Europe/Chisinau"),
        ("Mountain Standard Time (Mexico)", "America/Mazatlan"),
        ("Aleutian Standard Time", "America/Adak"),
        ("UTC-11", "Etc/GMT+11"),
        ("Yukon Standard Time", "America/Whitehorse"),
    ],
)
def test_resolve_zoneinfo_accepts_windows_timezone_names_when_enabled(
    windows_name, iana_name
):
    from zoneinfo import ZoneInfo

    assert utils.resolve_zoneinfo(windows_name, allow_windows_names=True) == ZoneInfo(
        iana_name
    )


def test_resolve_zoneinfo_rejects_windows_timezone_names_by_default():
    with pytest.raises(ValueError, match="recognized IANA zone name"):
        utils.resolve_zoneinfo("Eastern Standard Time")


def test_resolve_zoneinfo_rejects_unknown_timezone():
    with pytest.raises(ValueError, match="recognized IANA zone name"):
        utils.resolve_zoneinfo("Not/ARealZone")


def test_url_path_id_output_survives_requests_url_normalization():
    """Confirms the actual exploit this guards against: a naively
    interpolated ".." collapses the path via requests' own URL
    normalization to a completely different (still valid) endpoint."""
    prepared = requests.Request(
        "GET", "https://acme.my.salesforce.com/services/data/v59.0/sobjects/Account/.."
    ).prepare()
    assert (
        prepared.url == "https://acme.my.salesforce.com/services/data/v59.0/sobjects/"
    )

    with pytest.raises(ValueError):
        utils.url_path_id("..", "record_id")


_TEST_ALLOWED_DIRS_ENV_VAR = "XAGENT_TEST_FILE_ALLOWED_DIRS"


def test_allowed_dirs_from_env_falls_back_to_cwd_when_unset(monkeypatch):
    monkeypatch.delenv(_TEST_ALLOWED_DIRS_ENV_VAR, raising=False)
    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == [
        Path.cwd().resolve()
    ]


def test_allowed_dirs_from_env_falls_back_to_cwd_when_blank(monkeypatch):
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, "   ")
    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == [
        Path.cwd().resolve()
    ]


@pytest.mark.parametrize("raw_value", [",", " , ", ",,,"])
def test_allowed_dirs_from_env_denies_entryless_legacy_value(monkeypatch, raw_value):
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, raw_value)
    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == []


def test_allowed_dirs_from_env_parses_multiple_dirs_with_whitespace(
    monkeypatch, tmp_path
):
    dir_a = tmp_path / "a"
    dir_b = tmp_path / "b"
    dir_a.mkdir()
    dir_b.mkdir()
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, f" {dir_a} , {dir_b} ")

    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == [
        dir_a.resolve(),
        dir_b.resolve(),
    ]


def test_allowed_dirs_from_env_parses_json_paths_containing_commas(
    monkeypatch, tmp_path
):
    directory = tmp_path / "reports,final"
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, json.dumps([str(directory)]))

    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == [
        directory.resolve()
    ]


@pytest.mark.parametrize("raw_value", ["[]", '[""]', '["   "]'])
def test_allowed_dirs_from_env_treats_empty_json_paths_as_deny_all(
    monkeypatch, raw_value
):
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, raw_value)

    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == []


@pytest.mark.parametrize("raw_value", ["[", '["ok", 42]'])
def test_allowed_dirs_from_env_rejects_invalid_json(monkeypatch, raw_value):
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, raw_value)

    with pytest.raises(ValueError, match="JSON array"):
        utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR)


@pytest.mark.skipif(os.name == "nt", reason="symlink creation requires privileges")
def test_allowed_dirs_from_env_rejects_unresolvable_path(monkeypatch, tmp_path):
    loop = tmp_path / "loop"
    loop.symlink_to(loop)
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, json.dumps([str(loop)]))

    with pytest.raises(ValueError, match="invalid path") as exc_info:
        utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR)
    assert str(loop) not in str(exc_info.value)


def test_allowed_dirs_from_env_expands_user_home(monkeypatch, tmp_path):
    monkeypatch.setenv("HOME", str(tmp_path))
    monkeypatch.setenv(_TEST_ALLOWED_DIRS_ENV_VAR, "~/workspace")

    assert utils.allowed_dirs_from_env(_TEST_ALLOWED_DIRS_ENV_VAR) == [
        (tmp_path / "workspace").resolve()
    ]


def test_datetime_key_for_comparison_truncates_seven_digit_fractional_seconds():
    """Outlook commonly reports 100-nanosecond (7-digit) fractional
    seconds, one more digit than a microsecond can hold - this must not
    depend on whichever CPython version happens to run it."""
    key = utils.datetime_key_for_comparison("2026-08-27T10:00:00.1234567")
    assert key == utils.datetime_key_for_comparison("2026-08-27T10:00:00.123456")


def test_datetime_key_for_comparison_treats_equal_instants_as_equal_across_offsets():
    z_form = utils.datetime_key_for_comparison("2026-08-27T02:00:00Z")
    offset_form = utils.datetime_key_for_comparison("2026-08-27T10:00:00+08:00")
    assert z_form == offset_form


def test_datetime_key_for_comparison_falls_back_to_raw_string_on_malformed_input():
    assert utils.datetime_key_for_comparison("not-a-date") == "not-a-date"


def test_datetime_key_for_comparison_passes_none_through():
    assert utils.datetime_key_for_comparison(None) is None


def test_normalize_addresses_drops_case_insensitive_duplicates():
    """Regression test: email addresses are case-insensitive, so the same
    person listed twice with different casing must not become two separate
    attendee entries downstream - keeps the first casing seen."""
    assert utils.normalize_addresses(
        ["[email protected]", "[email protected]", "[email protected]"]
    ) == ["[email protected]", "[email protected]"]


def test_normalize_addresses_dedup_works_for_comma_separated_string_input():
    assert utils.normalize_addresses("[email protected], [email protected], [email protected]") == [
        "[email protected]",
        "[email protected]",
    ]


def test_attendees_were_given_treats_empty_string_as_not_provided():
    assert utils.attendees_were_given(None) is False
    assert utils.attendees_were_given("") is False


def test_attendees_were_given_treats_empty_list_as_provided():
    """An explicit [] is a deliberate "clear everyone" - distinct from
    not-provided, unlike an empty string."""
    assert utils.attendees_were_given([]) is True
    assert utils.attendees_were_given(["[email protected]"]) is True
    assert utils.attendees_were_given("[email protected]") is True


def test_attendees_to_add_filters_out_existing_and_normalizes():
    assert utils.attendees_to_add(
        ["[email protected]", "[email protected]"], {"[email protected]"}
    ) == ["[email protected]"]


def test_attendees_to_add_returns_empty_for_not_provided_or_empty():
    assert utils.attendees_to_add(None, {"[email protected]"}) == []
    assert utils.attendees_to_add("", {"[email protected]"}) == []
    assert utils.attendees_to_add([], {"[email protected]"}) == []


def test_merge_scope_error_reraises_when_no_conflict_is_known():
    error = utils.InsufficientScopeError(
        "reconnect required", [], ["[email protected]"]
    )

    with pytest.raises(utils.InsufficientScopeError) as raised:
        utils.merge_scope_error(error, [], [])

    assert raised.value is error


def test_merge_scope_error_preserves_confirmed_results():
    existing_conflict = {"calendar": "organizer"}
    error_conflict = {"calendar": "[email protected]"}
    error = utils.InsufficientScopeError(
        "reconnect required", [error_conflict], ["[email protected]"]
    )

    conflicts, unchecked = utils.merge_scope_error(
        error, [existing_conflict], ["[email protected]"]
    )

    assert conflicts == [existing_conflict, error_conflict]
    assert unchecked == [
        "[email protected]",
        "[email protected]",
    ]


def _key(value: str):
    return utils.datetime_key_for_comparison(value)


def test_window_delta_segments_empty_for_unchanged_or_shrunk_window():
    """A retained attendee's own busy block already covers everything
    inside the old window - a new window that's identical, or a strict
    subset of it, adds no territory worth checking them against."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    assert utils.window_delta_segments(old_start, old_end, old_start, old_end) == []

    shrunk_start = _key("2026-08-27T10:05:00+00:00")
    shrunk_end = _key("2026-08-27T10:25:00+00:00")
    assert (
        utils.window_delta_segments(old_start, old_end, shrunk_start, shrunk_end) == []
    )


def test_window_delta_segments_returns_the_new_only_portion_of_a_partial_nudge():
    """10:00-10:30 nudged to 10:15-10:45 - only 10:30-10:45 is new
    territory a retained attendee could have a genuine conflict in;
    10:15-10:30 is still covered by their busy block for this event."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    new_start, new_end = (
        _key("2026-08-27T10:15:00+00:00"),
        _key("2026-08-27T10:45:00+00:00"),
    )

    segments = utils.window_delta_segments(old_start, old_end, new_start, new_end)

    assert segments == [(old_end, new_end)]


def test_window_delta_segments_normalizes_iso_strings_internally():
    assert utils.window_delta_segments(
        "2026-08-27T10:00:00+00:00",
        "2026-08-27T10:30:00+00:00",
        "2026-08-27T10:15:00+00:00",
        "2026-08-27T10:45:00+00:00",
    ) == [
        (
            utils.datetime_key_for_comparison("2026-08-27T10:30:00+00:00"),
            utils.datetime_key_for_comparison("2026-08-27T10:45:00+00:00"),
        )
    ]


def test_window_delta_segments_returns_two_segments_when_widened_on_both_sides():
    """Extending a meeting earlier AND later in the same call creates new
    territory on both sides of the old window."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    new_start, new_end = (
        _key("2026-08-27T09:45:00+00:00"),
        _key("2026-08-27T10:45:00+00:00"),
    )

    segments = utils.window_delta_segments(old_start, old_end, new_start, new_end)

    assert len(segments) == 2
    assert segments[0] == (new_start, old_start)
    assert segments[1] == (old_end, new_end)


def test_window_delta_segments_returns_the_whole_window_for_a_disjoint_move():
    """A move to somewhere with zero overlap with the old window means the
    entire new window is new territory - this test also confirms the
    move-by-15-minutes example from the actual reported bug is caught:
    the delta segment here is the same shape as the disjoint case."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    new_start, new_end = (
        _key("2026-08-27T14:00:00+00:00"),
        _key("2026-08-27T14:30:00+00:00"),
    )

    assert utils.window_delta_segments(old_start, old_end, new_start, new_end) == [
        (new_start, new_end)
    ]


def test_window_delta_segments_is_conservative_on_unparseable_or_mismatched_keys():
    """ "Can't confirm the delta is smaller than the whole window" must
    never silently shrink what gets checked - falls back to the whole new
    window, both for a key that never parsed to a real datetime, and for
    two real datetimes that can't be compared (aware vs. naive raises
    TypeError on `<`)."""
    new_start, new_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    assert utils.window_delta_segments(
        "not-a-date", "also-not", new_start, new_end
    ) == [(new_start, new_end)]

    naive_start = _key("2026-08-27T09:00:00")
    naive_end = _key("2026-08-27T11:00:00")
    assert utils.window_delta_segments(naive_start, naive_end, new_start, new_end) == [
        (new_start, new_end)
    ]


def test_window_delta_segments_empty_when_new_window_itself_is_unparseable():
    """No valid new window at all means nothing meaningful to check,
    regardless of the old window."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    assert (
        utils.window_delta_segments(old_start, old_end, "not-a-date", "also-not") == []
    )


def test_window_delta_segments_empty_when_only_one_of_the_new_window_parses():
    """Regression test: the guard is `new_start AND new_end` both being
    real datetimes - a MIXED pair (one parses, one doesn't) must still
    return [], not fall through and try to build a segment out of a
    half-valid window. A prior test only exercised BOTH sides failing
    together, which can't tell `and` apart from a mistakenly-broadened
    `or` in that guard - this fixture, with exactly one side invalid,
    can."""
    old_start, old_end = (
        _key("2026-08-27T10:00:00+00:00"),
        _key("2026-08-27T10:30:00+00:00"),
    )
    new_start = _key("2026-08-27T14:00:00+00:00")
    assert utils.window_delta_segments(old_start, old_end, new_start, "also-not") == []
    assert (
        utils.window_delta_segments(old_start, old_end, "not-a-date", new_start) == []
    )


def test_reject_reversed_window_raises_when_end_is_not_after_start():
    with pytest.raises(ValueError, match="must be after"):
        utils.reject_reversed_window(
            "2026-08-27T10:30:00+00:00", "2026-08-27T10:00:00+00:00"
        )
    with pytest.raises(ValueError, match="must be after"):
        utils.reject_reversed_window(
            "2026-08-27T10:00:00+00:00", "2026-08-27T10:00:00+00:00"
        )


def test_reject_reversed_window_allows_a_forward_window():
    utils.reject_reversed_window(
        "2026-08-27T10:00:00+00:00", "2026-08-27T10:30:00+00:00"
    )


def test_reject_reversed_window_is_permissive_on_unparseable_input():
    """Can't-tell must never read as "reject" - only a confirmed reversal
    should raise."""
    utils.reject_reversed_window("not-a-date", "also-not-a-date")


def test_reject_reversed_window_is_permissive_when_aware_and_naive_are_mixed():
    """Regression test: both sides parse to real `datetime` instances, but
    comparing an offset-aware one against a naive one with `<=` raises
    `TypeError` in Python - the `isinstance` check alone doesn't guard
    against this, only checking that both are `datetime` instances of the
    SAME awareness does. Must stay permissive here, not crash with a raw
    TypeError, matching `window_delta_segments`'s handling of the
    identical hazard."""
    utils.reject_reversed_window("2026-08-27T10:30:00", "2026-08-27T10:30:00Z")
    utils.reject_reversed_window("2026-08-27T10:30:00Z", "2026-08-27T10:00:00")


def test_require_offset_datetime_rejects_a_naive_value():
    with pytest.raises(ValueError, match="start_time"):
        utils.require_offset_datetime("2026-08-27T10:30:00", "start_time")


def test_require_offset_datetime_accepts_an_offset_or_z_suffixed_value():
    utils.require_offset_datetime("2026-08-27T10:30:00+08:00", "start_time")
    utils.require_offset_datetime("2026-08-27T10:30:00Z", "start_time")


def test_require_offset_datetime_is_permissive_on_unparseable_input():
    """A value that doesn't even parse is a different failure a caller
    will already hit downstream with its own clear error - not this
    function's job to preempt with a possibly-confusing offset-specific
    message."""
    utils.require_offset_datetime("not-a-date", "start_time")


def test_calendar_day_bounds_spans_a_short_day_across_a_dst_spring_forward():
    """2026-03-08 is when America/New_York springs forward (clocks skip
    02:00-03:00), so the calendar day is only 23 hours long. The end
    boundary must be constructed from the next local calendar date so the
    timezone can apply the new UTC offset; adding 24 elapsed hours would
    land at 01:00 on the following day and mis-widen the query window."""
    start, end = utils.calendar_day_bounds("2026-03-08", "America/New_York")
    assert start == "2026-03-08T00:00:00-05:00"
    assert end == "2026-03-09T00:00:00-04:00"


def test_calendar_day_bounds_spans_a_long_day_across_a_dst_fall_back():
    start, end = utils.calendar_day_bounds("2026-11-01", "America/New_York")
    assert start == "2026-11-01T00:00:00-04:00"
    assert end == "2026-11-02T00:00:00-05:00"


@pytest.mark.parametrize("days", [0, -1])
def test_calendar_day_bounds_rejects_non_positive_days(days):
    with pytest.raises(ValueError, match="positive"):
        utils.calendar_day_bounds("2026-08-27", "UTC", days=days)


@pytest.mark.parametrize("days", [0, -1])
def test_naive_day_bounds_rejects_non_positive_days(days):
    with pytest.raises(ValueError, match="positive"):
        utils.naive_day_bounds("2026-08-27", "UTC", days=days)


def test_resolve_zoneinfo_reports_missing_name_as_value_error():
    with pytest.raises(ValueError, match="recognized IANA"):
        utils.resolve_zoneinfo(None)  # type: ignore[arg-type]


def test_offset_datetime_string_attaches_the_zone_offset_to_a_naive_value():
    assert (
        utils.offset_datetime_string("2026-08-27T10:00:00", "Asia/Singapore")
        == "2026-08-27T10:00:00+08:00"
    )


def test_offset_datetime_string_rejects_input_that_already_carries_an_offset():
    """Regression test: no public tool parameter is documented as requiring
    a naive value, so a caller passing one with a trailing 'Z' or an
    explicit offset is a real, reachable mistake - not a theoretical one.
    `.replace(tzinfo=...)` doesn't convert an aware datetime, it just
    relabels the same clock digits under a different zone, silently
    shifting the real instant by however much the two offsets differ
    (e.g. "10:00:00Z" relabeled as Asia/Shanghai reads as 10:00 Shanghai
    time - actually 8 hours earlier). Must fail loudly instead."""
    with pytest.raises(ValueError, match="already carries a UTC offset"):
        utils.offset_datetime_string("2026-08-27T10:00:00Z", "Asia/Shanghai")
    with pytest.raises(ValueError, match="already carries a UTC offset"):
        utils.offset_datetime_string("2026-08-27T10:00:00+00:00", "Asia/Shanghai")


def test_offset_datetime_string_rejects_a_nonexistent_dst_gap_time():
    with pytest.raises(ValueError, match="does not exist.*daylight-saving"):
        utils.offset_datetime_string("2026-03-08T02:30:00", "America/Los_Angeles")


def test_conflict_response_uncapped_when_it_fits(monkeypatch):
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "50000")
    conflicts = [{"calendar": "organizer", "summary": "1:1", "start": "a", "end": "b"}]
    response = json.loads(
        utils.conflict_response(
            conflicts, [], "2026-08-27T10:00:00", "2026-08-27T10:30:00"
        )
    )
    assert response["conflicts"] == conflicts
    assert response["truncated"] is False


def test_conflict_response_caps_an_oversized_conflicts_list(monkeypatch):
    """Regression test: unlike every other response path in this module,
    conflict_response used to return an uncapped payload - a busy shared
    calendar or wide window can turn up far more overlapping events than
    fit the platform's output budget. Only `conflicts` (the field that
    can actually grow large) should be halved to fit; small fields like
    `hint`/`unchecked_attendees` must survive untouched."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "2000")
    conflicts = [
        {
            "calendar": f"person{i}@example.com",
            "summary": "Busy block " + "x" * 50,
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
        for i in range(100)
    ]
    response = json.loads(
        utils.conflict_response(
            conflicts,
            ["[email protected]"],
            "2026-08-27T10:00:00",
            "2026-08-27T10:30:00",
        )
    )

    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert len(response["conflicts"]) < len(conflicts)
    assert response["conflicts"] == conflicts[: len(response["conflicts"])]
    assert response["unchecked_attendees"] == ["[email protected]"]
    assert len(json.dumps(response, ensure_ascii=False)) <= 2000


def test_conflict_response_caps_unchecked_attendees_when_conflicts_alone_is_not_enough(
    monkeypatch,
):
    """Regression test: a single real conflict combined with a huge
    unchecked_attendees list (e.g. every remaining attendee in a large
    invite batch, marked unchecked after a mid-batch scope error) can
    still exceed the output budget even after `conflicts` has been
    shrunk to nothing - unchecked_attendees must also be capped, not
    left untouched forever."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "2000")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "1:1 with Hazel",
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]
    unchecked_attendees = [f"person{i}@example.com" for i in range(200)]

    response = json.loads(
        utils.conflict_response(
            conflicts,
            unchecked_attendees,
            "2026-08-27T10:00:00",
            "2026-08-27T10:30:00",
        )
    )

    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == conflicts
    assert len(response["unchecked_attendees"]) < len(unchecked_attendees)
    assert (
        response["unchecked_attendees"]
        == unchecked_attendees[: len(response["unchecked_attendees"])]
    )
    assert len(json.dumps(response, ensure_ascii=False)) <= 2000


def test_conflict_response_uses_valid_compact_json_below_fixed_envelope(
    monkeypatch,
):
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "300")
    response_text = utils.conflict_response(
        [
            {
                "calendar": "organizer",
                "summary": "Busy",
                "start": "2026-08-27T10:00:00+00:00",
                "end": "2026-08-27T10:30:00+00:00",
            }
        ],
        ["[email protected]"],
        "2026-08-27T10:00:00+00:00",
        "2026-08-27T10:30:00+00:00",
    )

    response = json.loads(response_text)
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert len(response_text) <= 300


# ---------------------------------------------------------------------------
# success_with_capped_dict - dict-collapse sharp edge and last-resort extras
# ---------------------------------------------------------------------------


def test_success_with_capped_dict_degrades_a_single_key_nested_dict_to_a_marker(
    monkeypatch,
):
    """Regression test: phase 1 shrinks a dict-valued field by halving its
    KEY COUNT, mirroring how a list halves its elements. That works for a
    list at any length, but floors to zero for a dict with only one key,
    collapsing the whole field to {} in a single step instead of degrading
    gradually. The field should become a small, non-empty truncation
    marker instead, so a caller can tell something was dropped rather than
    reading {} and being unable to distinguish "truncated" from "always
    empty"."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "200")

    raw = utils.success_with_capped_dict(
        "record", {"id": "rec1", "metrics": {"total": "x" * 5000}}
    )
    result = json.loads(raw)

    assert len(raw) <= 200
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"]["id"] == "rec1"
    assert result["record"]["metrics"] == {"truncated": True}


def test_success_with_capped_dict_degrades_a_two_key_nested_dict_to_a_marker(
    monkeypatch,
):
    """Regression test: a 2-key dict reaches the same floor as the 1-key
    case one step later -- halving its key count first drops to 1 key, and
    a *subsequent* halving of that 1-key remainder is what collapses it to
    {}. The field must still end up as a non-empty marker, not {}, once
    fully exhausted."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "150")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "rec1", "metrics": {"total": "x" * 3000, "avg": "y" * 3000}},
    )
    result = json.loads(raw)

    assert len(raw) <= 150
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"]["id"] == "rec1"
    assert result["record"]["metrics"] == {"truncated": True}


def test_success_with_capped_dict_skips_the_marker_when_it_would_grow_the_field(
    monkeypatch,
):
    """Regression test: phase 1 floors an exhausted dict field to {} first
    (never installing the marker directly), then only upgrades it to the
    {"truncated": true} marker (19 bytes) if the *actual rebuilt response*
    with that marker installed still fits. Here upgrading "tiny" would cost
    17 bytes over its floored {}, and "name"/"note" are still oversized
    enough at that point that there's no surplus to spend -- so the
    upgrade must be skipped, matching the pre-marker (base) result exactly:
    "name" and "note" still get dropped by phase 2 afterward, same as
    always. Checked end-to-end (not just via the size-comparison unit test
    below) so a regression that reintroduced eager marker installation --
    which could still land on the same final shape by chance if a later
    pass coincidentally downgraded it back -- would be caught here too."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "85")

    raw = utils.success_with_capped_dict(
        "record",
        {"tiny": {"a": 1}, "id": "r1", "name": "Bob", "note": "n" * 30},
    )
    result = json.loads(raw)

    assert len(raw) <= 85
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"tiny": {}, "id": "r1"}


def test_success_with_capped_dict_top_level_single_key_survives_phase_two(
    monkeypatch,
):
    """Regression test: phase 2's top-level key-drop halves the key COUNT
    the same way phase 1 does for a nested dict, which floors to zero once
    only one top-level key is left -- the exact gap `mixpanel.py`'s
    `_success_with_capped_list` had to work around locally, since it
    wraps a bare list as `{key: items}` before calling this function.
    Once down to a single top-level key that still doesn't fit on its
    own, phase 2 must stop rather than empty `data` to {} and lose a
    field (here, "id") that the final compact-data fallback could
    otherwise have recovered."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "70")

    # "notes" sorts first (dict insertion order) so phase 2's "keep the
    # first half of keys" step drops "id" before "notes" -- if phase 2 were
    # then allowed to empty the single remaining "notes" key down to {},
    # "id" would never be recovered even though it's small enough to fit.
    raw = utils.success_with_capped_dict("record", {"notes": "x" * 5000, "id": "rec1"})
    result = json.loads(raw)

    assert len(raw) <= 70
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"id": "rec1"}


def test_success_with_capped_dict_last_resort_degrades_extras_before_dropping_them(
    monkeypatch,
):
    """Regression test: once `data` itself is fully truncated, the last
    resort used to drop every `extra_fields` entry outright the moment the
    full-extras candidate didn't fit. A caller-registered extra field
    (e.g. a per-field truncation flag) should keep its key -- even
    degraded to a generic placeholder -- for as long as there's room,
    instead of the whole `extra_fields` dict vanishing in one step. Uses a
    lowercase `id` and a limit distinct from
    test_success_with_capped_dict_last_resort_fallback_keeps_capitalized_id
    in test_deputy_mcp.py, which pins a different contract (capitalized
    `Id` survives) via the same shared helper -- so the two tests don't
    duplicate the same call."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "80")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "REC1", "Notes": "x" * 5000},
        extra_fields={"note": "y" * 60},
    )
    result = json.loads(raw)

    assert len(raw) <= 80
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"id": "REC1"}
    assert "note" in result
    assert result["note"] is True


def test_success_with_capped_dict_last_resort_falls_back_to_dropping_extras(
    monkeypatch,
):
    """When even a fully-degraded extras dict (every value replaced by
    `True`) still doesn't fit, the last resort must still fall back to
    dropping extras entirely rather than getting stuck or erroring -- while
    still preserving the compact `Id` the drop-extras rungs exist to keep
    (asserted explicitly so a regression that lost the id along with the
    extras, e.g. by falling all the way to the id-less rung instead of the
    id-with-no-extras one, would be caught here)."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "80")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 123, "Notes": "x" * 5000},
        extra_fields={"note_one": "y" * 60, "note_two": "z" * 60},
    )
    result = json.loads(raw)

    assert len(raw) <= 80
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"Id": 123}
    assert "note_one" not in result
    assert "note_two" not in result


def test_success_with_capped_dict_last_resort_degrades_the_larger_extra_first(
    monkeypatch,
):
    """Pins the "largest first" claim in the degradation-order docstring
    with two extras of genuinely different sizes (unlike the
    same-size-extras fallback test above, which can't distinguish "largest
    first" from any other tie-break). At a limit that fits the id plus one
    intact extra but not both intact, the larger extra ("big") must be the
    one degraded to `True` while the smaller ("small") stays intact -- a
    regression that degraded by iteration/insertion order instead of size,
    or picked the smallest first, would flip this."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "110")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 123, "Notes": "x" * 5000},
        extra_fields={"big": "b" * 80, "small": "s" * 20},
    )
    result = json.loads(raw)

    assert len(raw) <= 110
    assert result["truncated"] is True
    assert result["record"] == {"Id": 123}
    assert result["big"] is True
    assert result["small"] == "s" * 20


def test_halve_dict_or_mark_halves_while_more_than_one_key_remains():
    """The shared per-step helper both success_with_capped_dict's phase 1
    and shopify.py's local tail loop delegate to: drops the trailing half of
    the keys and reports the field is not yet at its floor."""
    shrunk, floored = utils.halve_dict_or_mark({"a": 1, "b": 2, "c": 3, "d": 4})

    assert shrunk == {"a": 1, "b": 2}
    assert floored is False


def test_halve_dict_or_mark_uses_the_marker_at_the_floor_when_smaller():
    shrunk, floored = utils.halve_dict_or_mark({"total": "x" * 5000})

    assert shrunk == {"truncated": True}
    assert floored is True


def test_halve_dict_or_mark_falls_back_to_empty_when_the_marker_would_grow_it():
    """Regression test for the review finding that motivated gating the
    marker on size at all: a tiny value (here, {"a": 1}, 8 bytes) is
    smaller than the marker itself (19 bytes) -- installing the marker
    would grow the payload instead of shrinking it, so this must fall
    back to {} instead, and still report the floor was reached."""
    shrunk, floored = utils.halve_dict_or_mark({"a": 1})

    assert shrunk == {}
    assert floored is True


def test_halve_dict_or_mark_uses_the_marker_on_an_exact_size_tie():
    """When the marker and the value it would replace serialize to the
    exact same length, the marker must still win: installing it costs
    nothing extra here, so there's no reason to throw away the
    "truncated" signal for a byte-neutral swap. `{"num": 1234567890}` and
    `{"truncated": true}` both serialize to 19 bytes."""
    value = {"num": 1234567890}
    assert len(json.dumps(value, ensure_ascii=False)) == len(
        json.dumps({"truncated": True}, ensure_ascii=False)
    )

    shrunk, floored = utils.halve_dict_or_mark(value)

    assert shrunk == {"truncated": True}
    assert floored is True


_MARKER_OVERHEAD_RECORD = {
    "id": "r1",
    "a": {"k": "x" * 500},
    "b": {"k": "y" * 500},
    "c": {"k": "z" * 500},
    "meta": {"left": "L", "right": "R"},
    "name": "Bob",
}


def test_success_with_capped_dict_floors_exactly_like_base_before_any_marker(
    monkeypatch,
):
    """Regression test: several dict fields hitting the one-key floor in
    the same call each cost a marker's worth of bytes over {}. If markers
    were installed eagerly during phase 1 (before every field's final size
    is known), that overhead could push the response over budget while
    OTHER fields are still being shrunk -- evicting a nested value phase 1
    itself would otherwise have kept intact, exactly unlike the pre-marker
    (base) code. Checked directly against base's own output at this cap:
    three same-size fields (a, b, c) reach the floor, and base still has
    to halve the fourth ("meta") once (to {"left": "L"}) before everything
    fits -- matched here byte-for-byte, since phase 1 floors to {} exactly
    like base until every field's final size is known, before any marker
    is even considered."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "140")

    raw = utils.success_with_capped_dict("record", _MARKER_OVERHEAD_RECORD)
    result = json.loads(raw)

    assert len(raw) <= 140
    assert result["truncated"] is True
    assert set(result["record"]) == {"id", "a", "b", "c", "meta", "name"}
    assert result["record"]["id"] == "r1"
    assert result["record"]["name"] == "Bob"
    # Matches base exactly at this cap: "meta" still needs one halving
    # pass even without any marker in the picture.
    assert result["record"]["meta"] == {"left": "L"}


def test_success_with_capped_dict_upgrades_a_marker_only_from_leftover_budget(
    monkeypatch,
):
    """Regression test: with the same record as the limit=140 case above
    but 20 more bytes of budget, base's own halving of "meta" is no
    longer needed -- it fits fully intact ({"left": "L", "right": "R"})
    once a/b/c are {}. A regression that installs a/b/c's markers
    immediately (spending budget before "meta" is ever considered) would
    force "meta" through phase 1's own halving anyway, permanently losing
    real data that base, and this fixed version, both keep intact --
    markers should only ever be paid for out of budget left over *after*
    matching base, never budget base itself needed. The full key set and
    "id"/"name" are asserted here too (not just the fields the
    marker-upgrade pass touches), so a regression that dropped an
    unrelated top-level key specifically in this branch would also be
    caught."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "160")

    raw = utils.success_with_capped_dict("record", _MARKER_OVERHEAD_RECORD)
    result = json.loads(raw)

    assert len(raw) <= 160
    assert result["truncated"] is True
    assert set(result["record"]) == {"id", "a", "b", "c", "meta", "name"}
    assert result["record"]["id"] == "r1"
    assert result["record"]["name"] == "Bob"
    assert result["record"]["meta"] == {"left": "L", "right": "R"}
    # The 20 extra bytes of budget over the base-equivalent 140-byte state
    # are exactly enough for one marker upgrade (17 bytes) -- spent on "a",
    # the first field floored, rather than wasted or spent unsafely early.
    assert result["record"]["a"] == {"truncated": True}
    assert result["record"]["b"] == {}
    assert result["record"]["c"] == {}


def test_success_with_capped_dict_marks_a_one_key_dict_without_recursing_into_it(
    monkeypatch,
):
    """Phase 1 recurses one level, not further: a one-key dict whose sole
    value is a huge list is replaced by the marker wholesale rather than
    having that inner list halved. Pinned here so the behavior reads as
    deliberate now that the marker exists, not as an oversight."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "150")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "r1", "wrap": {"items": [{"k": "x" * 100} for _ in range(50)]}},
    )
    result = json.loads(raw)

    assert len(raw) <= 150
    assert result["record"]["id"] == "r1"
    assert result["record"]["wrap"] == {"truncated": True}


def test_success_with_capped_dict_last_resort_keeps_extras_that_fit_beside_an_empty_record(
    monkeypatch,
):
    """Regression test: the last-resort ladder went from "id + extras"
    straight to "id, no extras", never trying "empty record + extras". A
    long id that doesn't fit beside the extras therefore cost the extras
    entirely, even when they'd have fit beside {} -- which is how a
    calendar event's Meet link could vanish under truncation although it
    had room. The pre-PR code kept it (its phase 2 collapsed the record to
    {} with extras still attached), so this was a regression."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "66")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "LONGISHIDVALUE1234", "Notes": "x" * 5000},
        extra_fields={"f": True},
    )
    result = json.loads(raw)

    assert len(raw) <= 66
    assert result["truncated"] is True
    assert result["record"] == {}
    assert result["f"] is True


def test_success_with_capped_dict_last_resort_never_degrades_an_extra_that_would_grow(
    monkeypatch,
):
    """Regression test: degrading an already-tiny extra field (here, `1`,
    1 byte) to `True` (4 bytes) would grow the payload, so the ladder must
    skip that step -- and, since the extras fit beside an empty record,
    keep the field with its real value rather than a bloated `true`."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "70")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "rec1", "Notes": "x" * 5000},
        extra_fields={"tiny": 1},
    )
    result = json.loads(raw)

    assert len(raw) <= 70
    assert result["truncated"] is True
    assert result["record"] == {}
    assert result["tiny"] == 1


def test_success_with_capped_dict_last_resort_never_flips_a_boolean_extra(
    monkeypatch,
):
    """Regression test: the extras-degradation loop's size gate only
    excluded an already-`True` value, not a real `False` -- since
    json.dumps(False) (5 bytes) is bigger than json.dumps(True) (4
    bytes), a real `False` extra field passed the "does degrading this
    shrink it" check and got silently flipped to `True`. That's not
    truncation, it's data corruption: a caller reading the response sees
    the wrong value with no signal anything happened. Booleans must never
    be treated as a degrade target at all, regardless of which one they
    currently hold."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "90")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "r1", "Notes": "x" * 5000},
        extra_fields={"is_recurring": False, "n": "N"},
    )
    result = json.loads(raw)

    assert len(raw) <= 90
    assert result["truncated"] is True
    assert result["is_recurring"] is False
    assert result["n"] == "N"


@pytest.mark.parametrize("field_name", ["status", "truncated"])
def test_success_with_capped_dict_rejects_a_field_name_that_shadows_the_envelope(
    field_name,
):
    """Regression test: `reserved_fields` validated that `extra_fields`
    couldn't collide with `field_name`/`status`/`truncated`, but never
    validated that `field_name` itself isn't one of those reserved keys.
    `field_name: payload` and the envelope's own hardcoded key would then
    be the literal same dict entry, and whichever appears later in the
    dict literal wins -- silently discarding the real payload (field_name
    == "status") or the envelope's own success/truncation markers
    (field_name == "truncated"), with no error and no size-capping ever
    attempted (the corrupted response is tiny, so the initial fit check
    trivially passes)."""
    with pytest.raises(ValueError, match="reserved envelope key"):
        utils.success_with_capped_dict(field_name, {"a": 1, "b": 2})


def test_success_with_capped_dict_last_resort_ranks_a_degraded_extra_below_the_id(
    monkeypatch,
):
    """Pins the fifth ladder rung and its position: an empty record beside a
    *degraded* extra ranks below the id alone -- only intact extras are
    worth giving the id up for. Here nothing containing the id fits and the
    extra doesn't fit intact beside {} either, so the degraded-extra rung is
    the first that fits and the id is (correctly) already gone; swapping
    rungs 4 and 5, or dropping rung 5, would change this result."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "75")

    raw = utils.success_with_capped_dict(
        "record",
        {"id": "LONGISHIDVALUE1234", "Notes": "x" * 5000},
        extra_fields={"note": "y" * 60},
    )
    result = json.loads(raw)

    assert len(raw) <= 75
    assert result["truncated"] is True
    assert result["record"] == {}
    assert result["note"] is True


def test_success_with_capped_dict_last_resort_prefers_an_intact_url_over_the_id(
    monkeypatch,
):
    """Regression test for a reviewer-reported case: a calendar-shaped event
    (a 26-character id plus a long description) with a real, still-intact
    Meet link as `extra_fields`. Before the ladder was reordered, `id +
    degraded extras` (the id beside a `True` placeholder for the link) was
    tried -- and fit -- before `{} + intact extras` got a chance, so the
    usable URL was thrown away in favor of an id next to a flag that only
    says "there was a link". The reordered ladder tries the empty record
    with the link still intact before ever degrading that link, so the
    real, followable URL wins over the id."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "109")

    raw = utils.success_with_capped_dict(
        "event",
        {"id": "e" * 26, "description": "d" * 5000},
        extra_fields={"hangout_link": "https://meet.google.com/abc-defg-hij"},
    )
    result = json.loads(raw)

    assert len(raw) <= 109
    assert result["truncated"] is True
    assert result["event"] == {}
    assert result["hangout_link"] == "https://meet.google.com/abc-defg-hij"


# ---------------------------------------------------------------------------
# _halve_largest_list_fields_until_bounded - list-collapse sharp edge
# ---------------------------------------------------------------------------
#
# Halving a list's element count works at any length above one, but floors
# to [] in one step for a single-item list: `conflict_response`'s
# `conflicts`/`unchecked_attendees` and `incomplete_check_response`'s
# `unchecked_attendees` could silently lose a genuine last item, becoming
# indistinguishable from "none found" even though `truncated` is True.


def test_conflict_response_marks_a_last_conflict_truncated_instead_of_emptying(
    monkeypatch,
):
    """Regression test: with a single real conflict too large to fit
    alongside the fixed envelope, halving it (`values[: len(values) // 2]`)
    used to collapse it straight to `[]` in one step -- indistinguishable
    from "no conflicts found" even though `truncated` is True. It should
    become a one-item truncation marker instead, as long as there's budget
    left over once nothing else can be shrunk further (see
    `_halve_largest_list_fields_until_bounded`)."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "700")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "Busy block " + "x" * 400,
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]

    response_text = utils.conflict_response(
        conflicts, [], "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 700
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == [{"truncated": True}]


def test_conflict_response_marks_the_last_unchecked_attendee_truncated_instead_of_emptying(
    monkeypatch,
):
    """Same sharp edge as above, for `unchecked_attendees`. Uses a small,
    realistic `conflicts` list (every real caller only reaches
    `conflict_response` with at least one conflict already confirmed -
    see `calendar.py`/`outlook.py`'s `if conflicts:` guards) that fits
    untouched, isolating the marker behavior to `unchecked_attendees`
    alone. The marker for a `list[str]` field is a sentinel string rather
    than the dict marker used for `conflicts`' event objects, since the
    field must stay a well-formed list of its own element type."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "600")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "1:1 with Hazel",
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]
    unchecked_attendees = ["person" + "y" * 300 + "@example.com"]

    response_text = utils.conflict_response(
        conflicts, unchecked_attendees, "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 600
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == conflicts
    assert response["unchecked_attendees"] == ["<truncated>"]


def test_conflict_response_marks_one_field_while_the_other_keeps_shrinking(
    monkeypatch,
):
    """Regression test: with both `conflicts` and `unchecked_attendees`
    populated, `conflicts` (one oversized event) reaches its one-item
    floor and gets marked well before `unchecked_attendees` (200 small
    entries) is done shrinking - the marker for the first field must not
    stop the second from continuing to shrink toward the budget on later
    loop iterations."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "900")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "Busy block " + "x" * 300,
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]
    unchecked_attendees = [f"person{i}@example.com" for i in range(100)]

    response_text = utils.conflict_response(
        conflicts, unchecked_attendees, "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 900
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == [{"truncated": True}]
    assert 0 < len(response["unchecked_attendees"]) < len(unchecked_attendees)
    assert (
        response["unchecked_attendees"]
        == unchecked_attendees[: len(response["unchecked_attendees"])]
    )


def test_conflict_response_upgrades_only_the_first_floored_field_when_budget_is_tight(
    monkeypatch,
):
    """Regression test: once both `conflicts` and `unchecked_attendees`
    have floored to [], the marker-upgrade pass spends whatever budget is
    left over one field at a time, in the order they floored. `conflicts`
    floors first here (its single event is larger than the single
    unchecked attendee), so its marker is installed; there's no budget
    left for `unchecked_attendees`'s own marker, which must stay []
    rather than push the response over the limit."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "475")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "Busy block " + "x" * 300,
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]
    unchecked_attendees = ["person" + "y" * 250 + "@example.com"]

    response_text = utils.conflict_response(
        conflicts, unchecked_attendees, "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 475
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == [{"truncated": True}]
    assert response["unchecked_attendees"] == []


def test_conflict_response_still_empties_a_last_conflict_when_no_budget_for_the_marker(
    monkeypatch,
):
    """Regression test: the marker upgrade only happens if it actually
    fits (checked against the real rebuilt response, not just estimated) --
    a limit too tight for the marker must still fall back to `[]` rather
    than exceed `max_output_length`. The limit is chosen so the *floored*
    envelope (conflicts=[], original message/hint intact) already fits on
    its own - proving this is the marker-upgrade pass declining to install
    a marker that doesn't fit, not `conflict_response`'s separate, much
    more aggressive compact-JSON fallback for a limit too tight for the
    fixed envelope itself (see
    test_conflict_response_uses_valid_compact_json_below_fixed_envelope)."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "460")
    conflicts = [
        {
            "calendar": "organizer",
            "summary": "Busy block " + "x" * 400,
            "start": "2026-08-27T10:00:00+00:00",
            "end": "2026-08-27T10:30:00+00:00",
        }
    ]

    response_text = utils.conflict_response(
        conflicts, [], "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 460
    assert response["status"] == "conflict"
    assert response["truncated"] is True
    assert response["conflicts"] == []
    assert response["message"] == (
        "1 existing event(s) overlap 2026-08-27T10:00:00 - 2026-08-27T10:30:00"
    )


def test_incomplete_check_response_uncapped_when_it_fits(monkeypatch):
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "50000")
    response = json.loads(
        utils.incomplete_check_response(
            ["[email protected]"],
            "2026-08-27T10:00:00",
            "2026-08-27T10:30:00",
        )
    )
    assert response["status"] == "conflict_check_incomplete"
    assert response["unchecked_attendees"] == ["[email protected]"]
    assert response["truncated"] is False


def test_incomplete_check_response_marks_the_last_unchecked_attendee_truncated_instead_of_emptying(
    monkeypatch,
):
    """Same sharp edge as `conflict_response`'s, for
    `incomplete_check_response`'s own (sole) `unchecked_attendees`
    field -- the last unchecked calendar must not silently vanish to `[]`
    under a tight limit."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "500")
    unchecked_attendees = ["person" + "x" * 300 + "@example.com"]

    response_text = utils.incomplete_check_response(
        unchecked_attendees, "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 500
    assert response["status"] == "conflict_check_incomplete"
    assert response["truncated"] is True
    assert response["unchecked_attendees"] == ["<truncated>"]


def test_incomplete_check_response_still_empties_when_no_budget_for_the_marker(
    monkeypatch,
):
    """Same distinction as `conflict_response`'s: at this limit the
    floored envelope (unchecked_attendees=[], original message intact)
    already fits, so a response reaching that state proves the
    marker-upgrade pass itself declined a marker that didn't fit - not
    the separate, much more aggressive compact-JSON fallback for a limit
    too tight for the fixed envelope itself."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "455")
    unchecked_attendees = ["person" + "x" * 300 + "@example.com"]

    response_text = utils.incomplete_check_response(
        unchecked_attendees, "2026-08-27T10:00:00", "2026-08-27T10:30:00"
    )
    response = json.loads(response_text)

    assert len(response_text) <= 455
    assert response["status"] == "conflict_check_incomplete"
    assert response["truncated"] is True
    assert response["unchecked_attendees"] == []
    assert response["message"] == (
        "Availability could not be checked for 1 calendar(s) for "
        "2026-08-27T10:00:00 - 2026-08-27T10:30:00. No event was written."
    )


def test_success_with_capped_dict_last_resort_fallback_keeps_capitalized_id(
    monkeypatch,
):
    """The severe-truncation last resort used to check only lowercase "id",
    so Deputy's capitalized "Id" (and MYOB's "Uid") was silently dropped
    once a record got truncated all the way down -- exercised directly
    against the shared utility (not through a deputy_* tool) because
    reaching this exact branch also requires extra_fields to push the
    unstripped candidate over the limit, which no deputy_* call site uses."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "100")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 123, "Notes": "x" * 5000},
        extra_fields={"note": "y" * 60},
    )
    result = json.loads(raw)

    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"Id": 123}


def test_success_with_capped_dict_critical_fields_survive_id_only_candidate(
    monkeypatch,
):
    """Unlike extra_fields (previous test), critical_fields must NOT be
    dropped once the ladder is down to its id-only candidate -- this is
    what _verify_record_readable relies on so an unconfirmed-write warning
    is never silently lost to truncation, which would reproduce the exact
    "confident-looking success" failure this mechanism exists to catch.
    (At this budget the id-only candidate already fits, so this doesn't
    reach _fit_critical_fields -- see the dedicated tests for that.)"""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "140")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 123, "Notes": "x" * 5000},
        critical_fields={"warning": "y" * 60},
    )
    result = json.loads(raw)

    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["record"] == {"Id": 123}
    assert result["warning"] == "y" * 60


def test_success_with_capped_dict_critical_fields_survive_tiny_requested_budget(
    monkeypatch,
):
    """Even with an aggressively low requested budget (floored back up to
    _MIN_OUTPUT_LENGTH=64), a critical value short enough to already fit
    within that floor's own fixed envelope overhead must come through
    completely untouched -- this is satisfied by the ladder's own
    bare-status-plus-critical candidate at this size, not by
    _fit_critical_fields itself (see the dedicated tests below for that
    function's own guarantee, including for values too long to fit)."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "10")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 123, "Notes": "x" * 5000},
        critical_fields={"warning": "unconf"},
    )
    result = json.loads(raw)

    assert result["status"] == "success"
    assert result["warning"] == "unconf"


def test_success_with_capped_dict_fits_the_exact_reviewer_reported_budget(
    monkeypatch,
):
    """Verified against rogercloud's own PR #2592 review numbers exactly:
    XAGENT_TOOL_MAX_OUTPUT_LENGTH=64, an Id=1 "returned no record" warning.
    At this budget there isn't even room left for the truncation marker
    once the fixed envelope overhead is accounted for -- the response must
    still fit, even if that means the surviving warning content is just a
    character or two; a stdio MCP child's own budget is mirrored into a
    *separate*, JSON-unaware truncation the parent process applies to this
    exact string, and an oversized response here would be blindly sliced
    mid-structure by that parent-side filter, producing invalid JSON
    instead of a valid-but-abbreviated one."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "64")
    warning = (
        "Deputy reported this Roster create as successful (Id 1), but "
        "reading it back returned no record. Treat this as unconfirmed -- "
        "verify in Deputy directly before relying on it."
    )
    assert len(warning) > 64  # the scenario only arises when it doesn't fit whole

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 1, "Notes": "x" * 5000},
        critical_fields={"warning": warning},
    )

    assert len(raw) <= 64
    result = json.loads(raw)
    assert result["status"] == "success"
    assert result["truncated"] is True


def test_success_with_capped_dict_shortens_an_oversized_critical_field(monkeypatch):
    """With a bit more room than the tightest possible budget, shortening
    must keep a real prefix of the original content plus the truncation
    marker, not just whatever survives is dropped down to nothing."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "100")
    warning = (
        "Deputy reported this Roster create as successful (Id 1), but "
        "reading it back returned no record. Treat this as unconfirmed -- "
        "verify in Deputy directly before relying on it."
    )
    assert len(warning) > 100

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 1, "Notes": "x" * 5000},
        critical_fields={"warning": warning},
    )

    assert len(raw) <= 100
    result = json.loads(raw)
    assert result["status"] == "success"
    assert result["truncated"] is True
    assert result["warning"].endswith("... [truncated]")
    assert warning.startswith(result["warning"].removesuffix("... [truncated]"))


def test_success_with_capped_dict_never_inflates_a_critical_field_below_marker_size(
    monkeypatch,
):
    """A critical field whose value is already SHORTER than the truncation
    marker must be left alone, not replaced by something bigger -- without
    a size gate matching _truncation_marker_or_empty's own ("only install
    the marker if it's no bigger than what it replaces"), a long key name
    paired with a short value could get "shortened" into a larger, still
    oversized response with nothing left to shrink afterward."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "64")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 1, "Notes": "x" * 5000},
        critical_fields={"a_very_long_critical_field_key_name_here": "x"},
    )

    assert len(raw) <= 64
    result = json.loads(raw)
    assert result["status"] == "success"
    assert result["truncated"] is True
    # Even the bare key name alone ("a_very_long_critical_field_key_name_here",
    # 41 chars) plus the envelope skeleton already exceeds this 64-char
    # budget regardless of its value, so this field is always dropped here
    # -- never left alone at "x" -- which is what should be asserted,
    # rather than an OR that would also pass if shrinking somehow mangled
    # the value into something other than "x".
    assert "a_very_long_critical_field_key_name_here" not in result


def test_success_with_capped_dict_drops_a_critical_field_that_cannot_shrink(
    monkeypatch,
):
    """A non-string critical value can't be shortened the way a string
    can -- once every shrinkable string is exhausted and the envelope is
    still oversized, the field must be dropped outright rather than the
    function ever handing back something wider than max_output_length."""
    monkeypatch.setenv("XAGENT_TOOL_MAX_OUTPUT_LENGTH", "64")

    raw = utils.success_with_capped_dict(
        "record",
        {"Id": 1, "Notes": "x" * 5000},
        critical_fields={"stats": {"a": 1, "b": 2, "c": 3, "d": 4, "e": 5, "f": 6}},
    )

    assert len(raw) <= 64
    result = json.loads(raw)
    assert result["status"] == "success"
    assert result["truncated"] is True


def test_success_with_capped_dict_rejects_overlapping_extra_and_critical_fields():
    with pytest.raises(ValueError, match="must not share a key"):
        utils.success_with_capped_dict(
            "record",
            {"Id": 1},
            extra_fields={"note": "a"},
            critical_fields={"note": "b"},
        )


class _GoogleHttpResponse:
    def __init__(self, status):
        self.status = status
        self.reason = "error"


def _google_http_error(status, content: bytes):
    from googleapiclient.errors import HttpError

    return HttpError(
        _GoogleHttpResponse(status),
        content,
        uri="https://www.googleapis.com/drive/v3/files/abc404?alt=json",
    )


def test_google_api_error_status_reads_http_error_status():
    assert utils.google_api_error_status(_google_http_error(404, b"{}")) == 404
    assert utils.google_api_error_status(_google_http_error("403", b"{}")) == 403
    assert utils.google_api_error_status(RuntimeError("404 not found")) is None


def test_google_api_error_reasons_reads_both_google_body_shapes():
    error = _google_http_error(
        403,
        json.dumps(
            {
                "error": {
                    "message": "denied",
                    "errors": [{"reason": "insufficientPermissions"}],
                    "details": [{"reason": "ACCESS_TOKEN_SCOPE_INSUFFICIENT"}],
                }
            }
        ).encode("utf-8"),
    )

    assert utils.google_api_error_reasons(error) == {
        "insufficientPermissions",
        "ACCESS_TOKEN_SCOPE_INSUFFICIENT",
    }
    assert utils.google_api_error_reasons(_google_http_error(500, b"oops")) == set()
    assert utils.google_api_error_reasons(RuntimeError("x")) == set()


def test_google_api_error_summary_leaves_out_the_request_uri():
    error = _google_http_error(
        404, b'{"error": {"message": "File not found: abc404."}}'
    )

    assert "googleapis.com" in str(error)
    assert utils.google_api_error_summary(error) == "HTTP 404 File not found: abc404."
    assert utils.google_api_error_summary(RuntimeError("boom")) == "boom"


_TEST_FILE_KIND = utils.GoogleFileKind(
    product="Google Docs",
    noun="document",
    link_example="https://docs.google.com/document/d/...",
    create_tool="google_docs_create_document",
    office_file="a Word file (.docx)",
    office_reader="read_file",
)
_TEST_DOC_PATTERN = re.compile(r"/document/d/([a-zA-Z0-9_-]+)")


def test_resolve_google_file_id_accepts_ids_and_links():
    assert (
        utils.resolve_google_file_id(
            " abc_-123 ", _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )
        == "abc_-123"
    )
    assert (
        utils.resolve_google_file_id(
            "https://docs.google.com/document/d/abc123/edit",
            _TEST_DOC_PATTERN,
            "document_id",
            _TEST_FILE_KIND,
        )
        == "abc123"
    )


@pytest.mark.parametrize(
    "value",
    [
        "",
        "Quarterly plan",
        "https://drive.google.com/drive/folders/abc123",
        "../x",
    ],
)
def test_resolve_google_file_id_rejects_values_that_cannot_be_ids(value):
    with pytest.raises(ValueError, match="is not a Google Docs link or document id"):
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )


def test_resolve_google_file_id_shortens_a_long_value_in_the_message():
    with pytest.raises(ValueError) as excinfo:
        utils.resolve_google_file_id(
            "word " * 100, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )

    assert "word word" in str(excinfo.value)
    assert "word " * 30 not in str(excinfo.value)
    assert "...' is not a Google Docs link" in str(excinfo.value)


def test_google_file_error_message_only_rewrites_file_access_errors():
    not_found = _google_http_error(404, b'{"error": {"message": "Not found."}}')
    rate_limited = _google_http_error(
        403,
        b'{"error": {"message": "Slow down.", '
        b'"errors": [{"reason": "userRateLimitExceeded"}]}}',
    )

    assert utils.google_file_error_message(not_found, _TEST_FILE_KIND).startswith(
        "Google Docs could not open this document"
    )
    assert utils.google_file_error_message(rate_limited, _TEST_FILE_KIND) == str(
        rate_limited
    )
    assert (
        utils.google_file_error_message(RuntimeError("boom"), _TEST_FILE_KIND) == "boom"
    )


@pytest.mark.parametrize(
    "reason",
    [
        "rateLimitExceeded",
        "userRateLimitExceeded",
        "dailyLimitExceeded",
        "sharingRateLimitExceeded",
        "quotaExceeded",
        "RATE_LIMIT_EXCEEDED",
        "accessNotConfigured",
        "SERVICE_DISABLED",
        "insufficientPermissions",
        "ACCESS_TOKEN_SCOPE_INSUFFICIENT",
    ],
)
@pytest.mark.parametrize("field", ["errors", "details"])
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_keeps_raw_error_for_non_file_access_403(
    reason, field, editing
):
    error = _google_http_error(
        403,
        json.dumps(
            {"error": {"message": "Denied.", field: [{"reason": reason}]}}
        ).encode("utf-8"),
    )

    assert not utils.is_google_file_access_error(error)
    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing
    ) == str(error)


@pytest.mark.parametrize(
    "reason",
    [
        "storageQuotaExceeded",
        "domainPolicy",
        "teamDriveFileLimitExceeded",
        "teamDrivesParentLimit",
        "cannotMoveTrashedItemIntoTeamDrive",
    ],
)
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_keeps_raw_error_for_unlisted_403_reasons(
    reason, editing
):
    error = _google_http_error(
        403,
        json.dumps(
            {"error": {"message": "Denied.", "errors": [{"reason": reason}]}}
        ).encode("utf-8"),
    )

    assert not utils.is_google_file_access_error(error)
    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing
    ) == str(error)


@pytest.mark.parametrize(
    "reason", ["insufficientFilePermissions", "appNotAuthorizedToFile", "forbidden"]
)
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_names_the_file_permission_reason(reason, editing):
    error = _google_http_error(
        403,
        json.dumps(
            {"error": {"message": "Denied.", "errors": [{"reason": reason}]}}
        ).encode("utf-8"),
    )

    message = utils.google_file_error_message(error, _TEST_FILE_KIND, editing=editing)

    assert utils.is_google_file_access_error(error)
    assert message.startswith(
        "Google Docs could not make this change"
        if editing
        else "Google Docs could not open this document"
    )
    assert message.endswith(f"Google API response: HTTP 403 Denied. (reason: {reason})")


@pytest.mark.parametrize(
    ("status", "reason", "unavailable", "access"),
    [
        (404, "notFound", True, True),
        (403, "appNotAuthorizedToFile", True, True),
        (403, "insufficientFilePermissions", False, True),
        (403, None, False, True),
        (403, "storageQuotaExceeded", False, False),
        (500, "backendError", False, False),
        # The unavailable check runs first, so appNotAuthorizedToFile counts
        # even next to a non-file reason; a permission reason does not.
        (403, ("appNotAuthorizedToFile", "rateLimitExceeded"), True, True),
        (403, ("insufficientFilePermissions", "rateLimitExceeded"), False, False),
    ],
)
def test_google_file_error_classifiers_share_one_definition(
    status, reason, unavailable, access
):
    body: dict = {"error": {"message": "Denied."}}
    if reason:
        reasons = (reason,) if isinstance(reason, str) else reason
        body["error"]["errors"] = [{"reason": r} for r in reasons]
    error = _google_http_error(status, json.dumps(body).encode("utf-8"))

    assert utils.is_google_file_unavailable_error(error) is unavailable
    assert utils.is_google_file_access_error(error) is access


def test_google_api_error_summary_appends_reasons_only_when_asked():
    error = _google_http_error(
        403,
        b'{"error": {"message": "Denied.", "errors": [{"reason": "forbidden"}]}}',
    )

    assert utils.google_api_error_summary(error) == "HTTP 403 Denied."
    assert (
        utils.google_api_error_summary(error, with_reasons=True)
        == "HTTP 403 Denied. (reason: forbidden)"
    )
    assert (
        utils.google_api_error_summary(
            _google_http_error(404, b'{"error": {"message": "Gone."}}'),
            with_reasons=True,
        )
        == "HTTP 404 Gone."
    )


def test_google_file_error_message_describes_a_refused_edit():
    denied = _google_http_error(
        403, b'{"error": {"message": "The caller does not have permission"}}'
    )
    not_found = _google_http_error(404, b'{"error": {"message": "Not found."}}')

    read_message = utils.google_file_error_message(denied, _TEST_FILE_KIND)
    edit_message = utils.google_file_error_message(
        denied, _TEST_FILE_KIND, editing=True
    )

    assert read_message.startswith("Google Docs could not open this document")
    assert edit_message.startswith("Google Docs could not make this change")
    assert "only view or comment access" in edit_message
    assert "google_docs_create_document" in edit_message
    assert edit_message.endswith(
        "Google API response: HTTP 403 The caller does not have permission"
    )
    assert utils.google_file_error_message(
        not_found, _TEST_FILE_KIND, editing=True
    ).startswith("Google Docs could not open this document")
    for message in (read_message, edit_message):
        assert "Connecting Google Drive would not change this access." in message


def test_google_file_error_message_says_names_are_not_searched_only_for_404():
    not_found = _google_http_error(404, b'{"error": {"message": "Not found."}}')
    denied = _google_http_error(
        403, b'{"error": {"message": "The caller does not have permission"}}'
    )

    for editing in (False, True):
        message = utils.google_file_error_message(
            not_found, _TEST_FILE_KIND, editing=editing
        )
        assert "cannot search for or list documents by name" in message
        assert "Otherwise, ask the user to check that the link is complete" in message
    for editing in (False, True):
        message = utils.google_file_error_message(
            denied, _TEST_FILE_KIND, editing=editing
        )
        assert "by name" not in message


@pytest.mark.parametrize(
    ("value", "product"),
    [
        ("https://docs.google.com/spreadsheets/d/abc123/edit", "Google Sheets"),
        ("https://docs.google.com/presentation/d/abc123/edit", "Google Slides"),
        ("docs.google.com/spreadsheets/u/0/d/abc123", "Google Sheets"),
    ],
)
def test_resolve_google_file_id_names_a_link_to_another_kind_of_file(value, product):
    with pytest.raises(ValueError) as excinfo:
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )

    message = str(excinfo.value)
    assert f"is a {product} link, not a Google Docs link" in message
    assert f"Open it with the {product} tools if they are available" in message
    assert "by name" not in message


def test_resolve_google_file_id_decodes_a_percent_encoded_link():
    wrapped = (
        "https://www.google.com/url?q=https%3A%2F%2Fdocs.google.com%2F"
        "document%2Fd%2Fabc123%2Fedit&sa=D"
    )

    assert (
        utils.resolve_google_file_id(
            wrapped, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )
        == "abc123"
    )


@pytest.mark.parametrize(
    ("value", "by_name"),
    [
        ("https://drive.google.com/drive/folders/abc123", False),
        ("https://example.com/report", False),
        ("Quarterly plan", True),
    ],
)
def test_resolve_google_file_id_only_mentions_name_search_for_a_non_link(
    value, by_name
):
    with pytest.raises(ValueError) as excinfo:
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )

    message = str(excinfo.value)
    assert "https://docs.google.com/document/d/..." in message
    assert ("cannot search for or list documents by name" in message) is by_name
    assert ("If google_drive_search is available" in message) is by_name
    assert ("Connecting Google Drive is not needed" in message) is by_name


_DRIVE_FILE_LINKS = [
    "https://drive.google.com/file/d/abc123/view?usp=sharing",
    "drive.google.com/file/u/1/d/abc123/view",
    "https://www.google.com/url?q=https%3A%2F%2Fdrive.google.com%2Ffile%2Fd"
    "%2Fabc123%2Fview&sa=D",
    # An older form of the same link.
    "https://docs.google.com/file/d/abc123/edit",
    # Drive's download host for the content of an uploaded file.
    "https://drive.usercontent.google.com/download?id=abc123&export=download",
    "https://drive.usercontent.google.com/download?export=download&id=abc123",
    "https://www.google.com/url?q=https%3A%2F%2Fdrive.usercontent.google.com"
    "%2Fdownload%3Fid%3Dabc123%26export%3Ddownload&sa=D",
]


@pytest.mark.parametrize("value", _DRIVE_FILE_LINKS)
def test_resolve_google_file_id_explains_a_drive_file_link(value):
    with pytest.raises(ValueError) as excinfo:
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )

    message = str(excinfo.value)
    assert "is a Google Drive file link, not a Google Docs link" in message
    assert "such as a Word file (.docx)" in message
    assert "download the file with google_drive_download_file" in message
    assert "read the downloaded copy with read_file" in message
    assert "works only if the Google Drive connection can access the file" in message
    assert "attach the file to their message" in message
    assert "File > Save as Google Docs" in message
    assert "https://docs.google.com/document/d/..." in message
    assert "by name" not in message


@pytest.mark.parametrize("value", _DRIVE_FILE_LINKS)
def test_resolve_google_file_id_explains_a_drive_file_link_to_an_editing_tool(
    value,
):
    with pytest.raises(ValueError) as excinfo:
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND, editing=True
        )

    message = str(excinfo.value)
    assert "is a Google Drive file link, not a Google Docs link" in message
    assert "such as a Word file (.docx)" in message
    # The same next steps as for the Office-file error from the API: a
    # downloaded or attached copy can only be read, not changed, and saving
    # as a Google Doc leaves the Word file as it was.
    assert "To make this change with these tools, ask the user to open it" in message
    assert "File > Save as Google Docs" in message
    assert (
        "Tell the user that this creates a new document: the change will be "
        "made in that copy, and the original file will stay unchanged."
    ) in message
    assert "google_drive_download_file" not in message
    assert "attach the file" not in message
    assert message.endswith(
        "If the file is a Google Docs document, ask the user for the document's "
        "own link (https://docs.google.com/document/d/...)."
    )


# Older share links and download links, such as those of Google Forms file
# uploads, can name a native file too, so their id goes to the API.
@pytest.mark.parametrize(
    ("value", "file_id"),
    [
        ("https://drive.google.com/open?id=1AbC_d-9", "1AbC_d-9"),
        ("https://drive.google.com/open?usp=sharing&id=1AbC_d-9", "1AbC_d-9"),
        ("https://drive.google.com/uc?export=download&id=1AbC_d-9", "1AbC_d-9"),
        ("https://drive.google.com/u/0/uc?id=1AbC_d-9&export=download", "1AbC_d-9"),
        ("Drive.Google.com/Open?id=1AbC_d-9", "1AbC_d-9"),
        (
            "https://www.google.com/url?q=https://drive.google.com/open%3Fid%3D"
            "1AbC_d-9&sa=D",
            "1AbC_d-9",
        ),
        (
            "https://www.google.com/url?q=https%3A%2F%2Fdrive.google.com%2Fuc"
            "%3Fexport%3Ddownload%26id%3D1AbC_d-9&sa=D",
            "1AbC_d-9",
        ),
    ],
)
@pytest.mark.parametrize("editing", [False, True])
def test_resolve_google_file_id_takes_the_id_of_a_drive_open_or_uc_link(
    value, file_id, editing
):
    assert (
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND, editing=editing
        )
        == file_id
    )


@pytest.mark.parametrize(
    "value",
    [
        "https://drive.google.com/open?usp=sharing",
        "https://drive.google.com/uc?id=&export=download",
    ],
)
def test_resolve_google_file_id_rejects_a_drive_open_or_uc_link_without_an_id(
    value,
):
    with pytest.raises(ValueError, match="is not a Google Docs link or document id"):
        utils.resolve_google_file_id(
            value, _TEST_DOC_PATTERN, "document_id", _TEST_FILE_KIND
        )


# The response the Sheets API gives for an Excel file stored in Drive. The
# Docs and Slides tools are checked against the same body.
_OFFICE_FILE_400 = {
    "error": {
        "code": 400,
        "message": (
            "This operation is not supported for this document. The document "
            "must not be an Office file."
        ),
        "status": "FAILED_PRECONDITION",
    }
}


@pytest.mark.parametrize(
    "error_body",
    [
        pytest.param(_OFFICE_FILE_400["error"], id="status-and-message"),
        pytest.param(
            {"message": "This operation is not supported for this document."},
            id="message-only",
        ),
        pytest.param(
            {"message": "This operation is Not Supported for this document."},
            id="message-only-other-case",
        ),
        pytest.param(
            {
                "message": "This operation is not supported for this document",
                "status": "INVALID_ARGUMENT",
            },
            id="message-with-another-status",
        ),
    ],
)
def test_is_google_office_file_error_matches_the_message(error_body):
    error = _google_http_error(400, json.dumps({"error": error_body}).encode("utf-8"))

    assert utils.is_google_office_file_error(error)


@pytest.mark.parametrize(
    ("status", "error_body"),
    [
        (
            400,
            {
                "code": 400,
                "message": "Unable to parse range: Sheet9!A1",
                "status": "INVALID_ARGUMENT",
            },
        ),
        # What the Docs and Slides APIs answer for the id of an Excel file:
        # nothing in it says which file it is.
        (
            400,
            {
                "code": 400,
                "message": "Request contains an invalid argument.",
                "status": "INVALID_ARGUMENT",
            },
        ),
        (400, {"message": "Bad request.", "errors": [{"reason": "badRequest"}]}),
        # FAILED_PRECONDITION alone does not mean an Office file: a batch
        # update, whose requests the caller builds, can fail a precondition
        # for other reasons.
        pytest.param(
            400,
            {"message": "Precondition check failed.", "status": "FAILED_PRECONDITION"},
            id="status-only",
        ),
        pytest.param(
            400,
            {"message": "Bad request.", "errors": [{"reason": "failedPrecondition"}]},
            id="legacy-reason-only",
        ),
        pytest.param(
            400,
            {
                "message": "Precondition check failed.",
                "details": [{"reason": "FAILED_PRECONDITION"}],
            },
            id="details-reason-only",
        ),
        # A body that is not Google-shaped, such as one from a proxy.
        (400, {"message": "Bad request.", "status": ["FAILED_PRECONDITION"]}),
        (404, _OFFICE_FILE_400["error"]),
        (500, {"message": "Internal error.", "status": "FAILED_PRECONDITION"}),
    ],
)
def test_is_google_office_file_error_ignores_other_errors(status, error_body):
    error = _google_http_error(
        status, json.dumps({"error": error_body}).encode("utf-8")
    )

    assert not utils.is_google_office_file_error(error)


@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_keeps_raw_error_for_another_failed_precondition(
    editing,
):
    error = _google_http_error(
        400,
        json.dumps(
            {
                "error": {
                    "code": 400,
                    "message": "Precondition check failed.",
                    "status": "FAILED_PRECONDITION",
                    "errors": [{"reason": "failedPrecondition"}],
                }
            }
        ).encode("utf-8"),
    )

    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing
    ) == str(error)


def test_google_file_error_message_keeps_raw_error_for_a_non_string_status():
    error = _google_http_error(
        400,
        json.dumps(
            {"error": {"message": "Bad request.", "status": ["FAILED_PRECONDITION"]}}
        ).encode("utf-8"),
    )

    assert utils.google_file_error_message(error, _TEST_FILE_KIND) == str(error)


# Every Docs, Sheets and Slides 400 is checked for the Office-file error, so
# a 400 whose body is not Google's JSON error object (such as an HTML error
# page) must keep the raw error rather than make the tool's error handler
# raise.
@pytest.mark.parametrize(
    "content",
    [
        pytest.param(
            b"<html><title>Error 400 (Bad Request)!!1</title></html>", id="html-body"
        ),
        pytest.param(
            json.dumps({"error": {"code": 400, "status": "INVALID_ARGUMENT"}}).encode(
                "utf-8"
            ),
            id="no-message",
        ),
        pytest.param(
            json.dumps({"error": "invalid_request"}).encode("utf-8"),
            id="string-error",
        ),
    ],
)
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_keeps_raw_error_for_a_400_that_is_not_google_shaped(
    content, editing
):
    error = _google_http_error(400, content)

    assert not utils.is_google_office_file_error(error)
    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing
    ) == str(error)


def test_is_google_office_file_error_needs_a_google_http_error():
    assert not utils.is_google_office_file_error(
        RuntimeError("This operation is not supported for this document")
    )


# Each Office-file 400 body, with the Google API response that the message
# ends with. A reason, from errors[] or only from details[], is kept there
# for diagnosis.
_OFFICE_FILE_400_RESPONSES = [
    pytest.param(
        _OFFICE_FILE_400,
        "HTTP 400 This operation is not supported for this document. The "
        "document must not be an Office file.",
        id="status-and-message",
    ),
    pytest.param(
        {
            "error": {
                "code": 400,
                "message": "This operation is not supported for this document",
                "errors": [{"reason": "failedPrecondition"}],
            }
        },
        "HTTP 400 This operation is not supported for this document "
        "(reason: failedPrecondition)",
        id="legacy-reason",
    ),
    pytest.param(
        {
            "error": {
                "code": 400,
                "message": "This operation is not supported for this document",
                "details": [
                    {
                        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                        "reason": "FAILED_PRECONDITION",
                    }
                ],
            }
        },
        "HTTP 400 This operation is not supported for this document "
        "(reason: FAILED_PRECONDITION)",
        id="details-reason",
    ),
]


def _assert_explains_an_office_file(message, google_response):
    # The Google Docs editor does open a Word file (in Office compatibility
    # mode); only the API behind these tools cannot, so the message must not
    # say that Google Docs itself cannot open it.
    assert message.startswith(
        "The Google Docs tools cannot open this file: it is most likely a Word "
        "file (.docx) stored in Google Drive rather than a Google Docs document. "
        "Google Docs can open such a file in Office compatibility mode, but the "
        "API these tools use cannot."
    )
    assert "File > Save as Google Docs" in message
    assert (
        "If google_drive_search or the file's mimeType shows that it is a "
        "Google Sheets or Google Slides file instead, open it with the matching "
        "tools."
    ) in message
    assert message.endswith(f"Google API response: {google_response}")


@pytest.mark.parametrize(("body", "google_response"), _OFFICE_FILE_400_RESPONSES)
def test_google_file_error_message_explains_an_office_file(body, google_response):
    error = _google_http_error(400, json.dumps(body).encode("utf-8"))

    message = utils.google_file_error_message(error, _TEST_FILE_KIND)

    _assert_explains_an_office_file(message, google_response)
    assert "If google_drive_download_file and read_file are available" in message
    assert "works only if the Google Drive connection can access the file" in message
    assert "attach the file to their message" in message


@pytest.mark.parametrize(("body", "google_response"), _OFFICE_FILE_400_RESPONSES)
def test_google_file_error_message_explains_an_office_file_to_an_editing_tool(
    body, google_response
):
    error = _google_http_error(400, json.dumps(body).encode("utf-8"))

    message = utils.google_file_error_message(error, _TEST_FILE_KIND, editing=True)

    _assert_explains_an_office_file(message, google_response)
    assert (
        "To make this change with these tools, ask the user to open it in "
        "Google Docs, choose File > Save as Google Docs, and paste the new "
        "document's link. Tell the user that this creates a new document: the "
        "change will be made in that copy, and the original file will stay "
        "unchanged."
    ) in message
    # A downloaded or attached copy can only be read, not changed.
    assert "google_drive_download_file" not in message
    assert "attach the file" not in message


@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_keeps_raw_error_for_other_400(editing):
    error = _google_http_error(
        400,
        json.dumps(
            {
                "error": {
                    "code": 400,
                    "message": "Unable to parse range: Sheet9!A1",
                    "status": "INVALID_ARGUMENT",
                }
            }
        ).encode("utf-8"),
    )

    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing
    ) == str(error)


# What the Docs and Slides APIs answer for the id of an Excel file: nothing in
# it says which file it is.
_INVALID_ARGUMENT_400 = {
    "error": {
        "code": 400,
        "message": "Request contains an invalid argument.",
        "status": "INVALID_ARGUMENT",
    }
}


# A Drive open?id= or uc?id= link can name a file uploaded to Drive, and its
# id goes to the API, so a 400 that names no cause gets the next steps for
# such a file, after Google's response.
@pytest.mark.parametrize(
    "link",
    [
        "https://drive.google.com/open?id=abc123",
        "https://drive.google.com/uc?export=download&id=abc123",
        "Drive.Google.com/Open?id=abc123",
        "https://www.google.com/url?q=https://drive.google.com/open%3Fid%3Dabc123&sa=D",
    ],
)
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_adds_next_steps_to_a_400_for_a_drive_open_link(
    link, editing
):
    error = _google_http_error(400, json.dumps(_INVALID_ARGUMENT_400).encode("utf-8"))

    message = utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing, file_link_or_id=link
    )

    assert message.startswith(
        "Google Docs rejected this request (Google API response: HTTP 400 "
        "Request contains an invalid argument.). The document id was taken "
        "from a Google Drive link, which can name a file uploaded to Drive, "
        "such as an Office or PDF file, as well as a Google Docs document. The "
        "Google Docs tools cannot open an uploaded file"
    )
    assert "File > Save as Google Docs" in message
    assert ("read the downloaded copy with read_file" in message) is not editing
    assert (
        "this creates a new document: the change will be made in that copy" in message
    ) is editing
    # Such a link does not show which product the file belongs to.
    assert message.endswith(
        "If google_drive_search or the file's mimeType shows that it is a "
        "Google Sheets or Google Slides file instead, open it with the matching "
        "tools. If it is a Google Docs document, the error is about the request "
        "itself."
    )


@pytest.mark.parametrize(
    "error_message",
    [
        "request contains an invalid argument",
        "  Request contains an invalid argument.  ",
    ],
)
def test_google_file_error_message_for_a_drive_open_link_matches_the_message_loosely(
    error_message,
):
    error = _google_http_error(
        400,
        json.dumps(
            {
                "error": {
                    "code": 400,
                    "message": error_message,
                    "status": "INVALID_ARGUMENT",
                }
            }
        ).encode("utf-8"),
    )

    message = utils.google_file_error_message(
        error,
        _TEST_FILE_KIND,
        file_link_or_id="https://drive.google.com/open?id=abc123",
    )

    assert "The document id was taken from a Google Drive link" in message


def test_google_file_error_message_for_a_drive_open_link_keeps_the_reasons():
    error = _google_http_error(
        400,
        json.dumps(
            {
                "error": {
                    **_INVALID_ARGUMENT_400["error"],
                    "errors": [
                        {
                            "message": "Request contains an invalid argument.",
                            "domain": "global",
                            "reason": "badRequest",
                        }
                    ],
                }
            }
        ).encode("utf-8"),
    )

    message = utils.google_file_error_message(
        error,
        _TEST_FILE_KIND,
        file_link_or_id="https://drive.google.com/open?id=abc123",
    )

    assert message.startswith(
        "Google Docs rejected this request (Google API response: HTTP 400 "
        "Request contains an invalid argument. (reason: badRequest)). The "
        "document id was taken from a Google Drive link"
    )


# A 400 whose message names a cause is about the request, even for an id
# taken from a Drive open?id= or uc?id= link, so it keeps the raw error, as
# it does for a bare id.
@pytest.mark.parametrize(
    "link",
    [
        "https://drive.google.com/open?id=abc123",
        "https://drive.google.com/uc?export=download&id=abc123",
    ],
)
@pytest.mark.parametrize(
    "content",
    [
        pytest.param(
            json.dumps(
                {
                    "error": {
                        "code": 400,
                        "message": "Unable to parse range: Q3 Budget!A1:B2",
                        "status": "INVALID_ARGUMENT",
                    }
                }
            ).encode("utf-8"),
            id="range",
        ),
        pytest.param(
            json.dumps(
                {
                    "error": {
                        "code": 400,
                        "message": (
                            "Invalid requests[0].insertText: The insertion index "
                            "must be inside the bounds of an existing paragraph."
                        ),
                        "status": "INVALID_ARGUMENT",
                    }
                }
            ).encode("utf-8"),
            id="request-field",
        ),
        pytest.param(
            json.dumps(
                {
                    "error": {
                        "code": 400,
                        "message": "Precondition check failed.",
                        "status": "FAILED_PRECONDITION",
                        "errors": [{"reason": "failedPrecondition"}],
                    }
                }
            ).encode("utf-8"),
            id="failed-precondition",
        ),
        pytest.param(
            json.dumps({"error": {"code": 400, "status": "INVALID_ARGUMENT"}}).encode(
                "utf-8"
            ),
            id="no-message",
        ),
        pytest.param(
            b"<html><title>Error 400 (Bad Request)!!1</title></html>", id="html-body"
        ),
    ],
)
@pytest.mark.parametrize("editing", [False, True])
def test_google_file_error_message_for_a_drive_open_link_keeps_raw_400_with_a_cause(
    link, content, editing
):
    error = _google_http_error(400, content)

    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, editing=editing, file_link_or_id=link
    ) == str(error)


@pytest.mark.parametrize(
    "file_link_or_id",
    [
        None,
        "abc123",
        "https://docs.google.com/document/d/abc123/edit",
        # Rejected before any API call; never sent here by the tools.
        "https://drive.google.com/file/d/abc123/view",
        "https://drive.google.com/open?usp=sharing",
    ],
)
def test_google_file_error_message_keeps_raw_400_without_a_drive_open_link(
    file_link_or_id,
):
    error = _google_http_error(400, json.dumps(_INVALID_ARGUMENT_400).encode("utf-8"))

    assert utils.google_file_error_message(
        error, _TEST_FILE_KIND, file_link_or_id=file_link_or_id
    ) == str(error)


def test_google_file_error_message_for_a_drive_open_link_keeps_other_mappings():
    link = "https://drive.google.com/open?id=abc123"
    office_file = _google_http_error(400, json.dumps(_OFFICE_FILE_400).encode("utf-8"))
    not_found = _google_http_error(404, b'{"error": {"message": "Not found."}}')
    server_error = _google_http_error(500, b'{"error": {"message": "Backend."}}')
    # Only a 400 gets the next steps, even with the message that names no cause.
    server_error_without_cause = _google_http_error(
        500,
        json.dumps(
            {"error": {"code": 500, "message": "Request contains an invalid argument."}}
        ).encode("utf-8"),
    )

    assert utils.google_file_error_message(
        office_file, _TEST_FILE_KIND, file_link_or_id=link
    ).startswith("The Google Docs tools cannot open this file")
    assert utils.google_file_error_message(
        not_found, _TEST_FILE_KIND, file_link_or_id=link
    ).startswith("Google Docs could not open this document")
    assert utils.google_file_error_message(
        server_error, _TEST_FILE_KIND, file_link_or_id=link
    ) == str(server_error)
    assert utils.google_file_error_message(
        server_error_without_cause, _TEST_FILE_KIND, file_link_or_id=link
    ) == str(server_error_without_cause)