@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/investigating-agentforce-d360/scripts/discover_sessions.py

@@ -1,556 +0,0 @@
-"""Session discovery for investigating-agentforce-d360 — Data Cloud only.
-
-Lets the user find candidate sessions when they don't have a session id.
-Output is a numbered picker table to stdout; the skill agent asks the user
-to pick one, then falls through to the existing fetch_dc.py pipeline with
-the chosen UUID. Writes no artifacts.
-
-DC-only by design (no OTel path).
-
-## CLI
-
-    python3 scripts/discover_sessions.py --org <alias> [options]
-
-Options (all optional except --org):
-  --since <expr>    "last 2 hours" | "last 10" | "today" | "yesterday"
-                    | "YYYY-MM-DD" | "YYYY-MM-DD to YYYY-MM-DD"
-                    | explicit UTC/TZ datetime (RFC 3339). Default: last 24 hours.
-  --agent <name>    Agent API name (e.g. MyAgent). Adds participant JOIN.
-  --channel <type>  Builder | Messaging | Voice. "Messaging" maps to
-                    "SCRT2 - EmbeddedMessaging" in SQL.
-  --outcome <type>  USER_ENDED | ESCALATED | TRANSFERRED | TIMEOUT | NOT_SET
-  --grep <pattern>  Substring in conversation text (user input + agent output).
-                    Adds interaction + message JOINs. Case-insensitive by
-                    default (LOWER on both sides); pass --grep-case-sensitive
-                    for exact match. `%` and `_` are escaped so they match
-                    the literal char.
-  --grep-case-sensitive
-                    Opt-in: make --grep case-sensitive (rare; default is
-                    case-insensitive because users almost always type the
-                    quote in whatever case they remember it).
-  --tz <IANA>       Override auto-detected local tz (e.g. America/Los_Angeles).
-                    Only affects calendar-day resolution (today/yesterday/
-                    bare-date/date-range); `last N` windows are anchored to
-                    UTC regardless. The chosen tz is echoed in zero-row
-                    output so the user can sanity-check boundaries.
-  --limit <N>       Max sessions. Default 20.
-
-Exit codes:
-  0 — ≥1 session found
-  2 — zero sessions (picker prints composed SQL so user can widen)
-  other — DC query or arg-parse error
-"""
-from __future__ import annotations
-
-import argparse
-import html
-import os
-import re
-import sys
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from typing import Optional
-from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-from dc import DCQueryError, load_sql, post, resolve_org
-from _shared.sql import _escape_sql_literal
-
-
-# ---- channel alias ---------------------------------------------------------
-
-# Source-skill convention: users type "Messaging" but DC stores the full
-# SCRT2 string. Other channels pass through as-is (Builder, Voice).
-_CHANNEL_ALIAS = {
-    "Messaging": "SCRT2 - EmbeddedMessaging",
-}
-
-
-# ---- escaping --------------------------------------------------------------
-#
-# `_escape_sql_literal` is imported from `_shared.sql` (single source of
-# truth per its module docstring). Do NOT re-declare locally — divergence
-# would break the documented contract that every DC-SQL caller shares one
-# escape strategy.
-
-_LIKE_ESCAPE = "!"  # ASCII, doesn't collide with SQL syntax, no quoting ambiguity
-
-def _escape_like_pattern(s: str) -> str:
-    """Escape SQL LIKE wildcards (`%`, `_`) and the escape char itself
-    (`!`) so `--grep "100%_off"` matches the literal text, not "100
-    anything-underscore-off". Quote-doubling still happens on top of this
-    via _escape_sql_literal. Used with the `ESCAPE '!'` clause in the
-    composed SQL.
-
-    Backslash was avoided because `ESCAPE '\\'` in source reduces to a
-    bare backslash on the wire, which some SQL parsers read as an
-    unterminated string literal (\\' → escaped quote).
-    """
-    return (
-        s.replace(_LIKE_ESCAPE, _LIKE_ESCAPE * 2)
-        .replace("%", f"{_LIKE_ESCAPE}%")
-        .replace("_", f"{_LIKE_ESCAPE}_")
-    )
-
-
-# ---- time parsing ----------------------------------------------------------
-
-@dataclass(frozen=True)
-class TimeRange:
-    """Half-open UTC range [start, end). `expr` is the original user input
-    so the picker header can echo back what was searched."""
-    start_utc: datetime
-    end_utc: datetime
-    expr: str
-    tz_name: str  # IANA or "UTC"
-
-    def iso(self, dt: datetime) -> str:
-        return dt.strftime("%Y-%m-%dT%H:%M:%S.000Z")
-
-
-def _autodetect_tz() -> str:
-    """IANA tz from /etc/localtime symlink (macOS / most Linux). Falls
-    back to the TZ env var, then UTC."""
-    link = Path("/etc/localtime")
-    try:
-        if link.is_symlink():
-            target = os.readlink(link)
-            # Typically .../zoneinfo/America/Los_Angeles
-            if "zoneinfo/" in target:
-                return target.split("zoneinfo/", 1)[1]
-    except OSError:
-        pass
-    return os.environ.get("TZ") or "UTC"
-
-
-_RX_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")  # @rule-suppress starter-sec-002 — re.compile, not eval/exec
-_RX_DATE_RANGE = re.compile(r"^(\d{4}-\d{2}-\d{2})\s+to\s+(\d{4}-\d{2}-\d{2})$")  # @rule-suppress starter-sec-002 — re.compile, not eval/exec
-_RX_LAST_N = re.compile(  # @rule-suppress starter-sec-002 — re.compile, not eval/exec
-    r"^last\s+(\d+)(?:\s+(hour|hours|day|days|minute|minutes))?$",
-    re.IGNORECASE,
-)
-
-
-def parse_time_expr(expr: Optional[str], tz_name: str) -> TimeRange:
-    """Parse one of the supported time expressions into a UTC half-open
-    range. Default (None) is "last 24 hours" so every query has a sane
-    time predicate — DC scans over the whole DMO without one are slow."""
-    tz_name = tz_name or _autodetect_tz()
-    try:
-        local_tz = ZoneInfo(tz_name)
-    except ZoneInfoNotFoundError:
-        raise SystemExit(f"discover_sessions: unknown IANA timezone {tz_name!r}")
-
-    now_utc = datetime.now(timezone.utc)
-
-    if expr is None:
-        return TimeRange(
-            start_utc=now_utc - timedelta(hours=24),
-            end_utc=now_utc,
-            expr="last 24 hours (default)",
-            tz_name=tz_name,
-        )
-
-    s = expr.strip()
-    sl = s.lower()
-
-    # "last N" / "last N hours" / "last N days" / "last N minutes"
-    m = _RX_LAST_N.match(sl)
-    if m:
-        n = int(m.group(1))
-        unit = (m.group(2) or "hours").lower()
-        if unit in ("hour", "hours"):
-            delta = timedelta(hours=n)
-        elif unit in ("day", "days"):
-            delta = timedelta(days=n)
-        elif unit in ("minute", "minutes"):
-            delta = timedelta(minutes=n)
-        else:
-            raise SystemExit(f"discover_sessions: unsupported time unit {unit!r}")
-        return TimeRange(
-            start_utc=now_utc - delta,
-            end_utc=now_utc,
-            expr=s,
-            tz_name=tz_name,
-        )
-
-    # "today" / "yesterday" — calendar day in local tz
-    if sl in ("today", "yesterday"):
-        local_now = datetime.now(local_tz)
-        offset_days = 0 if sl == "today" else 1
-        start_local = local_now.replace(hour=0, minute=0, second=0, microsecond=0) - timedelta(days=offset_days)
-        end_local = start_local + timedelta(days=1)
-        return TimeRange(
-            start_utc=start_local.astimezone(timezone.utc),
-            end_utc=end_local.astimezone(timezone.utc),
-            expr=s,
-            tz_name=tz_name,
-        )
-
-    # "YYYY-MM-DD to YYYY-MM-DD" — inclusive range in local tz
-    m = _RX_DATE_RANGE.match(s)
-    if m:
-        start_d, end_d = m.group(1), m.group(2)
-        start_local = datetime.strptime(start_d, "%Y-%m-%d").replace(tzinfo=local_tz)
-        end_local = datetime.strptime(end_d, "%Y-%m-%d").replace(tzinfo=local_tz) + timedelta(days=1)
-        return TimeRange(
-            start_utc=start_local.astimezone(timezone.utc),
-            end_utc=end_local.astimezone(timezone.utc),
-            expr=s,
-            tz_name=tz_name,
-        )
-
-    # Bare "YYYY-MM-DD"
-    if _RX_DATE.match(s):
-        start_local = datetime.strptime(s, "%Y-%m-%d").replace(tzinfo=local_tz)
-        end_local = start_local + timedelta(days=1)
-        return TimeRange(
-            start_utc=start_local.astimezone(timezone.utc),
-            end_utc=end_local.astimezone(timezone.utc),
-            expr=s,
-            tz_name=tz_name,
-        )
-
-    # Try RFC 3339 single datetime — caller probably meant "since this time"
-    try:
-        dt = datetime.fromisoformat(s.replace("Z", "+00:00"))
-        if dt.tzinfo is None:
-            dt = dt.replace(tzinfo=local_tz)
-        return TimeRange(
-            start_utc=dt.astimezone(timezone.utc),
-            end_utc=now_utc,
-            expr=f"since {s}",
-            tz_name=tz_name,
-        )
-    except ValueError:
-        pass
-
-    raise SystemExit(
-        f"discover_sessions: cannot parse --since {s!r}. "
-        f"Try: `last 2 hours`, `today`, `yesterday`, `2026-04-22`, "
-        f"`2026-04-22 to 2026-04-25`, or an ISO datetime."
-    )
-
-
-# ---- SQL composition -------------------------------------------------------
-
-def compose_sql(
-    *,
-    tr: TimeRange,
-    agent: Optional[str],
-    channel: Optional[str],
-    outcome: Optional[str],
-    grep: Optional[str],
-    grep_case_sensitive: bool = False,
-    limit: int,
-) -> str:
-    """Build the discovery SQL. Conditional JOINs + WHERE ANDs are
-    composed from `tr` + flag args; the SQL skeleton lives at
-    `assets/dc/discover_sessions.sql`."""
-    joins: list[str] = []
-    wheres: list[str] = [
-        f"s.ssot__StartTimestamp__c >= '{tr.iso(tr.start_utc)}'",
-        f"s.ssot__StartTimestamp__c < '{tr.iso(tr.end_utc)}'",
-    ]
-
-    if agent:
-        joins.append(
-            "JOIN ssot__AiAgentSessionParticipant__dlm p "
-            "ON s.ssot__Id__c = p.ssot__AiAgentSessionId__c"
-        )
-        wheres.append(f"p.ssot__AiAgentApiName__c = '{_escape_sql_literal(agent)}'")
-
-    if grep:
-        joins.append(
-            "JOIN ssot__AiAgentInteraction__dlm i "
-            "ON s.ssot__Id__c = i.ssot__AiAgentSessionId__c"
-        )
-        joins.append(
-            "JOIN ssot__AiAgentInteractionMessage__dlm m "
-            "ON i.ssot__Id__c = m.ssot__AiAgentInteractionId__c"
-        )
-        # LIKE wildcards (%, _) and the escape char (!) are neutralized so
-        # `--grep "100%_off"` matches the literal substring. Quote-doubling
-        # is layered on top via _escape_sql_literal. The `ESCAPE '!'` clause
-        # tells SQL the escape char is `!`.
-        pat = _escape_sql_literal(_escape_like_pattern(grep))
-        if grep_case_sensitive:
-            wheres.append(
-                f"m.ssot__ContentText__c LIKE '%{pat}%' ESCAPE '{_LIKE_ESCAPE}'"
-            )
-        else:
-            # Lowercase both sides so the predicate is case-insensitive.
-            # Default behaviour — users almost always type the quoted
-            # phrase in whatever case they remember, not the case the
-            # agent rendered it in.
-            wheres.append(
-                f"LOWER(m.ssot__ContentText__c) LIKE LOWER('%{pat}%') "
-                f"ESCAPE '{_LIKE_ESCAPE}'"
-            )
-
-    if channel:
-        ch = _CHANNEL_ALIAS.get(channel, channel)
-        wheres.append(f"s.ssot__AiAgentChannelType__c = '{_escape_sql_literal(ch)}'")
-
-    if outcome:
-        wheres.append(f"s.ssot__AiAgentSessionEndType__c = '{_escape_sql_literal(outcome)}'")
-
-    # DISTINCT when JOINs are present — a session can JOIN multiple
-    # participants / messages and explode rows.
-    columns = (
-        "s.ssot__Id__c, s.ssot__StartTimestamp__c, s.ssot__EndTimestamp__c, "
-        "s.ssot__AiAgentChannelType__c, s.ssot__AiAgentSessionEndType__c"
-    )
-    select_list = f"DISTINCT {columns}" if joins else columns
-
-    return load_sql(
-        "discover_sessions",
-        SELECT_LIST=select_list,
-        JOINS="\n".join(joins),
-        WHERE_CLAUSE=" AND ".join(wheres),
-        LIMIT=str(limit),
-    )
-
-
-# ---- agent-name enrichment -------------------------------------------------
-
-_NAME_NOT_SET = {"", "NOT_SET", None}
-
-
-def fetch_agent_names(
-    session_ids: list[str], *, instance_url: str, token: str
-) -> dict[str, str]:
-    """One follow-up query to grab agent names for discovered sessions.
-    The discovery query itself drops agent name from the projection
-    because adding it to SELECT forces a participant JOIN on every query
-    (including the no-filter case) and DC penalizes that.
-
-    Returns {session_uuid: agent_api_name}. Missing sessions → not in dict.
-
-    No role filter on the SQL. Some agent shapes (e.g. MyAgent) leave
-    AGENT-role rows with ``ssot__AiAgentApiName__c = 'NOT_SET'`` while USER-
-    role rows correctly carry the agent's api_name. Filtering to ``role =
-    'AGENT'`` would either return no row (picker shows '—' for a session
-    that clearly has an agent) or return the literal ``'NOT_SET'`` (picker
-    misleads the operator). Dropping the role filter and de-duplicating in
-    Python with the dominant-agent rule (``sorted(...)[0]``) recovers both
-    cases. Mirrors the fallback in ``fetch_dc._resolve_identity``.
-    """
-    if not session_ids:
-        return {}
-    quoted = ", ".join(f"'{_escape_sql_literal(sid)}'" for sid in session_ids)
-    sql = (
-        "SELECT ssot__AiAgentSessionId__c, ssot__AiAgentApiName__c "
-        "FROM ssot__AiAgentSessionParticipant__dlm "
-        f"WHERE ssot__AiAgentSessionId__c IN ({quoted})"
-    )
-    try:
-        rows = post(sql, instance_url, token, "discover_sessions_agent_names")
-    except DCQueryError:
-        return {}  # non-fatal — picker shows "—" for agent
-    # Group all api_names per session, drop NOT_SET sentinels, dominant-agent
-    # pick (lexicographic first) to match the rule used in fetch_dc.
-    # Sessions where every participant row is NOT_SET fall out of the result
-    # entirely — the picker will show '—', which is more honest than
-    # displaying the literal 'NOT_SET'.
-    by_sid: dict[str, set[str]] = {}
-    for row in rows:
-        sid = row.get("ssot__AiAgentSessionId__c")
-        name = row.get("ssot__AiAgentApiName__c")
-        if not sid or name in _NAME_NOT_SET:
-            continue
-        by_sid.setdefault(sid, set()).add(name)
-    return {sid: sorted(names)[0] for sid, names in by_sid.items() if names}
-
-
-# ---- rendering -------------------------------------------------------------
-
-def _fmt_duration(start_iso: Optional[str], end_iso: Optional[str]) -> str:
-    """Human-readable duration (e.g. "1m 12s", "28s") from two ISO timestamps.
-    Returns "—" if start_iso is missing or unparseable. When end_iso is
-    None but start_iso parses, computes elapsed-from-now and appends "+"
-    to signal the session is still open (or end timestamp hasn't
-    materialized in DC yet)."""
-    if not start_iso:
-        return "—"
-    try:
-        start = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
-    except ValueError:
-        return "—"
-    ongoing = False
-    if not end_iso:
-        end = datetime.now(timezone.utc)
-        ongoing = True
-    else:
-        try:
-            end = datetime.fromisoformat(end_iso.replace("Z", "+00:00"))
-        except ValueError:
-            return "—"
-    seconds = int((end - start).total_seconds())
-    if seconds < 0:
-        return "—"
-    suffix = "+" if ongoing else ""
-    if seconds < 60:
-        return f"{seconds}s{suffix}"
-    m, s = divmod(seconds, 60)
-    if m < 60:
-        return (f"{m}m {s}s" if s else f"{m}m") + suffix
-    h, m = divmod(m, 60)
-    return f"{h}h {m}m{suffix}"
-
-
-def _fmt_channel(raw: Optional[str]) -> str:
-    """Compact channel label for the picker."""
-    if not raw:
-        return "—"
-    # Reverse the Messaging alias for readability.
-    if raw == "SCRT2 - EmbeddedMessaging":
-        return "Messaging"
-    # Custom channel labels arrive HTML-encoded from DC (e.g. "E &amp; O").
-    return html.unescape(raw)
-
-
-def _fmt_start(iso: Optional[str]) -> str:
-    if not iso:
-        return "—"
-    try:
-        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
-    except ValueError:
-        return iso
-    return dt.strftime("%Y-%m-%d %H:%M:%SZ")
-
-
-def render_picker(
-    *,
-    rows: list[dict],
-    agent_by_sid: dict[str, str],
-    org: str,
-    tr: TimeRange,
-    filters: dict[str, Optional[str]],
-    composed_sql: str,
-) -> str:
-    """Markdown picker. Returned as a string so the caller prints once
-    (single subprocess write on stdout)."""
-    filter_bits = [f"{tr.expr}"]
-    for k, v in filters.items():
-        if v:
-            filter_bits.append(f"{k}={v}")
-    header_filters = " · ".join(filter_bits)
-
-    if not rows:
-        # Echo the composed SQL so the user can widen the query.
-        return (
-            f"No sessions matched in **{org}** ({header_filters}).\n\n"
-            f"Range searched (UTC): `{tr.iso(tr.start_utc)}` → `{tr.iso(tr.end_utc)}`\n"
-            f"Local tz: `{tr.tz_name}`\n\n"
-            f"Composed SQL:\n```sql\n{composed_sql}\n```\n"
-            f"Try widening: larger `--since`, drop `--channel`/`--outcome`, or broaden `--grep`."
-        )
-
-    lines = [
-        f"Found **{len(rows)}** session{'s' if len(rows) != 1 else ''} in "
-        f"**{org}** ({header_filters}):",
-        "",
-        "| # | UUID | Start (UTC) | Agent | Channel | Duration | Outcome |",
-        "|---|------|-------------|-------|---------|----------|---------|",
-    ]
-    for i, row in enumerate(rows, start=1):
-        uuid = row.get("ssot__Id__c") or "—"
-        agent = agent_by_sid.get(uuid, "—")
-        lines.append(
-            f"| {i} | `{uuid}` | {_fmt_start(row.get('ssot__StartTimestamp__c'))} "
-            f"| {agent} | {_fmt_channel(row.get('ssot__AiAgentChannelType__c'))} "
-            f"| {_fmt_duration(row.get('ssot__StartTimestamp__c'), row.get('ssot__EndTimestamp__c'))} "
-            f"| {row.get('ssot__AiAgentSessionEndType__c') or '—'} |"
-        )
-    lines.append("")
-    lines.append(f"Pick a number (1–{len(rows)}) to trace, or paste a UUID.")
-    return "\n".join(lines)
-
-
-# ---- CLI -------------------------------------------------------------------
-
-def main() -> int:
-    ap = argparse.ArgumentParser(
-        description="Find candidate Agentforce sessions via Data Cloud. "
-                    "Prints a numbered picker; no artifacts written.",
-    )
-    ap.add_argument("--org", required=True, help="sf CLI org alias (the one you configured via `sf org login`)")
-    ap.add_argument("--since", help='time range: "last 2 hours" | "today" | "yesterday" | '
-                                    '"YYYY-MM-DD" | "YYYY-MM-DD to YYYY-MM-DD" | ISO datetime. '
-                                    'Default: last 24 hours.')
-    ap.add_argument("--agent", help="Agent API name (exact match)")
-    ap.add_argument("--channel", help="Builder | Messaging | Voice (or full STDM string)")
-    ap.add_argument("--outcome", help="USER_ENDED | ESCALATED | TRANSFERRED | TIMEOUT | NOT_SET")
-    ap.add_argument(
-        "--grep",
-        help="substring in conversation text (user + agent); "
-             "case-insensitive by default — pass --grep-case-sensitive for exact match",
-    )
-    ap.add_argument(
-        "--grep-case-sensitive",
-        action="store_true",
-        default=False,
-        help="opt-in: make --grep case-sensitive (rare; default is case-insensitive)",
-    )
-    ap.add_argument("--tz", help="IANA timezone override for calendar-day resolution")
-    ap.add_argument("--limit", type=int, default=20, help="max sessions (default 20)")
-    # Runtime-agnostic path overrides; default to ~/.vibe/...
-    # discover_sessions doesn't read DATA_ROOT directly, but accepts the flags
-    # for contract consistency with the other 4 d360 entry scripts.
-    from _shared.cli_override import add_cli_flags, apply_overrides
-    add_cli_flags(ap)
-    args = ap.parse_args()
-    apply_overrides(args, caller_globals=globals())
-
-    if args.limit < 1:
-        raise SystemExit("discover_sessions: --limit must be >= 1")
-
-    tr = parse_time_expr(args.since, args.tz or "")
-    sql = compose_sql(
-        tr=tr,
-        agent=args.agent,
-        channel=args.channel,
-        outcome=args.outcome,
-        grep=args.grep,
-        grep_case_sensitive=args.grep_case_sensitive,
-        limit=args.limit,
-    )
-
-    instance_url, token = resolve_org(args.org)
-    try:
-        rows = post(sql, instance_url, token, "discover_sessions")
-    except DCQueryError as e:
-        print(f"discover_sessions: DC query failed.\n{e}", file=sys.stderr)
-        return 1
-
-    agent_by_sid: dict[str, str] = {}
-    if rows:
-        sids = [r["ssot__Id__c"] for r in rows if r.get("ssot__Id__c")]
-        agent_by_sid = fetch_agent_names(sids, instance_url=instance_url, token=token)
-
-    filters = {
-        "agent": args.agent,
-        "channel": args.channel,
-        "outcome": args.outcome,
-        "grep": args.grep,
-        # Only surface the case-sensitive note when --grep is in play AND
-        # the user opted into exact match — the default (insensitive) is
-        # the boring path and shouldn't clutter the picker header.
-        "grep_case_sensitive": "yes" if (args.grep and args.grep_case_sensitive) else None,
-    }
-    print(render_picker(
-        rows=rows,
-        agent_by_sid=agent_by_sid,
-        org=args.org,
-        tr=tr,
-        filters=filters,
-        composed_sql=sql,
-    ))
-    return 0 if rows else 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())