Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

21.0 KB
Raw Blame
"""MacOSScriptDucker: tiered AppleScript duck/restore with a fake runner.

The permission layer is a ``FakePermissionService`` that reads Automation as GRANTED
(the duck/restore logic is the subject here); ``test_ducking_permissions.py`` covers
the permission behaviour against ``FakeTCC``.
"""
from __future__ import annotations

import subprocess
import threading
import time

import pytest

from dodaios.audio.ducking import macos
from dodaios.audio.ducking.macos import _MASTER_TOKEN, MacOSScriptDucker
from dodaios.platform.permissions import PermissionId
from tests.fakes.fake_permission_service import FakePermissionService

_MUSIC = "com.apple.Music"
_SPOTIFY = "com.spotify.client"


class FakeRunner:
    """Records every script; returns scripted results per app / master.

    ``results`` maps a bundle id (or ``"master"``) to a stdout string, a
    ``CompletedProcess``, or an exception instance to raise.
    """

    def __init__(self, results: dict[str, object]):
        self.scripts: list[str] = []
        self._results = results

    def __call__(self, script: str) -> subprocess.CompletedProcess:
        self.scripts.append(script)
        for key, res in self._results.items():
            if key != "master" and key in script:
                return self._result(res)
        if "output volume" in script:
            return self._result(self._results.get("master", "50"))
        raise AssertionError(f"unexpected script: {script}")

    @staticmethod
    def _result(res: object) -> subprocess.CompletedProcess:
        if isinstance(res, BaseException):
            raise res
        if isinstance(res, subprocess.CompletedProcess):
            return res
        return subprocess.CompletedProcess(
            ["osascript"], 0, stdout=f"{res}\n", stderr=""
        )


def _ducker(runner: FakeRunner, **kwargs) -> MacOSScriptDucker:
    kwargs.setdefault("access_gate", FakePermissionService())  # Automation: granted
    return MacOSScriptDucker(run=runner, **kwargs)


def test_ducks_running_players_and_skips_stopped_ones():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})
    d = _ducker(run)
    tokens = d.mute_others(own_pid=123, never=frozenset())
    assert tokens == [1]
    assert d._saved == {1: 65}  # Spotify not running → never tokenized


def test_every_script_carries_the_is_running_guard():
    # Regression pin: a bare tell-application LAUNCHES the app; every player
    # script must guard with "is running" inside the same script.
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "40"})
    d = _ducker(run)
    tokens = d.mute_others(own_pid=123, never=frozenset())
    d.restore(tokens)
    d.prewarm()
    assert run.scripts, "no scripts were run"
    assert all("is running" in s for s in run.scripts)


def test_restore_sets_previous_volume_and_clears_state():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})
    d = _ducker(run)
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    d.restore([1])
    assert any("set sound volume to 65" in s for s in run.scripts)
    assert d._saved == {}


def test_restore_is_idempotent_and_unknown_token_is_noop():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})
    d = _ducker(run)
    d.mute_others(own_pid=1, never=frozenset())
    d.restore([1])
    calls_after_first = len(run.scripts)
    d.restore([1])  # already restored → no further osascript call
    d.restore([42])  # unknown token → no-op
    assert len(run.scripts) == calls_after_first


def test_never_mute_maps_names_case_insensitively_stripping_suffixes():
    for entry in ("Spotify", "spotify", "Spotify.exe", "Spotify.app"):
        run = FakeRunner({_MUSIC: "65", _SPOTIFY: "40"})
        d = _ducker(run)
        tokens = d.mute_others(own_pid=1, never=frozenset({entry}))
        assert tokens == [1], entry
        assert not any(_SPOTIFY in s for s in run.scripts), entry


def test_runner_timeout_skips_player_but_others_still_duck():
    run = FakeRunner(
        {
            _MUSIC: subprocess.TimeoutExpired(cmd="osascript", timeout=3.0),
            _SPOTIFY: "70",
        }
    )
    d = _ducker(run)
    tokens = d.mute_others(own_pid=1, never=frozenset())
    assert tokens == [2]
    assert d._saved == {2: 70}


def test_nonzero_returncode_skips_player_but_others_still_duck():
    # rc=1 covers the Automation TCC denial (-1743) shape as well.
    denied = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    run = FakeRunner({_MUSIC: denied, _SPOTIFY: "70"})
    d = _ducker(run)
    assert d.mute_others(own_pid=1, never=frozenset()) == [2]


def test_master_fallback_off_and_no_players_ducks_nothing():
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-"})
    d = _ducker(run, master_fallback=False)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert not any("output volume" in s for s in run.scripts)


