teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/adapters/cdp/teams.py

@@ -0,0 +1,463 @@
+"""Safe Microsoft Teams process management for CDP-based automation.
+
+Every process kill is guarded by a tri-state live-call probe.  The probe
+combines CoreAudio process activity with the macOS Accessibility tree so that
+video-only calls are protected as well as calls using Teams audio.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import subprocess
+import time
+import typing
+from dataclasses import dataclass
+from enum import Enum
+
+from teams_transcripts.adapters.cdp.helpers import cdp_http_get
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class LoggerLike(typing.Protocol):
+    def log(self, step: str, msg: str) -> None: ...
+
+
+class ShutdownLike(typing.Protocol):
+    def interruptible_sleep_sync(self, seconds: float) -> None: ...
+
+
+CDP_FLAGS: list[str] = [
+    "--disable-backgrounding-occluded-windows",
+    "--disable-renderer-backgrounding",
+    "--disable-hang-monitor",
+    "--disable-ipc-flooding-protection",
+    "--disable-smooth-scrolling",
+    "--run-all-compositor-stages-before-draw",
+    "--hide-scrollbars",
+    "--mute-audio",
+    "--silent-debugger-extension-api",
+    "--force-device-scale-factor=2",
+]
+
+_ENV_VAR = "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS"
+_TEAMS_PROCESS_PATTERN = r"Microsoft Teams\.app/Contents/|(^|/)MSTeams( |$)"
+_AUDIO_SAMPLE_COUNT = 3
+_AUDIO_SAMPLE_INTERVAL_SECONDS = 0.5
+
+
+class CallState(str, Enum):
+    """Whether Teams can safely be restarted."""
+
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    UNKNOWN = "unknown"
+
+
+class RestartBlockedError(RuntimeError):
+    """Raised when a restart is denied by the live-call safeguard."""
+
+    def __init__(self, call_state: CallState) -> None:
+        self.call_state = call_state
+        self.reason = "active_call" if call_state is CallState.ACTIVE else "call_state_unknown"
+        super().__init__(self.reason)
+
+
+@dataclass(frozen=True)
+class RestartResult:
+    """Outcome of a guarded Teams restart."""
+
+    restarted: bool
+    cdp_ready: bool
+    port: int
+    call_state: CallState
+    forced: bool
+
+    def to_dict(self) -> dict[str, object]:
+        """Return the MCP-facing representation."""
+        return {
+            "status": "ok" if self.cdp_ready else "error",
+            "restarted": self.restarted,
+            "cdp_ready": self.cdp_ready,
+            "port": self.port,
+            "call_state": self.call_state.value,
+            "forced": self.forced,
+        }
+
+
+class _AudioObjectPropertyAddress(ctypes.Structure):
+    _fields_ = [
+        ("mSelector", ctypes.c_uint32),
+        ("mScope", ctypes.c_uint32),
+        ("mElement", ctypes.c_uint32),
+    ]
+
+
+def _fourcc(value: str) -> int:
+    return int.from_bytes(value.encode("ascii"), byteorder="big")
+
+
+_AUDIO_SYSTEM_OBJECT = 1
+_AUDIO_OBJECT_UNKNOWN = 0
+_AUDIO_SCOPE_GLOBAL = _fourcc("glob")
+_AUDIO_ELEMENT_MAIN = 0
+_AUDIO_TRANSLATE_PID = _fourcc("id2p")
+_AUDIO_RUNNING_INPUT = _fourcc("piri")
+_AUDIO_RUNNING_OUTPUT = _fourcc("piro")
+
+
+def _build_cdp_flags(port: int) -> str:
+    """Build the WebView2 Chromium flags for a debugging port."""
+    return " ".join([f"--remote-debugging-port={port}", *CDP_FLAGS])
+
+
+def _set_launchctl_env(flags_value: str, *, logger: LoggerLike) -> None:
+    """Make WebView2 flags visible to apps launched by LaunchServices."""
+    subprocess.run(
+        ["launchctl", "setenv", _ENV_VAR, flags_value],
+        capture_output=True,
+        check=False,
+    )
+    logger.log("step1", f"launchctl setenv {_ENV_VAR} (port extracted from flags)")
+
+
+def _find_teams_processes() -> list[int] | None:
+    """Return Teams and Teams helper PIDs, or ``None`` if inspection failed."""
+    try:
+        result = subprocess.run(
+            ["pgrep", "-f", _TEAMS_PROCESS_PATTERN],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+
+    if result.returncode == 1:
+        return []
+    if result.returncode != 0:
+        return None
+
+    try:
+        return sorted({int(line) for line in result.stdout.splitlines() if line.strip()})
+    except (AttributeError, ValueError):
+        return None
+
+
+def _load_coreaudio() -> typing.Any:
+    coreaudio = ctypes.CDLL("/System/Library/Frameworks/CoreAudio.framework/CoreAudio")
+    get_data = coreaudio.AudioObjectGetPropertyData
+    get_data.argtypes = [
+        ctypes.c_uint32,
+        ctypes.POINTER(_AudioObjectPropertyAddress),
+        ctypes.c_uint32,
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_uint32),
+        ctypes.c_void_p,
+    ]
+    get_data.restype = ctypes.c_int32
+    return coreaudio
+
+
+def _audio_property(coreaudio: typing.Any, object_id: int, selector: int) -> bool:
+    address = _AudioObjectPropertyAddress(
+        selector,
+        _AUDIO_SCOPE_GLOBAL,
+        _AUDIO_ELEMENT_MAIN,
+    )
+    value = ctypes.c_uint32(0)
+    size = ctypes.c_uint32(ctypes.sizeof(value))
+    status = coreaudio.AudioObjectGetPropertyData(
+        object_id,
+        ctypes.byref(address),
+        0,
+        None,
+        ctypes.byref(size),
+        ctypes.byref(value),
+    )
+    if status != 0:
+        raise OSError(f"CoreAudio property query failed with OSStatus {status}")
+    return bool(value.value)
+
+
+def _audio_process_object(coreaudio: typing.Any, pid: int) -> int:
+    address = _AudioObjectPropertyAddress(
+        _AUDIO_TRANSLATE_PID,
+        _AUDIO_SCOPE_GLOBAL,
+        _AUDIO_ELEMENT_MAIN,
+    )
+    qualifier = ctypes.c_int32(pid)
+    object_id = ctypes.c_uint32(_AUDIO_OBJECT_UNKNOWN)
+    size = ctypes.c_uint32(ctypes.sizeof(object_id))
+    status = coreaudio.AudioObjectGetPropertyData(
+        _AUDIO_SYSTEM_OBJECT,
+        ctypes.byref(address),
+        ctypes.sizeof(qualifier),
+        ctypes.byref(qualifier),
+        ctypes.byref(size),
+        ctypes.byref(object_id),
+    )
+    if status != 0:
+        raise OSError(f"CoreAudio PID translation failed with OSStatus {status}")
+    return object_id.value
+
+
+def _sample_teams_audio(process_ids: Sequence[int]) -> bool:
+    """Return whether any Teams process currently has active audio I/O."""
+    coreaudio = _load_coreaudio()
+    for pid in process_ids:
+        object_id = _audio_process_object(coreaudio, pid)
+        if object_id == _AUDIO_OBJECT_UNKNOWN:
+            continue
+        if _audio_property(coreaudio, object_id, _AUDIO_RUNNING_INPUT):
+            return True
+        if _audio_property(coreaudio, object_id, _AUDIO_RUNNING_OUTPUT):
+            return True
+    return False
+
+
+_ACCESSIBILITY_CALL_SCRIPT = r"""
+tell application "System Events"
+    set teamsProcesses to every application process whose name is "Microsoft Teams" ¬
+        or name is "MSTeams"
+    if (count of teamsProcesses) is 0 then return "inactive"
+    repeat with teamsProcess in teamsProcesses
+        set uiItems to entire contents of teamsProcess
+        repeat with uiItem in uiItems
+            try
+                set itemVisible to true
+                try
+                    set itemVisible to value of attribute "AXVisible" of uiItem
+                end try
+                try
+                    if value of attribute "AXHidden" of uiItem then set itemVisible to false
+                end try
+                if itemVisible and role of uiItem is "AXButton" then
+                    set itemText to ""
+                    try
+                        set itemText to itemText & " " & (name of uiItem as text)
+                    end try
+                    try
+                        set itemText to itemText & " " & (description of uiItem as text)
+                    end try
+                    try
+                        set itemText to itemText & " " & ¬
+                            (value of attribute "AXTitle" of uiItem as text)
+                    end try
+                    ignoring case
+                        if itemText contains "leave" or itemText contains "hang up" ¬
+                            or itemText contains "hang-up" then
+                            return "active"
+                        end if
+                    end ignoring
+                end if
+            end try
+        end repeat
+    end repeat
+    return "inactive"
+end tell
+"""
+
+
+def _probe_accessibility_call_ui() -> bool | None:
+    """Inspect Teams' accessibility tree for a Leave/Hang-up button."""
+    try:
+        result = subprocess.run(
+            ["osascript", "-e", _ACCESSIBILITY_CALL_SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    output = result.stdout.strip().lower()
+    if output == "active":
+        return True
+    if output == "inactive":
+        return False
+    return None
+
+
+def detect_call_state() -> CallState:
+    """Detect live Teams calls using persistent audio activity and visible UI."""
+    process_ids = _find_teams_processes()
+    if process_ids is None:
+        return CallState.UNKNOWN
+    if not process_ids:
+        return CallState.INACTIVE
+
+    audio_samples: list[bool] = []
+    try:
+        for sample_index in range(_AUDIO_SAMPLE_COUNT):
+            audio_samples.append(_sample_teams_audio(process_ids))
+            if sample_index + 1 < _AUDIO_SAMPLE_COUNT:
+                time.sleep(_AUDIO_SAMPLE_INTERVAL_SECONDS)
+    except (AttributeError, OSError):
+        return CallState.UNKNOWN
+
+    if all(audio_samples):
+        return CallState.ACTIVE
+
+    ui_active = _probe_accessibility_call_ui()
+    if ui_active is True:
+        return CallState.ACTIVE
+    if ui_active is False:
+        return CallState.INACTIVE
+    return CallState.UNKNOWN
+
+
+def _kill_teams(
+    *,
+    logger: LoggerLike,
+    label: str = "step1",
+    force: bool = False,
+) -> CallState:
+    """Kill Teams only after checking for a possible live call."""
+    call_state = detect_call_state()
+    logger.log(label, f"Teams call state before restart: {call_state.value}")
+    if not force and call_state is not CallState.INACTIVE:
+        raise RestartBlockedError(call_state)
+    subprocess.run(
+        ["pkill", "-f", "Microsoft Teams"],
+        capture_output=True,
+        check=False,
+    )
+    logger.log(label, "Killed existing Teams processes.")
+    return call_state
+
+
+def _launch_teams(
+    port: int,
+    *,
+    logger: LoggerLike,
+    tenant_id: str | None = None,
+) -> None:
+    flags_value = _build_cdp_flags(port)
+    _set_launchctl_env(flags_value, logger=logger)
+    env = os.environ.copy()
+    env[_ENV_VAR] = flags_value
+    command = ["open", "-a", "Microsoft Teams"]
+    if tenant_id:
+        command.append(
+            "msteams://teams.microsoft.com/l/entity/"
+            f"com.microsoft.teamspace.tab.wiki/tab?tenantId={tenant_id}"
+        )
+    subprocess.Popen(command, env=env)
+
+
+def restart_teams_process(
+    port: int,
+    *,
+    logger: LoggerLike,
+    shutdown: ShutdownLike,
+    force: bool = False,
+    tenant_id: str | None = None,
+    label: str = "step1",
+) -> RestartResult:
+    """Guard, kill, relaunch, and verify Teams on ``port``."""
+    call_state = _kill_teams(logger=logger, label=label, force=force)
+    shutdown.interruptible_sleep_sync(3 if tenant_id else 2)
+    _launch_teams(port, logger=logger, tenant_id=tenant_id)
+    logger.log(label, "Waiting for Teams to start...")
+    shutdown.interruptible_sleep_sync(20 if tenant_id else 12)
+    cdp_ready = _is_cdp_ready(port)
+    if cdp_ready:
+        logger.log(label, f"Teams restarted and CDP is ready on port {port}.")
+    else:
+        logger.log(label, f"Teams restarted but CDP did not become ready on port {port}.")
+    return RestartResult(
+        restarted=True,
+        cdp_ready=cdp_ready,
+        port=port,
+        call_state=call_state,
+        forced=force,
+    )
+
+
+def _is_cdp_ready(port: int) -> bool:
+    version = cdp_http_get(port, "/json/version")
+    return isinstance(version, dict) and "Browser" in version
+
+
+def _exit_restart_blocked(
+    error: RestartBlockedError,
+    *,
+    label: str,
+    format_json: bool,
+) -> typing.NoReturn:
+    from teams_transcripts.infrastructure.errors import (
+        ERROR_RESTART_BLOCKED,
+        EXIT_CDP_UNAVAILABLE,
+        exit_error,
+    )
+
+    detail = (
+        "an active Teams call was detected"
+        if error.reason == "active_call"
+        else ("the Teams call state could not be determined")
+    )
+    exit_error(
+        EXIT_CDP_UNAVAILABLE,
+        ERROR_RESTART_BLOCKED,
+        f"Teams restart blocked because {detail}. "
+        "Do not interrupt Teams automatically. Retry with the CLI flag "
+        "--force-restart, or call restart_teams(force=True), only after the user "
+        "explicitly approves interrupting a possible live call.",
+        step=label,
+        format_json=format_json,
+    )
+
+
+def ensure_teams_running(
+    port: int,
+    *,
+    logger: LoggerLike,
+    shutdown: ShutdownLike,
+    format_json: bool = False,
+    force: bool = False,
+) -> RestartResult | None:
+    """Ensure CDP is available, safely restarting Teams when necessary."""
+    version = cdp_http_get(port, "/json/version")
+    if isinstance(version, dict) and "Browser" in version:
+        logger.log("step1", f"CDP already active: {version['Browser']}")
+        return None
+
+    logger.log("step1", "CDP not responding. Checking call state before restarting Teams...")
+    try:
+        return restart_teams_process(
+            port,
+            logger=logger,
+            shutdown=shutdown,
+            force=force,
+        )
+    except RestartBlockedError as error:
+        _exit_restart_blocked(error, label="step1", format_json=format_json)
+
+
+def relaunch_teams_on_tenant(
+    port: int,
+    tenant_id: str,
+    *,
+    logger: LoggerLike,
+    shutdown: ShutdownLike,
+    format_json: bool = False,
+    force: bool = False,
+) -> RestartResult:
+    """Safely relaunch Teams on a specific Azure AD tenant."""
+    logger.log("tenant", "Switching tenant: checking call state before restarting Teams...")
+    try:
+        return restart_teams_process(
+            port,
+            logger=logger,
+            shutdown=shutdown,
+            force=force,
+            tenant_id=tenant_id,
+            label="tenant",
+        )
+    except RestartBlockedError as error:
+        _exit_restart_blocked(error, label="tenant", format_json=format_json)