@salesforce/afv-skills 1.20.0 → 1.22.0

package/skills/agentforce-d360-analyze/scripts/tests/test_discover_sessions.py

@@ -0,0 +1,458 @@
+"""Tests for ``discover_sessions`` — DC-only session picker.
+
+Covers:
+- ``parse_time_expr``     pure str → TimeRange (12 supported expressions)
+- ``compose_sql``         pure args → SQL string (conditional JOINs / WHEREs)
+- ``fetch_agent_names``   DC follow-up call (mocks ``post``)
+- ``render_picker``       pure rows → markdown
+- ``main``                argv → exit code (mocks ``resolve_org`` + ``post``)
+"""
+from __future__ import annotations
+
+import unittest
+from datetime import datetime, timedelta, timezone
+from unittest import mock
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import discover_sessions  # type: ignore
+from dc import DCQueryError  # type: ignore
+
+
+# -----------------------------------------------------------------------------
+# parse_time_expr — pure
+# -----------------------------------------------------------------------------
+
+
+class ParseTimeExprTests(unittest.TestCase):
+
+    def test_default_none_returns_last_24_hours(self):
+        tr = discover_sessions.parse_time_expr(None, "UTC")
+        delta = tr.end_utc - tr.start_utc
+        self.assertEqual(delta, timedelta(hours=24))
+        self.assertIn("default", tr.expr)
+
+    def test_last_n_hours(self):
+        tr = discover_sessions.parse_time_expr("last 2 hours", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(hours=2))
+        self.assertEqual(tr.expr, "last 2 hours")
+
+    def test_last_n_minutes(self):
+        tr = discover_sessions.parse_time_expr("last 30 minutes", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(minutes=30))
+
+    def test_last_n_days(self):
+        tr = discover_sessions.parse_time_expr("last 3 days", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(days=3))
+
+    def test_last_n_bare_defaults_to_hours(self):
+        # Spec: "last 10" is ambiguous; the regex treats unit-less as hours.
+        tr = discover_sessions.parse_time_expr("last 10", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(hours=10))
+
+    def test_today_uses_local_tz_calendar_day(self):
+        tr = discover_sessions.parse_time_expr("today", "UTC")
+        # End - start should be exactly 24 hours.
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(days=1))
+
+    def test_yesterday_window_precedes_today(self):
+        today = discover_sessions.parse_time_expr("today", "UTC")
+        yest = discover_sessions.parse_time_expr("yesterday", "UTC")
+        self.assertEqual(yest.end_utc, today.start_utc)
+        self.assertEqual(yest.end_utc - yest.start_utc, timedelta(days=1))
+
+    def test_bare_iso_date(self):
+        tr = discover_sessions.parse_time_expr("2026-04-22", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(days=1))
+        self.assertEqual(tr.start_utc.year, 2026)
+        self.assertEqual(tr.start_utc.month, 4)
+        self.assertEqual(tr.start_utc.day, 22)
+
+    def test_iso_date_range_inclusive(self):
+        # "2026-04-22 to 2026-04-25" → 4 calendar days (22, 23, 24, 25).
+        tr = discover_sessions.parse_time_expr("2026-04-22 to 2026-04-25", "UTC")
+        self.assertEqual(tr.end_utc - tr.start_utc, timedelta(days=4))
+
+    def test_explicit_iso_datetime(self):
+        tr = discover_sessions.parse_time_expr(
+            "2026-04-22T10:00:00Z", "UTC"
+        )
+        self.assertEqual(tr.start_utc.year, 2026)
+        self.assertIn("since", tr.expr)
+
+    def test_unparseable_expression_raises(self):
+        with self.assertRaises(SystemExit) as ctx:
+            discover_sessions.parse_time_expr("nope", "UTC")
+        self.assertIn("cannot parse", str(ctx.exception))
+
+    def test_unknown_tz_raises(self):
+        with self.assertRaises(SystemExit) as ctx:
+            discover_sessions.parse_time_expr("today", "Mars/Olympus")
+        self.assertIn("unknown IANA timezone", str(ctx.exception))
+
+
+# -----------------------------------------------------------------------------
+# compose_sql — pure
+# -----------------------------------------------------------------------------
+
+
+def _basic_tr() -> discover_sessions.TimeRange:
+    return discover_sessions.TimeRange(
+        start_utc=datetime(2026, 4, 22, 0, 0, 0, tzinfo=timezone.utc),
+        end_utc=datetime(2026, 4, 22, 23, 0, 0, tzinfo=timezone.utc),
+        expr="test", tz_name="UTC",
+    )
+
+
+class ComposeSqlTests(unittest.TestCase):
+
+    def test_no_filters_skips_joins_and_uses_no_distinct(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep=None, limit=20,
+        )
+        # Strip SQL comments so the JOIN/DISTINCT mentions in the template
+        # docblock don't fool the naive substring check.
+        executable = "\n".join(
+            line for line in sql.splitlines() if not line.strip().startswith("--")
+        )
+        self.assertNotIn("JOIN ", executable)
+        self.assertNotIn("DISTINCT", executable)
+        self.assertIn("ssot__StartTimestamp__c >= '2026-04-22T00:00:00.000Z'", executable)
+        self.assertIn("ssot__StartTimestamp__c < '2026-04-22T23:00:00.000Z'", executable)
+
+    def test_agent_filter_adds_participant_join(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent="MyAgent", channel=None,
+            outcome=None, grep=None, limit=20,
+        )
+        self.assertIn("ssot__AiAgentSessionParticipant__dlm", sql)
+        self.assertIn("p.ssot__AiAgentApiName__c = 'MyAgent'", sql)
+        self.assertIn("DISTINCT", sql)
+
+    def test_messaging_channel_maps_to_scrt2_string(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel="Messaging",
+            outcome=None, grep=None, limit=20,
+        )
+        self.assertIn("'SCRT2 - EmbeddedMessaging'", sql)
+
+    def test_unknown_channel_passes_through(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel="Custom_Channel",
+            outcome=None, grep=None, limit=20,
+        )
+        self.assertIn("'Custom_Channel'", sql)
+
+    def test_outcome_filter_added(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome="ESCALATED", grep=None, limit=20,
+        )
+        self.assertIn("ssot__AiAgentSessionEndType__c = 'ESCALATED'", sql)
+
+    def test_grep_adds_interaction_message_joins(self):
+        # Default --grep is case-insensitive (§16d) — both sides are
+        # wrapped in LOWER(...). The case-sensitive variant is covered
+        # by test_grep_case_sensitive_opt_in below.
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep="refund", limit=20,
+        )
+        self.assertIn("ssot__AiAgentInteraction__dlm", sql)
+        self.assertIn("ssot__AiAgentInteractionMessage__dlm", sql)
+        self.assertIn("LOWER(m.ssot__ContentText__c) LIKE LOWER('%refund%')", sql)
+        self.assertIn("ESCAPE '!'", sql)
+
+    def test_grep_case_sensitive_opt_in(self):
+        # --grep-case-sensitive bypasses the LOWER() wrap — restores the
+        # exact-match shape for the rare user who wants it.
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep="Refund", grep_case_sensitive=True, limit=20,
+        )
+        self.assertIn("m.ssot__ContentText__c LIKE '%Refund%'", sql)
+        self.assertNotIn("LOWER(", sql)
+        self.assertIn("ESCAPE '!'", sql)
+
+    def test_grep_escapes_like_wildcards(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep="100%_off", limit=20,
+        )
+        # Both `%` and `_` get the `!` escape prefix
+        self.assertIn("100!%!_off", sql)
+
+    def test_grep_escapes_single_quotes(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep="O'Brien", limit=20,
+        )
+        # Single quote doubled per SQL escaping rule
+        self.assertIn("O''Brien", sql)
+
+    def test_limit_substituted(self):
+        sql = discover_sessions.compose_sql(
+            tr=_basic_tr(), agent=None, channel=None,
+            outcome=None, grep=None, limit=42,
+        )
+        self.assertIn("42", sql)
+
+
+# -----------------------------------------------------------------------------
+# fetch_agent_names — mocks dc.post
+# -----------------------------------------------------------------------------
+
+
+class FetchAgentNamesTests(unittest.TestCase):
+
+    def test_empty_session_ids_returns_empty_dict_no_post(self):
+        with mock.patch.object(discover_sessions, "post") as p:
+            out = discover_sessions.fetch_agent_names(
+                [], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {})
+        p.assert_not_called()
+
+    def test_returns_dict_keyed_by_session_id(self):
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.return_value = [
+                {
+                    "ssot__AiAgentSessionId__c": "sid1",
+                    "ssot__AiAgentApiName__c": "AgentA",
+                },
+                {
+                    "ssot__AiAgentSessionId__c": "sid2",
+                    "ssot__AiAgentApiName__c": "AgentB",
+                },
+            ]
+            out = discover_sessions.fetch_agent_names(
+                ["sid1", "sid2"], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {"sid1": "AgentA", "sid2": "AgentB"})
+
+    def test_skips_rows_with_empty_agent_name(self):
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.return_value = [
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": ""},
+                {"ssot__AiAgentSessionId__c": "sid2", "ssot__AiAgentApiName__c": "AgentB"},
+            ]
+            out = discover_sessions.fetch_agent_names(
+                ["sid1", "sid2"], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {"sid2": "AgentB"})
+
+    def test_dcqueryerror_returns_empty_dict_non_fatal(self):
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.side_effect = DCQueryError("boom")
+            out = discover_sessions.fetch_agent_names(
+                ["sid1"], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {})
+
+    def test_uses_user_row_name_when_agent_row_is_not_set(self):
+        # MyAgent-shape session: AGENT row carries 'NOT_SET',
+        # USER row carries the real api_name. Old code filtered to
+        # role=AGENT and would return 'NOT_SET' (or nothing). New code
+        # is role-agnostic and recovers the api_name from the USER row.
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.return_value = [
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": "NOT_SET"},
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": "MyAgent"},
+            ]
+            out = discover_sessions.fetch_agent_names(
+                ["sid1"], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {"sid1": "MyAgent"})
+
+    def test_drops_session_when_every_row_is_not_set(self):
+        # No usable api_name anywhere — picker should show '—' for the
+        # session, which is more honest than displaying the literal
+        # 'NOT_SET' string. Implementation contract: missing key in dict.
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.return_value = [
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": "NOT_SET"},
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": ""},
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": None},
+            ]
+            out = discover_sessions.fetch_agent_names(
+                ["sid1"], instance_url="https://x", token="t",
+            )
+        self.assertNotIn("sid1", out)
+        self.assertEqual(out, {})
+
+    def test_picks_lexicographic_first_on_handoff_session(self):
+        # Multi-agent handoff: two distinct AGENT api_names appear on
+        # different rows for the same session. Dominant-agent rule
+        # (sorted(...)[0]) matches the policy used by fetch_dc — every
+        # writer agrees on the session's namesake.
+        with mock.patch.object(discover_sessions, "post") as p:
+            p.return_value = [
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": "ZAgent"},
+                {"ssot__AiAgentSessionId__c": "sid1", "ssot__AiAgentApiName__c": "AAgent"},
+            ]
+            out = discover_sessions.fetch_agent_names(
+                ["sid1"], instance_url="https://x", token="t",
+            )
+        self.assertEqual(out, {"sid1": "AAgent"})
+
+    def test_sql_does_not_filter_by_role(self):
+        # Lock the no-role-filter contract — if a future "tighten this
+        # back up" refactor re-adds the AGENT filter, MyAgent
+        # sessions silently regress to '—' or 'NOT_SET' in the picker.
+        captured = {}
+
+        def fake_post(sql, *_a, **_k):
+            captured["sql"] = sql
+            return []
+
+        with mock.patch.object(discover_sessions, "post", side_effect=fake_post):
+            discover_sessions.fetch_agent_names(
+                ["sid1"], instance_url="https://x", token="t",
+            )
+        self.assertNotIn("AiAgentSessionParticipantRole", captured["sql"])
+        self.assertNotIn("'AGENT'", captured["sql"])
+
+
+# -----------------------------------------------------------------------------
+# render_picker — pure
+# -----------------------------------------------------------------------------
+
+
+def _picker_filters(**overrides) -> dict:
+    base = {"agent": None, "channel": None, "outcome": None, "grep": None}
+    base.update(overrides)
+    return base
+
+
+class RenderPickerTests(unittest.TestCase):
+
+    def test_zero_rows_emits_widen_hint_with_composed_sql(self):
+        out = discover_sessions.render_picker(
+            rows=[], agent_by_sid={}, org="my-org",
+            tr=_basic_tr(), filters=_picker_filters(),
+            composed_sql="SELECT 1",
+        )
+        self.assertIn("No sessions matched", out)
+        self.assertIn("```sql\nSELECT 1\n```", out)
+        self.assertIn("Try widening", out)
+
+    def test_renders_markdown_table_with_one_row(self):
+        rows = [{
+            "ssot__Id__c": "019dface-0000-7000-8000-000000000001",
+            "ssot__StartTimestamp__c": "2026-04-22T10:00:00Z",
+            "ssot__EndTimestamp__c": "2026-04-22T10:01:30Z",
+            "ssot__AiAgentChannelType__c": "SCRT2 - EmbeddedMessaging",
+            "ssot__AiAgentSessionEndType__c": "USER_ENDED",
+        }]
+        out = discover_sessions.render_picker(
+            rows=rows, agent_by_sid={"019dface-0000-7000-8000-000000000001": "AgentA"},
+            org="my-org", tr=_basic_tr(),
+            filters=_picker_filters(), composed_sql="",
+        )
+        self.assertIn("Found **1** session", out)
+        self.assertIn("`019dface-0000-7000-8000-000000000001`", out)
+        self.assertIn("AgentA", out)
+        # Reverse-aliased channel
+        self.assertIn("Messaging", out)
+        # Duration formatter
+        self.assertIn("1m 30s", out)
+        self.assertIn("USER_ENDED", out)
+
+    def test_handles_session_without_known_agent_with_dash(self):
+        rows = [{
+            "ssot__Id__c": "sid1",
+            "ssot__StartTimestamp__c": "2026-04-22T10:00:00Z",
+            "ssot__EndTimestamp__c": "2026-04-22T10:00:30Z",
+            "ssot__AiAgentChannelType__c": "Builder",
+            "ssot__AiAgentSessionEndType__c": None,
+        }]
+        out = discover_sessions.render_picker(
+            rows=rows, agent_by_sid={}, org="my-org",
+            tr=_basic_tr(), filters=_picker_filters(), composed_sql="",
+        )
+        self.assertIn("| — |", out)  # agent + outcome both render as "—"
+        self.assertIn("30s", out)
+
+    def test_filter_bits_appear_in_header(self):
+        rows = [{
+            "ssot__Id__c": "sid1",
+            "ssot__StartTimestamp__c": "2026-04-22T10:00:00Z",
+            "ssot__EndTimestamp__c": "2026-04-22T10:00:30Z",
+            "ssot__AiAgentChannelType__c": "Builder",
+            "ssot__AiAgentSessionEndType__c": "ESCALATED",
+        }]
+        out = discover_sessions.render_picker(
+            rows=rows, agent_by_sid={}, org="my-org", tr=_basic_tr(),
+            filters=_picker_filters(agent="MyAgent", outcome="ESCALATED"),
+            composed_sql="",
+        )
+        self.assertIn("agent=MyAgent", out)
+        self.assertIn("outcome=ESCALATED", out)
+
+
+# -----------------------------------------------------------------------------
+# main — argv-driven exit codes
+# -----------------------------------------------------------------------------
+
+
+class MainTests(unittest.TestCase):
+
+    def _argv(self, *extra: str) -> list[str]:
+        # `--org` is required; everything else has a default or is optional.
+        return ["discover_sessions.py", "--org", "my-org", *extra]
+
+    def test_main_exit_zero_when_rows_returned(self):
+        with mock.patch.object(discover_sessions.sys, "argv", self._argv()):
+            with mock.patch.object(
+                discover_sessions, "resolve_org",
+                return_value=("https://example.salesforce.com", "TOKEN"),
+            ):
+                with mock.patch.object(
+                    discover_sessions, "post",
+                    return_value=[{
+                        "ssot__Id__c": "sid1",
+                        "ssot__StartTimestamp__c": "2026-04-22T00:00:00Z",
+                        "ssot__EndTimestamp__c": "2026-04-22T00:01:00Z",
+                        "ssot__AiAgentChannelType__c": "Builder",
+                        "ssot__AiAgentSessionEndType__c": "USER_ENDED",
+                    }],
+                ):
+                    rc = discover_sessions.main()
+        self.assertEqual(rc, 0)
+
+    def test_main_exit_two_when_zero_rows(self):
+        with mock.patch.object(discover_sessions.sys, "argv", self._argv()):
+            with mock.patch.object(
+                discover_sessions, "resolve_org",
+                return_value=("https://x", "T"),
+            ):
+                with mock.patch.object(discover_sessions, "post", return_value=[]):
+                    rc = discover_sessions.main()
+        self.assertEqual(rc, 2)
+
+    def test_main_exit_one_when_dc_query_fails(self):
+        with mock.patch.object(discover_sessions.sys, "argv", self._argv()):
+            with mock.patch.object(
+                discover_sessions, "resolve_org",
+                return_value=("https://x", "T"),
+            ):
+                with mock.patch.object(
+                    discover_sessions, "post",
+                    side_effect=DCQueryError("HTTP 500"),
+                ):
+                    rc = discover_sessions.main()
+        self.assertEqual(rc, 1)
+
+    def test_main_rejects_zero_or_negative_limit(self):
+        with mock.patch.object(
+            discover_sessions.sys, "argv",
+            self._argv("--limit", "0"),
+        ):
+            with self.assertRaises(SystemExit) as ctx:
+                discover_sessions.main()
+        self.assertIn("--limit must be >= 1", str(ctx.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/agentforce-d360-analyze/scripts/tests/test_discover_sessions_grep_ci.py

@@ -0,0 +1,193 @@
+"""Regression guard for §16d — case-insensitive ``--grep`` default.
+
+§16d flipped the default behaviour of ``--grep`` from case-sensitive
+exact match to case-insensitive (``LOWER(...) LIKE LOWER(...)``).
+Operators almost always type the quoted phrase in whatever case they
+remember, not the case the agent rendered it in — the old default
+silently dropped legitimate matches.
+
+The compose_sql shape is already pinned in
+``test_discover_sessions.py`` (LOWER wrap on default, bypass on opt-in,
+escape semantics). What this file pins down is the
+**argparse → filters dict → picker header** pipeline — the integration
+seams where a refactor could:
+
+  - flip the argparse default back to ``True`` (forgot ``default=False``)
+  - drop the ``grep_case_sensitive`` key from the filters dict (header
+    no longer warns the operator that the picker is in opt-in mode)
+  - surface ``grep_case_sensitive`` even when ``--grep`` isn't set
+    (false signal in the header for unrelated runs)
+"""
+from __future__ import annotations
+
+import argparse
+import unittest
+from unittest import mock
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import discover_sessions  # type: ignore
+
+
+class GrepCaseSensitiveArgparseDefaultTests(unittest.TestCase):
+    """The argparse flag must default to ``False`` so case-insensitive
+    is the path of least resistance."""
+
+    def _build_parser(self) -> argparse.ArgumentParser:
+        # Re-export the parser the same way main() does — we don't have
+        # a parser factory, so spy on the module-level ``argparse`` to
+        # capture the parser before main() invokes parse_args().
+        captured: dict[str, argparse.ArgumentParser] = {}
+        real_parse_args = argparse.ArgumentParser.parse_args
+
+        def capture(self, *a, **kw):  # type: ignore[no-redef]
+            captured["parser"] = self
+            # Stop main() before it calls anything network-y.
+            raise SystemExit(0)
+
+        with mock.patch.object(argparse.ArgumentParser, "parse_args", capture):
+            with mock.patch.object(
+                discover_sessions.sys, "argv",
+                ["discover_sessions.py", "--org", "x"],
+            ):
+                with self.assertRaises(SystemExit):
+                    discover_sessions.main()
+        # Restore (the patch.object exit already did this, but be explicit
+        # in case something held onto the bound method.)
+        argparse.ArgumentParser.parse_args = real_parse_args
+        return captured["parser"]
+
+    def test_grep_case_sensitive_default_is_false(self):
+        # parse_args without --grep-case-sensitive must return False.
+        parser = self._build_parser()
+        ns = parser.parse_args(["--org", "x"])
+        self.assertFalse(ns.grep_case_sensitive,
+                         "default flipped — case-insensitive was the §16d "
+                         "decision; flipping default=False back to True "
+                         "regresses to the pre-§16d behaviour")
+
+    def test_grep_case_sensitive_opt_in_via_flag(self):
+        # Pass the flag explicitly — must be True.
+        parser = self._build_parser()
+        ns = parser.parse_args(["--org", "x", "--grep-case-sensitive"])
+        self.assertTrue(ns.grep_case_sensitive)
+
+
+class FiltersDictSurfacesCaseSensitiveTests(unittest.TestCase):
+    """The filters dict feeds render_picker's header. Without a marker,
+    the operator can't tell whether their grep is in case-insensitive
+    (default) or case-sensitive (opt-in) mode — a silent footgun when
+    a query returns zero rows in opt-in mode by accident."""
+
+    def _run_main_and_capture_filters(self, *extra_argv: str) -> dict:
+        # Stub resolve_org + post so main() doesn't talk to DC, then
+        # intercept render_picker to capture the filters dict main()
+        # constructed.
+        captured: dict[str, dict] = {}
+
+        def fake_render(*, filters, **_kw):
+            captured["filters"] = filters
+            return "ok"
+
+        argv = ["discover_sessions.py", "--org", "x", *extra_argv]
+        with mock.patch.object(discover_sessions.sys, "argv", argv), \
+             mock.patch.object(
+                 discover_sessions, "resolve_org",
+                 return_value=("https://x", "T"),
+             ), \
+             mock.patch.object(
+                 discover_sessions, "post",
+                 return_value=[{
+                     "ssot__Id__c": "sid1",
+                     "ssot__StartTimestamp__c": "2026-04-22T00:00:00Z",
+                     "ssot__EndTimestamp__c": "2026-04-22T00:01:00Z",
+                     "ssot__AiAgentChannelType__c": "Builder",
+                     "ssot__AiAgentSessionEndType__c": "USER_ENDED",
+                 }],
+             ), \
+             mock.patch.object(
+                 discover_sessions, "render_picker",
+                 side_effect=fake_render,
+             ):
+            discover_sessions.main()
+        return captured["filters"]
+
+    def test_filters_omit_case_sensitive_when_grep_unset(self):
+        # No --grep at all: surfacing case-sensitive=yes in the header
+        # would be a meaningless artifact (there's no grep to be
+        # case-sensitive about). Contract: the value is None so
+        # render_picker's `if v:` filter drops the bit.
+        filters = self._run_main_and_capture_filters()
+        self.assertIsNone(filters["grep_case_sensitive"])
+
+    def test_filters_omit_case_sensitive_when_grep_set_but_default(self):
+        # --grep set, --grep-case-sensitive NOT set: default mode is
+        # case-insensitive. Don't surface the marker — the absence is
+        # the default and surfacing "yes/no" on every grep would just
+        # add noise to the picker header.
+        filters = self._run_main_and_capture_filters("--grep", "refund")
+        self.assertEqual(filters["grep"], "refund")
+        self.assertIsNone(filters["grep_case_sensitive"])
+
+    def test_filters_surface_case_sensitive_only_when_both_set(self):
+        # The interesting case: operator opted in. The header MUST tell
+        # them, otherwise a zero-row return looks identical to a
+        # case-insensitive zero-row return.
+        filters = self._run_main_and_capture_filters(
+            "--grep", "Refund", "--grep-case-sensitive",
+        )
+        self.assertEqual(filters["grep"], "Refund")
+        self.assertEqual(filters["grep_case_sensitive"], "yes")
+
+
+class RenderPickerHeaderShowsCaseSensitiveTests(unittest.TestCase):
+    """End-to-end: when filters dict surfaces ``grep_case_sensitive``,
+    render_picker must include it in the header."""
+
+    def _row(self) -> dict:
+        return {
+            "ssot__Id__c": "sid1",
+            "ssot__StartTimestamp__c": "2026-04-22T10:00:00Z",
+            "ssot__EndTimestamp__c": "2026-04-22T10:00:30Z",
+            "ssot__AiAgentChannelType__c": "Builder",
+            "ssot__AiAgentSessionEndType__c": "USER_ENDED",
+        }
+
+    def _tr(self) -> "discover_sessions.TimeRange":
+        from datetime import datetime, timezone
+        return discover_sessions.TimeRange(
+            start_utc=datetime(2026, 4, 22, 0, 0, 0, tzinfo=timezone.utc),
+            end_utc=datetime(2026, 4, 22, 23, 0, 0, tzinfo=timezone.utc),
+            expr="test", tz_name="UTC",
+        )
+
+    def test_header_includes_case_sensitive_bit_when_set(self):
+        out = discover_sessions.render_picker(
+            rows=[self._row()], agent_by_sid={}, org="my-org",
+            tr=self._tr(),
+            filters={
+                "agent": None, "channel": None, "outcome": None,
+                "grep": "Refund", "grep_case_sensitive": "yes",
+            },
+            composed_sql="",
+        )
+        self.assertIn("grep=Refund", out)
+        self.assertIn("grep_case_sensitive=yes", out)
+
+    def test_header_omits_case_sensitive_bit_in_default_mode(self):
+        # Default-mode grep (no opt-in): the bit must NOT appear.
+        out = discover_sessions.render_picker(
+            rows=[self._row()], agent_by_sid={}, org="my-org",
+            tr=self._tr(),
+            filters={
+                "agent": None, "channel": None, "outcome": None,
+                "grep": "refund", "grep_case_sensitive": None,
+            },
+            composed_sql="",
+        )
+        self.assertIn("grep=refund", out)
+        self.assertNotIn("grep_case_sensitive", out)
+
+
+if __name__ == "__main__":
+    unittest.main()