Skip to content

launch_agent

diapason.desktop.launch_agent

Install Diapason background services as macOS LaunchAgents.

Two services use this: the dictation agent (diapason dictate) and the API server (diapason serve). They differ only in label and arguments, so the plist builder is parameterised rather than duplicated.

A LaunchAgent (not a LaunchDaemon) runs in the user's GUI session at login, which is required: the key tap and the paste both need a logged-in graphical session. The plist is generated from the CURRENT interpreter so it keeps working regardless of where the venv lives.

The unavoidable caveat, made explicit to the caller: TCC permissions (Input Monitoring, Accessibility) attach to the executable, and the agent runs the Python binary directly — NOT Terminal. The grants you gave Terminal do not transfer. The agent's first run requests them for the Python binary; you grant those once, then launchctl kickstart it.

build_plist(*, python, workdir, out_log, err_log, executable=None, label=LABEL, args=None, schedule=None, interval_s=None)

Render the LaunchAgent plist.

When executable is given (the .app bundle's launcher), launchd runs THAT — which is what gives the process a bundle identity, and therefore the ability to hold Microphone permission at all. Falling back to the bare interpreter keeps the agent usable on a machine where the bundle could not be built, at the cost of a mic that macOS will never authorise.

install(*, executable=None, label=LABEL, args=None, log_prefix='dictate', schedule=None, interval_s=None)

Write the plist and bootstrap it into the user's launchd domain.

Logs are truncated here: they accumulate one block per (re)start, and a stale wall of "still missing" lines from an earlier attempt makes the current state impossible to read.

job_pid(label=LABEL)

Le PID que launchd donne à ce job, ou None s'il n'en a pas.

« Chargé » n'est ni « vivant » ni « seul » : is_loaded répond vrai pour un job déclaré mais arrêté. Avec un PID, on peut comparer au détenteur réel d'un port et savoir si le service qu'on croit posséder est bien celui qui sert.

kickstart(label=LABEL)

Force a (re)start now, after permissions are granted.

uninstall(label=LABEL)

Stop the agent and remove its plist. Returns True if a plist existed.