def test_master_fallback_on_and_no_players_ducks_master_and_restores():
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True)
    tokens = d.mute_others(own_pid=1, never=frozenset())
    assert tokens == [_MASTER_TOKEN]
    assert d._saved == {_MASTER_TOKEN: 80}
    assert any("set volume output volume" in s for s in run.scripts)
    d.restore(tokens)
    assert any("set volume output volume 80" in s for s in run.scripts)
    assert d._saved == {}


def test_master_fallback_untouched_when_a_player_was_ducked():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    assert not any("output volume" in s for s in run.scripts)


def test_already_quiet_player_is_not_tokenized():
    run = FakeRunner({_MUSIC: "0", _SPOTIFY: "-"})
    d = _ducker(run, duck_volume_percent=0)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert d._saved == {}


def test_master_fallback_skipped_when_a_running_player_is_already_quiet():
    """"Nothing was ducked" is not "no player is running".

    Music running at volume 0 needs no duck, so the tier is already handled.
    Falling through to the MASTER output there lowered Jarvis's own TTS — the
    side effect the fallback is opt-in to avoid — and silenced the answer the
    user was waiting for, for no gain.
    """
    run = FakeRunner({_MUSIC: "0", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True, duck_volume_percent=0)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert not any("output volume" in s for s in run.scripts)
    assert d._saved == {}


def test_unrestored_player_is_re_adopted_by_the_next_session():
    """A duck whose restore never landed must not strand the user's volume.

    The player then sits AT the duck volume with our saved level still in
    ``_saved``: every later duck reads that already-ducked volume, so
    ``prev > duck`` stays false and the token is never reported again — the
    music stays silent for good. The next session has to re-adopt it.
    """
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})
    d = _ducker(run)
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]

    # Session 1 ends, but the restore osascript times out -> saved level stays.
    run._results[_MUSIC] = subprocess.TimeoutExpired(cmd="osascript", timeout=3.0)
    d.restore([1])
    assert d._saved == {1: 65}

    # Session 2: Music still reads 0 (ducked). It must come back as a token.
    run._results[_MUSIC] = "0"
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    d.restore([1])
    assert any("set sound volume to 65" in s for s in run.scripts)
    assert d._saved == {}


def test_re_adoption_needs_a_saved_level_not_just_a_quiet_player():
    """A player the USER turned down must never be claimed as ours."""
    run = FakeRunner({_MUSIC: "0", _SPOTIFY: "-"})
    d = _ducker(run)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert d._saved == {}


def test_unrestored_master_is_re_adopted_by_the_next_session():
    """The stranded-restore shape exists for the MASTER output too.

    A master duck whose restore never landed leaves the WHOLE Mac output at
    the duck volume with our saved level still in ``_saved``; the next duck
    reads that already-ducked volume, ``prev > duck`` stays false, and without
    re-adoption no session ever restores it — the Mac stays quiet for good.
    """
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset()) == [_MASTER_TOKEN]

    # Session 1 ends, but the master restore osascript times out.
    def _raise(_script: str):
        raise subprocess.TimeoutExpired(cmd="osascript", timeout=3.0)

    original = d._run
    d._run = _raise
    d.restore([_MASTER_TOKEN])
    d._run = original
    assert d._saved == {_MASTER_TOKEN: 80}

    # Session 2: the master still reads the duck volume (0). It must come
    # back as a token so THIS session's restore can finally land.
    run._results["master"] = "0"
    assert d.mute_others(own_pid=1, never=frozenset()) == [_MASTER_TOKEN]
    run._results["master"] = "80"
    d.restore([_MASTER_TOKEN])
    assert any("set volume output volume 80" in s for s in run.scripts)
    assert d._saved == {}


def test_master_re_adoption_needs_a_saved_level_not_just_a_quiet_master():
    """An output volume the USER turned down must never be claimed as ours."""
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-", "master": "0"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert d._saved == {}


def test_master_fallback_withheld_while_a_never_muted_player_is_running():
    """never_mute must beat the master fallback.

    The master output carries the protected player's audio too: with Spotify
    on the never list and running, ducking the master would silence exactly
    the app the user told us to leave alone.
    """
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "40", "master": "80"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset({"Spotify"})) == []
    assert not any("output volume" in s for s in run.scripts)
    assert d._saved == {}


def test_master_fallback_available_when_the_never_muted_player_is_not_running():
    """A merely-LISTED player must not disable the fallback for good."""
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset({"Spotify"})) == [_MASTER_TOKEN]
    assert d._saved == {_MASTER_TOKEN: 80}


def test_denied_restore_keeps_the_saved_level_for_re_adoption():
    """rc != 0 (a dismissed Automation prompt, -1743) is a restore that never
    landed — popping the saved level there stranded the duck for good, because
    re-adoption keys on exactly that saved level."""
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})
    d = _ducker(run)
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]

    run._results[_MUSIC] = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    d.restore([1])
    assert d._saved == {1: 65}

    # The user granted the prompt: the next session re-adopts and restores.
    run._results[_MUSIC] = "0"
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    d.restore([1])
    assert any("set sound volume to 65" in s for s in run.scripts)
    assert d._saved == {}


