teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/services/listing.py

@@ -0,0 +1,826 @@
+"""Meeting transcript listing service via MCPS worker injection.
+
+Connects to a Teams web worker via CDP, injects JavaScript to call the
+MCPS ``startListArtifactsByUserWorkflow`` API, and returns structured
+meeting artifact data.  Day queries are dispatched concurrently (up to 5
+in parallel) for performance.
+
+Public API:
+    run_list_transcripts(port, days, format_json, output_path, logger, shutdown)
+    resolve_meeting_id(port, meeting_id, logger, shutdown, tenant_id) -> (str, str, str)
+    resolve_call_id(port, call_id, logger, shutdown, tenant_id) -> (str, str, str)
+
+Schema version: 1.1.0
+Created: 2026-04-28
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import datetime as dt
+import typing
+import uuid
+
+import websockets
+
+from teams_transcripts.domain.mcps import (
+    build_thread_id,
+    extract_meeting_id,
+    format_artifacts_json,
+    format_artifacts_table,
+    parse_mcps_response,
+)
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.adapters.cdp.connection import WebSocketLike
+    from teams_transcripts.domain.models import MeetingArtifact
+    from teams_transcripts.infrastructure.logging import Logger
+    from teams_transcripts.infrastructure.signals import ShutdownCoordinator
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_MAX_CONCURRENT_DAYS = 5
+"""Maximum number of day queries running in parallel."""
+
+_MCPS_PAGE_SIZE = 20
+"""Number of results per MCPS page."""
+
+
+# ---------------------------------------------------------------------------
+# Concurrent CDP connection (multiplexed)
+# ---------------------------------------------------------------------------
+
+
+class _MuxCDPConnection:
+    """A concurrency-safe CDP connection that multiplexes requests.
+
+    Unlike :class:`~adapters.cdp.connection.CDPConnection` (which uses a
+    simple recv loop per request and is not safe for concurrent use), this
+    class runs a single background recv loop that dispatches responses to
+    the correct waiting future by message ID.
+
+    This allows multiple coroutines to call :meth:`send` concurrently on
+    the same WebSocket connection.
+    """
+
+    def __init__(self, ws: WebSocketLike) -> None:
+        self._ws = ws
+        self._msg_id = 0
+        self._pending: dict[int, asyncio.Future[dict]] = {}
+        self._recv_task: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        """Start the background receive loop."""
+        self._recv_task = asyncio.get_event_loop().create_task(self._recv_loop())
+
+    async def stop(self) -> None:
+        """Stop the background receive loop."""
+        if self._recv_task:
+            self._recv_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._recv_task
+
+    async def _recv_loop(self) -> None:
+        """Background loop that reads messages and dispatches to futures."""
+        import json
+
+        try:
+            while True:
+                raw = await self._ws.recv()
+                data = json.loads(raw)
+                msg_id = data.get("id")
+                if msg_id is not None and msg_id in self._pending:
+                    self._pending[msg_id].set_result(data)
+                    del self._pending[msg_id]
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            # Connection closed or error — cancel all pending futures
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.cancel()
+            self._pending.clear()
+
+    async def send(
+        self,
+        method: str,
+        params: dict | None = None,
+        timeout: float = 30,
+    ) -> dict:
+        """Send a CDP command and wait for the matching response.
+
+        Safe to call concurrently from multiple coroutines.
+        """
+        import json
+
+        self._msg_id += 1
+        mid = self._msg_id
+        future: asyncio.Future[dict] = asyncio.get_event_loop().create_future()
+        self._pending[mid] = future
+
+        await self._ws.send(json.dumps({"id": mid, "method": method, "params": params or {}}))
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        except (asyncio.TimeoutError, asyncio.CancelledError):
+            self._pending.pop(mid, None)
+            future.cancel()
+            raise
+
+
+_JS_RESOLVE_CONTEXT = """\
+(async () => {
+    const ctx = workerServer._stateAndRequestHandlers
+        .get('graphql').requestHandler.contextValue;
+    const ews = ctx.managers.artifactsPlatformManager
+        .managerContext.workflowStarters.existingWorkflowStarter;
+
+    // Resolve UPN and tenant from Graph token JWT payload
+    let upn = null;
+    let tid = null;
+    try {
+        const token = await ctx.discoverService.aad.acquireToken(
+            'https://graph.microsoft.com'
+        );
+        if (token) {
+            const tokenStr = typeof token === 'string' ? token : token.token;
+            if (tokenStr) {
+                const parts = tokenStr.split('.');
+                const payload = JSON.parse(atob(parts[1]));
+                upn = payload.upn || payload.preferred_username
+                    || payload.unique_name || null;
+                tid = payload.tid || null;
+            }
+        }
+    } catch(e) {}
+
+    return { hasEws: !!ews, upn: upn, tid: tid };
+})()
+"""
+
+_JS_QUERY_DAY_TEMPLATE = """\
+(async () => {{
+    const ctx = workerServer._stateAndRequestHandlers
+        .get('graphql').requestHandler.contextValue;
+    const ews = ctx.managers.artifactsPlatformManager
+        .managerContext.workflowStarters.existingWorkflowStarter;
+
+    const results = [];
+    let skiptoken = undefined;
+
+    while (true) {{
+        const params = {{
+            correlationId: '{correlation_id}',
+            top: {page_size},
+            userUpn: '{upn}',
+            startDateTime: '{start_dt}',
+            endDateTime: '{end_dt}',
+            includeTypes: 'TranscriptV2',
+            callerApp: 'TeamsRecapPodcastDesktop',
+        }};
+        if (skiptoken) params.skiptoken = skiptoken;
+
+        const resp = await ews.startListArtifactsByUserWorkflow(params);
+        if (!resp.value || resp.value.length === 0) break;
+        results.push(...resp.value);
+
+        if (!resp.paginationInfo || !resp.paginationInfo.hasNextPage) break;
+        skiptoken = resp.paginationInfo.skipToken;
+    }}
+
+    return {{ value: results }};
+}})()
+"""
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_day_query_js(upn: str, query_date: dt.date) -> str:
+    """Build the JavaScript expression to query a single day.
+
+    Args:
+        upn: User principal name (email).
+        query_date: The date to query.
+
+    Returns:
+        JavaScript expression string for Runtime.evaluate.
+    """
+    start_dt = f"{query_date.isoformat()}T00:00:00Z"
+    end_dt = f"{(query_date + dt.timedelta(days=1)).isoformat()}T00:00:00Z"
+    correlation_id = str(uuid.uuid4())
+
+    return _JS_QUERY_DAY_TEMPLATE.format(
+        correlation_id=correlation_id,
+        page_size=_MCPS_PAGE_SIZE,
+        upn=upn,
+        start_dt=start_dt,
+        end_dt=end_dt,
+    )
+
+
+async def _query_day(
+    cdp: _MuxCDPConnection,
+    upn: str,
+    query_date: dt.date,
+    semaphore: asyncio.Semaphore,
+    logger: Logger,
+) -> list[MeetingArtifact]:
+    """Query a single day with pagination, gated by semaphore.
+
+    Args:
+        cdp: Active CDP connection to the worker target.
+        upn: User principal name.
+        query_date: The date to query.
+        semaphore: Concurrency limiter.
+        logger: Logger instance.
+
+    Returns:
+        List of meeting artifacts for the queried day.
+    """
+    async with semaphore:
+        js = _build_day_query_js(upn, query_date)
+        resp = await cdp.send(
+            "Runtime.evaluate",
+            {
+                "expression": js,
+                "awaitPromise": True,
+                "returnByValue": True,
+            },
+            timeout=30,
+        )
+
+        # Extract the result value
+        result = resp.get("result", {}).get("result", {}).get("value")
+        if not result or not isinstance(result, dict):
+            # Check for exceptions
+            exception_details = resp.get("result", {}).get("exceptionDetails")
+            if exception_details:
+                text = exception_details.get("text", "unknown error")
+                logger.log(
+                    "list-transcripts",
+                    f"  {query_date}: query failed ({text})",
+                )
+            return []
+
+        artifacts = parse_mcps_response(result, query_date)
+        if artifacts:
+            logger.log(
+                "list-transcripts",
+                f"  {query_date}: {len(artifacts)} meeting(s)",
+            )
+        return artifacts
+
+
+async def _resolve_upn(
+    cdp: _MuxCDPConnection,
+    tenant_id: str | None = None,
+) -> str | None:
+    """Resolve the user principal name from the worker context.
+
+    Args:
+        cdp: Active CDP connection to the worker target.
+        tenant_id: If provided, only return UPN when the worker's
+            JWT tenant claim matches this prefix.
+
+    Returns:
+        UPN string, or None if resolution failed or tenant mismatch.
+    """
+    resp = await cdp.send(
+        "Runtime.evaluate",
+        {
+            "expression": _JS_RESOLVE_CONTEXT,
+            "awaitPromise": True,
+            "returnByValue": True,
+        },
+        timeout=15,
+    )
+    result = resp.get("result", {}).get("result", {}).get("value")
+    if not result or not isinstance(result, dict):
+        return None
+    if not result.get("hasEws"):
+        return None
+    # Tenant check: if requested, verify this worker belongs to the right tenant
+    if tenant_id:
+        tid = result.get("tid") or ""
+        if not tid.startswith(tenant_id):
+            return None
+    return result.get("upn") or None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+async def resolve_meeting_id(
+    port: int,
+    meeting_id: str,
+    *,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    format_json: bool = False,
+    tenant_id: str | None = None,
+    force_restart: bool = False,
+) -> tuple[str, str, str]:
+    """Resolve a meeting UUID to its subject, date, and thread_id via MCPS.
+
+    Connects to the Teams worker, queries a date range (up to 90 days back)
+    to find the meeting entry whose thread_id matches the given UUID, and
+    returns the subject string, date, and full thread_id.
+
+    The returned ``thread_id`` enables direct navigation to the meeting
+    chat without the search-click-verify cycle.
+
+    Args:
+        port: CDP debugging port number.
+        meeting_id: Meeting UUID (e.g. ``2b4c1f5c-...``).
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        format_json: Whether to emit JSON error output.
+        tenant_id: Optional tenant ID prefix to filter workers.
+
+    Returns:
+        A tuple of ``(subject, date_str, thread_id)`` where ``date_str``
+        is ISO format (``YYYY-MM-DD``) and ``thread_id`` is the full
+        Teams thread identifier (e.g. ``19:meeting_...@thread.v2``).
+
+    Raises:
+        SystemExit: If the meeting cannot be found or CDP is unavailable.
+    """
+    from teams_transcripts.adapters.cdp.helpers import (
+        cdp_http_get,
+        filter_worker_targets,
+        verify_cdp,
+    )
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+    from teams_transcripts.infrastructure.errors import (
+        EXIT_CDP_UNAVAILABLE,
+        EXIT_MEETING_NOT_FOUND,
+        exit_error,
+    )
+
+    logger.log("resolve-id", f"Resolving meeting ID {meeting_id[:12]}...")
+
+    # Ensure Teams is running and CDP is available
+    ensure_teams_running(
+        port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=format_json,
+        force=force_restart,
+    )
+    verify_cdp(port, logger=logger, shutdown=shutdown, format_json=format_json)
+
+    # Discover workers
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "Could not list CDP targets.",
+            step="resolve-id",
+            format_json=format_json,
+        )
+
+    workers = filter_worker_targets(raw_targets, tenant_id=tenant_id)
+    if not workers:
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "No Teams web worker targets found.",
+            step="resolve-id",
+            format_json=format_json,
+        )
+
+    # Query workers to find the meeting
+    today = dt.datetime.now(tz=dt.timezone.utc).date()
+    # Search 90 days back (covers the typical retention period)
+    search_days = 90
+    date_range = [today - dt.timedelta(days=i) for i in range(search_days)]
+    semaphore = asyncio.Semaphore(_MAX_CONCURRENT_DAYS)
+
+    # Pre-compute both matching strategies: exact thread_id and extracted UUID.
+    # The exact match handles the common case; the UUID comparison handles
+    # format variations (URL-safe base64, padding differences, etc.).
+    target_thread_id = build_thread_id(meeting_id)
+    target_id_lower = meeting_id.lower()
+
+    for worker in workers:
+        worker_id = worker.get("id", "")
+        ws_url = worker.get("webSocketDebuggerUrl", "")
+        if not ws_url:
+            ws_url = f"ws://127.0.0.1:{port}/devtools/page/{worker_id}"
+
+        cdp: _MuxCDPConnection | None = None
+        ws_conn = None
+        try:
+            ws_conn = await websockets.connect(ws_url, max_size=16 * 1024 * 1024)
+            cdp = _MuxCDPConnection(ws_conn)
+            cdp.start()
+            upn = await _resolve_upn(cdp, tenant_id=tenant_id)
+            if not upn:
+                await cdp.stop()
+                await ws_conn.close()
+                continue
+
+            logger.log("resolve-id", f"Searching MCPS for meeting (user: {upn})...")
+
+            # Query days until we find the matching meeting.
+            # Process in batches; use return_exceptions=True so that a single
+            # day-query timeout or error does not discard the entire batch.
+            for batch_start in range(0, search_days, _MAX_CONCURRENT_DAYS):
+                shutdown.check_shutdown()
+                batch = date_range[batch_start : batch_start + _MAX_CONCURRENT_DAYS]
+                tasks = [_query_day(cdp, upn, d, semaphore, logger) for d in batch]
+                results = await asyncio.gather(*tasks, return_exceptions=True)
+                for day_results in results:
+                    # Skip failed day queries (returned as exceptions)
+                    if isinstance(day_results, BaseException):
+                        continue
+                    for artifact in day_results:
+                        # Primary: exact thread_id match
+                        if artifact.thread_id == target_thread_id:
+                            logger.log(
+                                "resolve-id",
+                                f"Found: '{artifact.subject}' on {artifact.date}",
+                            )
+                            await cdp.stop()
+                            await ws_conn.close()
+                            return (
+                                artifact.subject,
+                                artifact.date.isoformat(),
+                                artifact.thread_id,
+                            )
+                        # Fallback: compare extracted UUIDs (handles encoding
+                        # differences between standard and URL-safe base64,
+                        # padding variations, and case mismatches).
+                        extracted = extract_meeting_id(artifact.thread_id)
+                        if extracted.lower() == target_id_lower:
+                            logger.log(
+                                "resolve-id",
+                                f"Found (UUID match): '{artifact.subject}' on {artifact.date}",
+                            )
+                            await cdp.stop()
+                            await ws_conn.close()
+                            return (
+                                artifact.subject,
+                                artifact.date.isoformat(),
+                                artifact.thread_id,
+                            )
+
+            await cdp.stop()
+            await ws_conn.close()
+
+            # If a specific tenant was requested, don't try other workers
+            if tenant_id:
+                break
+
+        except SystemExit:
+            raise
+        except Exception:
+            if cdp:
+                with contextlib.suppress(Exception):
+                    await cdp.stop()
+            if ws_conn:
+                with contextlib.suppress(Exception):
+                    await ws_conn.close()
+            continue
+
+    exit_error(
+        EXIT_MEETING_NOT_FOUND,
+        "MEETING_NOT_FOUND",
+        f"Meeting ID {meeting_id} not found in the last {search_days} days of transcripts.",
+        step="resolve-id",
+        format_json=format_json,
+    )
+    return ("", "", "")  # unreachable — exit_error calls sys.exit
+
+
+async def resolve_call_id(
+    port: int,
+    call_id: str,
+    *,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    format_json: bool = False,
+    tenant_id: str | None = None,
+    force_restart: bool = False,
+) -> tuple[str, str, str]:
+    """Resolve a call ID to its subject, date, and thread_id via MCPS.
+
+    Connects to the Teams worker, queries a date range (up to 90 days back)
+    to find the meeting entry whose call_id matches the given value, and
+    returns the subject string, date, and full thread_id.
+
+    Call IDs uniquely identify a specific occurrence, making this the
+    preferred resolution method for recurring meetings.
+
+    Args:
+        port: CDP debugging port number.
+        call_id: Call identifier (from --list-transcripts Call ID column).
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        format_json: Whether to emit JSON error output.
+        tenant_id: Optional tenant ID prefix to filter workers.
+
+    Returns:
+        A tuple of ``(subject, date_str, thread_id)`` where ``date_str``
+        is ISO format (``YYYY-MM-DD``) and ``thread_id`` is the full
+        Teams thread identifier (e.g. ``19:meeting_...@thread.v2``).
+
+    Raises:
+        SystemExit: If the call cannot be found or CDP is unavailable.
+    """
+    from teams_transcripts.adapters.cdp.helpers import (
+        cdp_http_get,
+        filter_worker_targets,
+        verify_cdp,
+    )
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+    from teams_transcripts.infrastructure.errors import (
+        EXIT_CDP_UNAVAILABLE,
+        EXIT_MEETING_NOT_FOUND,
+        exit_error,
+    )
+
+    logger.log("resolve-call-id", f"Resolving call ID '{call_id}'...")
+
+    # Ensure Teams is running and CDP is available
+    ensure_teams_running(
+        port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=format_json,
+        force=force_restart,
+    )
+    verify_cdp(port, logger=logger, shutdown=shutdown, format_json=format_json)
+
+    # Discover workers
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "Could not list CDP targets.",
+            step="resolve-call-id",
+            format_json=format_json,
+        )
+
+    workers = filter_worker_targets(raw_targets, tenant_id=tenant_id)
+    if not workers:
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "No Teams web worker targets found.",
+            step="resolve-call-id",
+            format_json=format_json,
+        )
+
+    # Query workers to find the meeting by call_id
+    today = dt.datetime.now(tz=dt.timezone.utc).date()
+    search_days = 90
+    date_range = [today - dt.timedelta(days=i) for i in range(search_days)]
+    semaphore = asyncio.Semaphore(_MAX_CONCURRENT_DAYS)
+
+    for worker in workers:
+        worker_id = worker.get("id", "")
+        ws_url = worker.get("webSocketDebuggerUrl", "")
+        if not ws_url:
+            ws_url = f"ws://127.0.0.1:{port}/devtools/page/{worker_id}"
+
+        cdp: _MuxCDPConnection | None = None
+        ws_conn = None
+        try:
+            ws_conn = await websockets.connect(ws_url, max_size=16 * 1024 * 1024)
+            cdp = _MuxCDPConnection(ws_conn)
+            cdp.start()
+            upn = await _resolve_upn(cdp, tenant_id=tenant_id)
+            if not upn:
+                await cdp.stop()
+                await ws_conn.close()
+                continue
+
+            logger.log("resolve-call-id", f"Searching MCPS for call (user: {upn})...")
+
+            # Query days until we find the matching call_id.
+            for batch_start in range(0, search_days, _MAX_CONCURRENT_DAYS):
+                shutdown.check_shutdown()
+                batch = date_range[batch_start : batch_start + _MAX_CONCURRENT_DAYS]
+                tasks = [_query_day(cdp, upn, d, semaphore, logger) for d in batch]
+                results = await asyncio.gather(*tasks, return_exceptions=True)
+                for day_results in results:
+                    if isinstance(day_results, BaseException):
+                        continue
+                    for artifact in day_results:
+                        if artifact.call_id == call_id:
+                            logger.log(
+                                "resolve-call-id",
+                                f"Found: '{artifact.subject}' on {artifact.date}",
+                            )
+                            await cdp.stop()
+                            await ws_conn.close()
+                            return (
+                                artifact.subject,
+                                artifact.date.isoformat(),
+                                artifact.thread_id,
+                            )
+
+            await cdp.stop()
+            await ws_conn.close()
+
+            # If a specific tenant was requested, don't try other workers
+            if tenant_id:
+                break
+
+        except SystemExit:
+            raise
+        except Exception:
+            if cdp:
+                with contextlib.suppress(Exception):
+                    await cdp.stop()
+            if ws_conn:
+                with contextlib.suppress(Exception):
+                    await ws_conn.close()
+            continue
+
+    exit_error(
+        EXIT_MEETING_NOT_FOUND,
+        "MEETING_NOT_FOUND",
+        f"Call ID '{call_id}' not found in the last {search_days} days of transcripts.",
+        step="resolve-call-id",
+        format_json=format_json,
+    )
+    return ("", "", "")  # unreachable — exit_error calls sys.exit
+
+
+async def run_list_transcripts(
+    port: int,
+    *,
+    days: int,
+    logger: Logger,
+    shutdown: ShutdownCoordinator,
+    format_json: bool,
+    output_path: str | None = None,
+    tenant_id: str | None = None,
+    force_restart: bool = False,
+) -> None:
+    """List meetings with transcripts for the given number of days.
+
+    Connects to the Teams web worker via CDP, queries each day in
+    parallel (up to 5 concurrent), and outputs results as a table
+    or JSON.
+
+    Args:
+        port: CDP debugging port number.
+        days: Number of days back to query (1 = today only).
+        logger: Logger instance.
+        shutdown: Shutdown coordinator.
+        format_json: If ``True``, output JSON; otherwise text table.
+        output_path: File path to write to, or ``None`` for stdout.
+        tenant_id: Optional tenant ID to filter worker targets.
+    """
+    import sys
+
+    from teams_transcripts.adapters.cdp.helpers import (
+        cdp_http_get,
+        filter_worker_targets,
+        verify_cdp,
+    )
+    from teams_transcripts.adapters.cdp.teams import ensure_teams_running
+    from teams_transcripts.infrastructure.errors import (
+        EXIT_CDP_UNAVAILABLE,
+        EXIT_DOWNLOAD_FAILED,
+        exit_error,
+    )
+
+    # Step 1: Ensure Teams is running with CDP
+    ensure_teams_running(
+        port,
+        logger=logger,
+        shutdown=shutdown,
+        format_json=format_json,
+        force=force_restart,
+    )
+
+    # Step 2: Verify CDP
+    verify_cdp(port, logger=logger, shutdown=shutdown, format_json=format_json)
+
+    # Step 3: Discover worker targets
+    raw_targets = cdp_http_get(port, "/json")
+    if not raw_targets or not isinstance(raw_targets, list):
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "Could not list CDP targets.",
+            step="list-transcripts",
+            format_json=format_json,
+        )
+
+    workers = filter_worker_targets(raw_targets, tenant_id=tenant_id)
+    if not workers:
+        exit_error(
+            EXIT_CDP_UNAVAILABLE,
+            "CDP_UNAVAILABLE",
+            "No Teams web worker targets found. Is Teams running and signed in?",
+            step="list-transcripts",
+            format_json=format_json,
+        )
+
+    # Step 3: Connect to workers and query
+    # When --tenant is specified, use the first matching worker.
+    # When no tenant is specified, try all workers and aggregate results
+    # across tenants.
+    today = dt.datetime.now(tz=dt.timezone.utc).date()
+    date_range = [today - dt.timedelta(days=i) for i in range(days)]
+    semaphore = asyncio.Semaphore(_MAX_CONCURRENT_DAYS)
+
+    all_artifacts: list[MeetingArtifact] = []
+    seen_upns: set[str] = set()
+
+    for worker in workers:
+        worker_id = worker.get("id", "")
+        ws_url = worker.get("webSocketDebuggerUrl", "")
+        if not ws_url:
+            ws_url = f"ws://127.0.0.1:{port}/devtools/page/{worker_id}"
+
+        logger.log("list-transcripts", f"Trying worker {worker_id[:12]}...")
+
+        cdp: _MuxCDPConnection | None = None
+        ws_conn = None
+        try:
+            ws_conn = await websockets.connect(ws_url, max_size=16 * 1024 * 1024)
+            cdp = _MuxCDPConnection(ws_conn)
+            cdp.start()
+            upn = await _resolve_upn(cdp, tenant_id=tenant_id)
+            if not upn:
+                await cdp.stop()
+                await ws_conn.close()
+                continue
+
+            # Skip if we already queried this UPN (same tenant, different worker)
+            if upn in seen_upns:
+                await cdp.stop()
+                await ws_conn.close()
+                continue
+            seen_upns.add(upn)
+
+            logger.log("list-transcripts", f"User: {upn}")
+            logger.log("list-transcripts", f"Querying {days} day(s)...")
+
+            tasks = [
+                _query_day(cdp, upn, query_date, semaphore, logger) for query_date in date_range
+            ]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            for day_results in results:
+                if isinstance(day_results, BaseException):
+                    continue
+                all_artifacts.extend(day_results)
+
+            await cdp.stop()
+            await ws_conn.close()
+
+            # If a specific tenant was requested, stop after the first match
+            if tenant_id:
+                break
+
+        except Exception:
+            if cdp:
+                await cdp.stop()
+            if ws_conn:
+                await ws_conn.close()
+            continue
+
+    if not seen_upns:
+        exit_error(
+            EXIT_DOWNLOAD_FAILED,
+            "DOWNLOAD_FAILED",
+            "Could not resolve user principal name from any worker target.",
+            step="list-transcripts",
+            format_json=format_json,
+        )
+
+    # Sort by date descending
+    all_artifacts.sort(key=lambda a: a.date, reverse=True)
+
+    # Step 4: Format output
+    if format_json:
+        output = format_artifacts_json(all_artifacts)
+    else:
+        output = format_artifacts_table(all_artifacts)
+
+    # Step 5: Write to file or stdout
+    if output_path:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(output)
+            f.write("\n")
+        logger.log("list-transcripts", f"Output written to {output_path}")
+    else:
+        print(output)
+
+    sys.exit(0)