def test_denied_master_restore_keeps_the_saved_level():
    """The same rc != 0 shape must keep the MASTER level re-adoptable."""
    run = FakeRunner({_MUSIC: "-", _SPOTIFY: "-", "master": "80"})
    d = _ducker(run, master_fallback=True)
    assert d.mute_others(own_pid=1, never=frozenset()) == [_MASTER_TOKEN]

    run._results["master"] = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="execution error (-1743)"
    )
    d.restore([_MASTER_TOKEN])
    assert d._saved == {_MASTER_TOKEN: 80}


# --------------------------------------------------------------------------- #
# Permission gating (FakePermissionService)                                    #
# --------------------------------------------------------------------------- #


def _music_scripts(run: FakeRunner) -> list[str]:
    return [s for s in run.scripts if _MUSIC in s]


def _music_scripts_with_a_send(run: FakeRunner) -> list[str]:
    return [s for s in _music_scripts(run) if "tell application" in s]


def test_a_player_without_a_live_grant_is_never_scripted_and_never_asked():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "40"})
    gate = FakePermissionService({PermissionId.AUTOMATION: "pending"})
    d = _ducker(run, access_gate=gate)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert d._saved == {}
    # Only the pure running-state query ever reaches a player that was not granted.
    assert all("tell application" not in s for s in run.scripts)
    # The service was only READ, or told non-interactively: nothing could have asked.
    assert gate.native_free()
    assert {c.target for c in gate.check_calls()} == {_MUSIC, _SPOTIFY}


def test_a_miss_is_recorded_through_a_non_interactive_ensure_only_for_a_running_player():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-"})  # Spotify is not running
    gate = FakePermissionService({PermissionId.AUTOMATION: "pending"})
    d = _ducker(run, access_gate=gate)
    d.mute_others(own_pid=1, never=frozenset())
    calls = gate.ensure_calls(PermissionId.AUTOMATION)
    assert [(c.target, c.interactive, c.feature) for c in calls] == [
        (_MUSIC, False, "audio_ducking")
    ]


def test_a_player_the_service_calls_not_required_is_left_alone():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "40"})
    gate = FakePermissionService({PermissionId.AUTOMATION: "not_required"})
    d = _ducker(run, access_gate=gate)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert run.scripts == []  # not installed (or not macOS): not even a probe
    assert gate.ensure_calls() == []


def test_master_fallback_still_applies_when_a_running_player_has_no_grant():
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "-", "master": "80"})
    gate = FakePermissionService({PermissionId.AUTOMATION: "denied"})
    d = _ducker(run, master_fallback=True, access_gate=gate)
    assert d.mute_others(own_pid=1, never=frozenset()) == [_MASTER_TOKEN]
    assert not _music_scripts_with_a_send(run)


def test_minus_1743_after_a_granted_read_skips_the_player_and_drops_the_cache():
    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )

    class Gate(FakePermissionService):
        invalidated: list[object]

        def invalidate(self, permission=None):
            self.invalidated.append(permission)

    gate = Gate()
    gate.invalidated = []
    run = FakeRunner({_MUSIC: refused, _SPOTIFY: "70"})
    d = _ducker(run, access_gate=gate)
    assert d.mute_others(own_pid=1, never=frozenset()) == [2]  # Spotify still ducks
    assert gate.invalidated == [PermissionId.AUTOMATION]
    # The service is told ONCE, through the failed-use report: a background episode that
    # names the player, never an ask (and no longer a non-interactive ensure).
    (report,) = gate.report_calls("report_failed_use")
    assert (report.permission, report.feature, report.target) == (
        PermissionId.AUTOMATION,
        "audio_ducking",
        _MUSIC,
    )
    assert (report.reason, report.origin, report.interactive) == (
        "needs_settings",
        "background",
        False,
    )
    assert gate.ensure_calls(PermissionId.AUTOMATION) == [] and gate.native_free()


def test_a_send_that_lands_after_a_refusal_reports_the_success_once():
    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    gate = FakePermissionService()
    run = FakeRunner({_MUSIC: refused, _SPOTIFY: "-"})
    d = _ducker(run, access_gate=gate)
    assert d.mute_others(own_pid=1, never=frozenset()) == []
    assert gate.report_calls("report_use_ok") == []  # nothing landed yet

    run._results[_MUSIC] = "65"  # fixed in System Settings: the next duck lands
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    (ok,) = gate.report_calls("report_use_ok")
    assert (ok.permission, ok.feature, ok.target) == (
        PermissionId.AUTOMATION,
        "audio_ducking",
        _MUSIC,
    )
    d.restore([1])
    assert d.mute_others(own_pid=1, never=frozenset()) == [1]
    assert len(gate.report_calls("report_use_ok")) == 1  # a healthy session never reports again
    assert gate.native_free()


def test_a_healthy_session_never_calls_the_failed_use_reports():
    gate = FakePermissionService()
    run = FakeRunner({_MUSIC: "65", _SPOTIFY: "40"})
    d = _ducker(run, access_gate=gate)
    tokens = d.mute_others(own_pid=1, never=frozenset())
    d.restore(tokens)
    assert d.mute_others(own_pid=1, never=frozenset()) == [1, 2]
    assert gate.report_calls() == []


def test_a_player_that_is_not_running_is_no_evidence_that_a_send_landed():
    """The ``is running`` guard answers ``-`` before any Apple event is sent."""
    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    gate = FakePermissionService()
    run = FakeRunner({_MUSIC: refused, _SPOTIFY: "-"})
    d = _ducker(run, access_gate=gate)
    d.mute_others(own_pid=1, never=frozenset())

    run._results[_MUSIC] = "-"  # Music quit: nothing was sent, so nothing was proven
    d.mute_others(own_pid=1, never=frozenset())

    assert gate.report_calls("report_use_ok") == []


def test_a_gate_without_the_report_calls_still_gets_the_older_background_episode():
    """A scripted stub has no ``report_failed_use``: the miss goes through a plain ensure."""
    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    inner = FakePermissionService()

    class BareGate:
        def check(self, permission, *, target=None):
            return inner.check(permission, target=target)

        def ensure(self, permission, **kwargs):
            return inner.ensure(permission, **kwargs)

    run = FakeRunner({_MUSIC: refused, _SPOTIFY: "70"})
    d = _ducker(run, access_gate=BareGate())
    assert d.mute_others(own_pid=1, never=frozenset()) == [2]
    assert [c.interactive for c in inner.ensure_calls(PermissionId.AUTOMATION)] == [False]

    run._results[_MUSIC] = "65"  # and a landed send is simply not reported
    assert d.mute_others(own_pid=1, never=frozenset()) == [1, 2]


def test_a_report_that_hangs_never_stalls_the_session_and_the_other_player_still_ducks(
    monkeypatch,
):
    release = threading.Event()
    entered = threading.Event()

    class HungReportGate(FakePermissionService):
        def report_failed_use(self, permission, **kwargs):
            entered.set()
            release.wait(10)
            return super().report_failed_use(permission, **kwargs)

    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    monkeypatch.setattr(macos, "_PROBE_TIMEOUT_S", 0.05)
    d = _ducker(FakeRunner({_MUSIC: refused, _SPOTIFY: "70"}), access_gate=HungReportGate())
    started = time.monotonic()
    try:
        assert d.mute_others(own_pid=1, never=frozenset()) == [2]
        assert entered.is_set()  # the report really was out
    finally:
        release.set()
    assert time.monotonic() - started < 2.0


def test_a_report_that_raises_is_logged_and_never_breaks_the_session(caplog):
    """AP-30: the failure is contained, the session carries on, and it leaves a trace."""

    class BrokenGate(FakePermissionService):
        def report_failed_use(self, permission, **kwargs):
            raise RuntimeError("the permission service is broken")

    refused = subprocess.CompletedProcess(
        ["osascript"], 1, stdout="", stderr="Not authorized to send Apple events (-1743)"
    )
    d = _ducker(FakeRunner({_MUSIC: refused, _SPOTIFY: "70"}), access_gate=BrokenGate())
    with caplog.at_level("DEBUG", logger="dodaios.audio.ducking"):
        assert d.mute_others(own_pid=1, never=frozenset()) == [2]
    messages = [record.getMessage() for record in caplog.records]
    assert any("bounded" in m and "failed" in m for m in messages)
    assert any("was not delivered to the permission service" in m for m in messages)


def test_prewarm_asks_through_the_gate_for_running_players_only():
    run = FakeRunner({_MUSIC: "+", _SPOTIFY: "-"})
    gate = FakePermissionService({PermissionId.AUTOMATION: "granted"})
    report = _ducker(run, access_gate=gate).prewarm()
    calls = gate.ensure_calls(PermissionId.AUTOMATION)
    # The ask runs on a worker thread, so it waits for the dialog (budget minus a margin).
    (call,) = calls
    assert (call.target, call.interactive) == (_MUSIC, True)
    assert call.wait_s == pytest.approx(macos._ASK_BUDGET_S - macos._ASK_WAIT_MARGIN_S)
    assert [p.player for p in report.players] == ["Music"]
    assert report.not_running == ("Spotify",)
    assert all("is running" in s and "tell application" not in s for s in run.scripts)