wirenote 0.1.0__py3-none-any.whl

wirenote/detector/graph.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""In-memory mirror of the PipeWire object graph, fed by `pw-dump --monitor`.
+
+Output format (docs/dev/m0-findings.md §2): pretty-printed JSON arrays written
+back to back, each ending with "]" alone at column 0. The first array is the
+full graph; later arrays are update batches. Updates carry the whole object,
+so they replace; a removal is {"id": N, "info": null} with no "type".
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+
+
+class BatchFramer:
+    """Collects pw-dump output lines; feed() returns a batch once one is complete."""
+
+    def __init__(self) -> None:
+        self._buf: list[str] = []
+
+    def feed(self, line: str) -> list[dict] | None:
+        self._buf.append(line)
+        if line.rstrip("\n") != "]":
+            return None
+        try:
+            batch = json.loads("".join(self._buf))
+        except json.JSONDecodeError:
+            return None  # a nested "]" at column 0; keep reading
+        self._buf.clear()
+        return batch
+
+
+def iter_batches(lines: Iterable[str]) -> Iterator[list[dict]]:
+    """Yield each top-level JSON array from pw-dump output, line by line."""
+    framer = BatchFramer()
+    for line in lines:
+        batch = framer.feed(line)
+        if batch is not None:
+            yield batch
+
+
+def is_removal(obj: dict) -> bool:
+    return obj.get("info") is None and "type" not in obj
+
+
+class Graph:
+    """Objects keyed by id. Ids are reused by PipeWire; object.serial is not."""
+
+    def __init__(self) -> None:
+        self.objects: dict[int, dict] = {}
+
+    def apply(self, batch: list[dict]) -> None:
+        for obj in batch:
+            if is_removal(obj):
+                self.objects.pop(obj["id"], None)
+            else:
+                self.objects[obj["id"]] = obj
+
+    def clear(self) -> None:
+        self.objects.clear()
+
+    def props(self, oid: int | None) -> dict:
+        obj = self.objects.get(oid) if oid is not None else None
+        return ((obj or {}).get("info") or {}).get("props") or {}
+
+    def of_type(self, suffix: str) -> Iterator[dict]:
+        for obj in self.objects.values():
+            if obj.get("type", "").endswith(suffix):
+                yield obj
+
+    def nodes(self) -> Iterator[dict]:
+        return self.of_type(":Node")
+
+    def links(self) -> Iterator[dict]:
+        return self.of_type(":Link")
+
+    def default_node(self, key: str = "default.audio.source") -> str | None:
+        """node.name from the "default" Metadata object. Metadata keeps its props
+        at the top level, not under info."""
+        for obj in self.of_type(":Metadata"):
+            if (obj.get("props") or {}).get("metadata.name") != "default":
+                continue
+            for entry in obj.get("metadata") or []:
+                if entry.get("key") == key:
+                    value = entry.get("value")
+                    if isinstance(value, str):
+                        try:
+                            value = json.loads(value)
+                        except json.JSONDecodeError:
+                            return value or None
+                    return (value or {}).get("name") if isinstance(value, dict) else None
+        return None
+
+
+def info(obj: dict | None) -> dict:
+    return (obj or {}).get("info") or {}
+
+
+def props(obj: dict | None) -> dict:
+    return info(obj).get("props") or {}

wirenote/detector/identity.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Which app owns a mic stream (docs/dev/PLAN.md › Identifying the app).
+
+PID rule (docs/dev/m0-findings.md §3): for pulse-protocol clients
+(client.api == "pipewire-pulse") pipewire.sec.pid is the pipewire-pulse
+server, so the self-reported application.process.id is used; for native
+clients pipewire.sec.pid comes from the socket and is used. The chosen PID
+must pass a check: its exe basename or comm equals the reported
+application.process.binary. If it fails (say a Flatpak sandbox PID that
+names an unrelated host process), the PID-derived steps are skipped.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ..config.apps import AppRule, AppRules
+
+PARENT_DEPTH = 5
+COMM_LEN = 15  # the kernel truncates /proc/<pid>/comm to 15 characters
+
+
+class ProcReader(Protocol):
+    def read(self, pid: int) -> dict | None:
+        """exe_basename, comm, cmdline0, flatpak_id, snap_name, unit, ppid; None if gone."""
+
+
+@dataclass(frozen=True)
+class Evidence:
+    pid: int | None = None
+    pid_source: str | None = None
+    pid_ok: bool = False
+    flatpak_id: str | None = None
+    snap_name: str | None = None
+    unit: str | None = None
+    portal_app_id: str | None = None
+    exe: str | None = None
+    cmdline0: str | None = None
+    parents: tuple[str, ...] = ()
+    binary: str | None = None
+    app_name: str | None = None
+
+    def as_dict(self) -> dict:
+        return {k: v for k, v in self.__dict__.items() if v not in (None, ())}
+
+
+@dataclass(frozen=True)
+class Identity:
+    rule: AppRule | None
+    matched_by: str | None
+    evidence: Evidence = field(default_factory=Evidence)
+
+    @property
+    def key(self) -> str | None:
+        return self.rule.key if self.rule else None
+
+
+def gather_evidence(client_props: dict, node_props: dict, proc: ProcReader) -> Evidence:
+    def prop(name):
+        return client_props.get(name) or node_props.get(name)
+
+    binary = prop("application.process.binary")
+    if client_props.get("client.api") == "pipewire-pulse":
+        pid_source = "application.process.id"
+        pid = _as_int(prop("application.process.id"))
+    else:
+        pid_source = "pipewire.sec.pid"
+        pid = _as_int(client_props.get("pipewire.sec.pid"))
+        if pid is None:
+            pid_source = "application.process.id"
+            pid = _as_int(prop("application.process.id"))
+
+    base = dict(
+        pid=pid,
+        pid_source=pid_source if pid is not None else None,
+        portal_app_id=client_props.get("pipewire.access.portal.app_id"),
+        binary=binary,
+        app_name=prop("application.name"),
+    )
+    p = proc.read(pid) if pid is not None else None
+    if not p:
+        return Evidence(**base)
+
+    names = {p.get("exe_basename"), p.get("comm")}
+    pid_ok = binary is None or binary in names or binary[:COMM_LEN] in names
+    if not pid_ok:
+        return Evidence(**base)
+
+    parents = []
+    ppid = p.get("ppid")
+    while ppid and ppid > 1 and len(parents) < PARENT_DEPTH:
+        pp = proc.read(ppid)
+        if not pp:
+            break
+        parents.append(pp.get("exe_basename") or pp.get("comm") or "?")
+        ppid = pp.get("ppid")
+
+    return Evidence(
+        **base,
+        pid_ok=True,
+        flatpak_id=p.get("flatpak_id"),
+        snap_name=p.get("snap_name"),
+        unit=p.get("unit"),
+        exe=p.get("exe_basename"),
+        cmdline0=p.get("cmdline0"),
+        parents=tuple(parents),
+    )
+
+
+def resolve(ev: Evidence, rules: AppRules) -> Identity:
+    """Walk the lookup order and stop at the first exact rule match."""
+    steps: list[tuple[str, str, str | None]] = []
+    if ev.pid_ok:
+        steps += [("cgroup.flatpak", "flatpak", ev.flatpak_id),
+                  ("cgroup.snap", "snap", ev.snap_name)]
+    steps.append(("portal_app_id", "flatpak", ev.portal_app_id))
+    if ev.pid_ok:
+        steps += [("exe", "exe", ev.exe), ("cmdline0", "exe", ev.cmdline0)]
+        steps += [(f"parent{i + 1}", "exe", name) for i, name in enumerate(ev.parents)]
+    steps += [("binary", "binary", ev.binary), ("binary", "exe", ev.binary),
+              ("app_name", "app_name", ev.app_name)]
+    for label, fld, value in steps:
+        rule = rules.lookup(fld, value)
+        if rule:
+            return Identity(rule, label, ev)
+    return Identity(None, None, ev)
+
+
+class LiveProc:
+    """ProcReader over /proc."""
+
+    def read(self, pid: int) -> dict | None:
+        base = f"/proc/{pid}"
+        try:
+            exe = os.readlink(f"{base}/exe").removesuffix(" (deleted)")
+        except OSError:
+            exe = None
+        comm = _read(f"{base}/comm")
+        if comm is None and exe is None:
+            return None
+        cmdline = _read(f"{base}/cmdline") or ""
+        argv = [a for a in cmdline.split("\0") if a]
+        stat = _read(f"{base}/stat") or ""
+        rest = stat.rsplit(")", 1)[-1].split()
+        out = {
+            "exe_basename": os.path.basename(exe) if exe else None,
+            "comm": comm.strip() if comm else None,
+            "cmdline0": cmdline0(argv),
+            "ppid": int(rest[1]) if len(rest) > 1 else None,
+        }
+        out.update(parse_cgroup(_read(f"{base}/cgroup")))
+        return out
+
+
+def cmdline0(argv: list[str]) -> str | None:
+    if not argv:
+        return None
+    # Chrome and Electron rewrite argv into one space-joined string.
+    first = argv[0].split(" ", 1)[0] if len(argv) == 1 else argv[0]
+    return os.path.basename(first)
+
+
+def parse_cgroup(text: str | None) -> dict:
+    out = {"flatpak_id": None, "snap_name": None, "unit": None}
+    path = None
+    for line in (text or "").splitlines():
+        parts = line.split(":", 2)
+        if len(parts) == 3 and (parts[0] == "0" or parts[1] == "name=systemd"):
+            path = parts[2]
+            if parts[0] == "0":
+                break
+    if not path:
+        return out
+    segs = path.split("/")
+    units = [s for s in segs if s.endswith((".scope", ".service"))]
+    out["unit"] = units[-1] if units else None
+    for seg in reversed(segs):
+        m = re.match(r"app-flatpak-(.+)-\d+\.scope$", seg)
+        if m:
+            out["flatpak_id"] = m.group(1)
+            break
+        m = re.match(r"snap\.([^.]+)\.", seg)
+        if m:
+            out["snap_name"] = m.group(1)
+            break
+    return out
+
+
+def _read(path: str) -> str | None:
+    try:
+        with open(path, "rb") as f:
+            return f.read().decode("utf-8", "replace")
+    except OSError:
+        return None
+
+
+def _as_int(v) -> int | None:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None

wirenote/detector/streams.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Turn the graph mirror into the set of running microphone streams.
+
+A mic stream (docs/dev/PLAN.md › What counts as a mic stream): a Stream/Input/Audio
+node in state "running", linked from at least one Audio/Source* node, and not
+owned by this daemon.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .graph import Graph, info, props
+
+CAPTURE_CLASS = "Stream/Input/Audio"
+
+
+@dataclass(frozen=True)
+class MicStream:
+    serial: int                 # object.serial; node ids get reused
+    node_id: int
+    client_serial: int | None   # identity is cached per client
+    media_name: str | None
+    node_props: dict
+    client_props: dict
+    source_names: tuple[str, ...]
+
+
+def mic_streams(graph: Graph, own_pids: set[int], own_prefix: str) -> list[MicStream]:
+    sources_by_node: dict[int, list[str]] = {}
+    for link in graph.links():
+        li = info(link)
+        src = graph.props(li.get("output-node-id"))
+        if src.get("media.class", "").startswith("Audio/Source"):
+            sources_by_node.setdefault(li.get("input-node-id"), []).append(
+                src.get("node.name", "?"))
+
+    out = []
+    for node in graph.nodes():
+        np = props(node)
+        if np.get("media.class") != CAPTURE_CLASS or info(node).get("state") != "running":
+            continue
+        if node["id"] not in sources_by_node:
+            continue  # fed only from a sink monitor, or not linked yet
+        if str(np.get("node.name", "")).startswith(own_prefix):
+            continue
+        cp = graph.props(np.get("client.id"))
+        claimed = {cp.get("application.process.id"), np.get("application.process.id"),
+                   cp.get("pipewire.sec.pid")}
+        if any(_as_int(p) in own_pids for p in claimed):
+            continue
+        out.append(MicStream(
+            serial=np.get("object.serial"),
+            node_id=node["id"],
+            client_serial=cp.get("object.serial"),
+            media_name=np.get("media.name"),
+            node_props=np,
+            client_props=cp,
+            source_names=tuple(sorted(set(sources_by_node[node["id"]]))),
+        ))
+    return out
+
+
+def _as_int(v) -> int | None:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None

wirenote/detector/tracker.py

@@ -0,0 +1,304 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Per-app state machine (docs/dev/PLAN.md › State machine, Mermaid diagram).
+
+Pure: no I/O, no clock of its own. The daemon calls update() after every
+PipeWire batch and on the 1 s reconcile tick with the apps currently on the
+mic; user clicks come in through record(), ignore() and stop(). Every call
+returns a list of actions for the daemon to carry out and log.
+
+Two refinements of the diagram, both to avoid surprising prompts:
+- StopPending stays put while a stop guard (recording < 30 s, app runtime
+  < 20 s) blocks, and re-checks on every update, instead of bouncing back to
+  Recording each tick. It returns to Recording only when the app comes back.
+- Manual Stop and the 4 h cap go to Suppressed, not Idle, so a call that is
+  still running does not prompt again right away.
+Prompted also waits out the grace before withdrawing, so a mic reopen (Chrome
+closes and reopens it at Join, docs/dev/m0-findings.md) does not flash the prompt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ..config.settings import Settings
+
+
+MANUAL_KEY = "manual"
+
+
+class State(StrEnum):
+    IDLE = "idle"
+    CANDIDATE = "candidate"
+    PROMPTED = "prompted"
+    RECORDING = "recording"
+    STOP_PENDING = "stop_pending"
+    SUPPRESSED = "suppressed"
+
+
+@dataclass(frozen=True)
+class Observation:
+    """One app on the mic right now: all of its running mic streams."""
+    key: str
+    name: str
+    kind: str                     # "meeting" or "browser", after title rules
+    streams: frozenset[int]       # object.serial of each running stream
+    service: str | None = None    # e.g. "Jitsi", from a title rule
+    room: str | None = None
+
+
+# Actions -------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Transition:
+    key: str
+    old: State
+    new: State
+    reason: str
+
+
+@dataclass(frozen=True)
+class Note:
+    key: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ShowPrompt:
+    key: str
+    name: str
+    kind: str
+    service: str | None
+    room: str | None
+
+
+@dataclass(frozen=True)
+class WithdrawPrompt:
+    key: str
+
+
+@dataclass(frozen=True)
+class StartRecording:
+    key: str
+    name: str
+
+
+@dataclass(frozen=True)
+class StopRecording:
+    key: str
+    reason: str
+    duration_s: float
+
+
+@dataclass(frozen=True)
+class ShowNudge:
+    key: str
+    name: str
+    dismisses: int
+
+
+Action = Transition | Note | ShowPrompt | WithdrawPrompt | StartRecording | StopRecording | ShowNudge
+
+
+@dataclass
+class AppTrack:
+    key: str
+    state: State = State.IDLE
+    obs: Observation | None = None
+    session_start: float | None = None   # first mic use of this session
+    gone_since: float | None = None      # set while the app is off the mic
+    candidate_since: float | None = None
+    recording_since: float | None = None
+    note: str | None = None              # last Note, so it is emitted once
+    manual: bool = False                 # started with "Record a meeting": no app to leave
+
+
+class Tracker:
+    def __init__(self, settings: Settings, dismisses: dict[str, int] | None = None) -> None:
+        self.s = settings
+        self.apps: dict[str, AppTrack] = {}
+        self.dismisses: dict[str, int] = dict(dismisses or {})
+        self.asleep = False
+
+    # Queries ---------------------------------------------------------------
+
+    @property
+    def recording_key(self) -> str | None:
+        return next((t.key for t in self.apps.values()
+                     if t.state in (State.RECORDING, State.STOP_PENDING)), None)
+
+    def snapshot(self, now: float) -> dict:
+        out = {}
+        for t in self.apps.values():
+            entry = {"state": str(t.state), "name": t.obs.name if t.obs else t.key}
+            if t.session_start is not None:
+                entry["on_mic_for_s"] = round(now - t.session_start, 1)
+            if t.recording_since is not None:
+                entry["recording_for_s"] = round(now - t.recording_since, 1)
+            if t.gone_since is not None:
+                entry["gone_for_s"] = round(now - t.gone_since, 1)
+            out[t.key] = entry
+        return out
+
+    # Inputs ----------------------------------------------------------------
+
+    def update(self, now: float, observations: dict[str, Observation]) -> list[Action]:
+        if self.asleep:
+            return []
+        actions: list[Action] = []
+        for key in sorted(set(self.apps) | set(observations)):
+            t = self.apps.setdefault(key, AppTrack(key))
+            obs = observations.get(key)
+            if obs is not None:
+                t.obs = obs
+                t.gone_since = None
+            elif t.gone_since is None:
+                t.gone_since = now
+            self._step(t, now, obs is not None, actions)
+            if t.state is State.IDLE:
+                del self.apps[key]
+        return actions
+
+    def record(self, key: str, now: float) -> list[Action]:
+        t = self.apps.get(key)
+        if t is None or t.state is not State.PROMPTED:
+            return [Note(key, "record ignored: no prompt showing")]
+        if self.recording_key is not None:
+            return [Note(key, f"record refused: {self.recording_key} is recording")]
+        actions: list[Action] = []
+        t.recording_since = now
+        self._go(t, State.RECORDING, "user clicked Record", actions)
+        actions.append(StartRecording(key, t.obs.name if t.obs else key))
+        return actions
+
+    def start_manual(self, now: float, key: str = MANUAL_KEY,
+                     name: str = "In-person meeting") -> list[Action]:
+        """Record without a call app (docs/dev/features-2-design.md › 2). Only Stop,
+        the 4 h cap and sleep end it."""
+        if self.recording_key is not None:
+            return [Note(key, f"record refused: {self.recording_key} is recording")]
+        actions: list[Action] = []
+        t = self.apps[key] = AppTrack(key, obs=Observation(key, name, "meeting", frozenset()),
+                                      session_start=now, recording_since=now, manual=True)
+        self._go(t, State.RECORDING, "user started a recording", actions)
+        actions.append(StartRecording(key, name))
+        return actions
+
+    def ignore(self, key: str, now: float) -> list[Action]:
+        t = self.apps.get(key)
+        if t is None or t.state is not State.PROMPTED:
+            return [Note(key, "ignore ignored: no prompt showing")]
+        actions: list[Action] = []
+        self._go(t, State.SUPPRESSED, "user ignored the prompt", actions)
+        n = self.dismisses[key] = self.dismisses.get(key, 0) + 1
+        if n == self.s.nudge_after_dismisses:
+            actions.append(ShowNudge(key, t.obs.name if t.obs else key, n))
+        return actions
+
+    def stop(self, now: float, reason: str = "manual stop") -> list[Action]:
+        key = self.recording_key
+        if key is None:
+            return []
+        actions: list[Action] = []
+        self._stop(self.apps[key], now, State.SUPPRESSED, reason, actions)
+        return actions
+
+    def sleep(self, now: float) -> list[Action]:
+        actions: list[Action] = []
+        for t in list(self.apps.values()):
+            if t.state is State.PROMPTED:
+                actions.append(WithdrawPrompt(t.key))
+            if t.state in (State.RECORDING, State.STOP_PENDING):
+                self._stop(t, now, State.IDLE, "system sleep", actions)
+            elif t.state is not State.IDLE:
+                self._go(t, State.IDLE, "system sleep", actions)
+        self.apps.clear()
+        self.asleep = True
+        return actions
+
+    def resume(self, now: float, observations: dict[str, Observation]) -> list[Action]:
+        """Apps already on the mic after wake count as seen: no prompt."""
+        self.asleep = False
+        actions: list[Action] = []
+        for key, obs in sorted(observations.items()):
+            t = self.apps.setdefault(key, AppTrack(key, obs=obs, session_start=now))
+            self._go(t, State.SUPPRESSED, "on the mic at resume", actions)
+        return actions
+
+    # Internals -------------------------------------------------------------
+
+    def _step(self, t: AppTrack, now: float, present: bool, actions: list[Action]) -> None:
+        s = self.s
+        gone_for = now - t.gone_since if t.gone_since is not None else 0.0
+
+        if t.state is State.IDLE:
+            if present:
+                t.session_start = t.candidate_since = now
+                self._go(t, State.CANDIDATE, "app opened the mic", actions)
+
+        elif t.state is State.CANDIDATE:
+            if not present:
+                self._go(t, State.IDLE, "mic closed before dwell", actions)
+                return
+            other = self.recording_key
+            if other is not None:
+                self._note(t, f"prompt held: {other} is recording", actions)
+                return
+            dwell = s.dwell_meeting_s if t.obs.kind == "meeting" else s.dwell_browser_s
+            if now - t.candidate_since >= dwell:
+                self._go(t, State.PROMPTED, f"on the mic for {dwell:g} s", actions)
+                o = t.obs
+                actions.append(ShowPrompt(t.key, o.name, o.kind, o.service, o.room))
+
+        elif t.state is State.PROMPTED:
+            if not present and gone_for >= s.grace_s:
+                self._go(t, State.IDLE, "app left the mic (prompt withdrawn)", actions)
+                actions.append(WithdrawPrompt(t.key))
+
+        elif t.state is State.SUPPRESSED:
+            if not present and gone_for >= max(s.cooldown_s, s.grace_s):
+                self._go(t, State.IDLE, f"stream ended {s.cooldown_s:g} s ago", actions)
+
+        elif t.state is State.RECORDING:
+            if now - t.recording_since >= s.max_recording_s:
+                self._stop(t, now, State.SUPPRESSED, "4 h cap", actions)
+            elif t.manual:
+                pass
+            elif not present and gone_for >= s.grace_s:
+                self._go(t, State.STOP_PENDING, f"app gone > {s.grace_s:g} s", actions)
+                self._check_stop(t, now, actions)
+
+        elif t.state is State.STOP_PENDING:
+            if present:
+                self._go(t, State.RECORDING, "app back on the mic", actions)
+            elif now - t.recording_since >= s.max_recording_s:
+                self._stop(t, now, State.SUPPRESSED, "4 h cap", actions)
+            else:
+                self._check_stop(t, now, actions)
+
+    def _check_stop(self, t: AppTrack, now: float, actions: list[Action]) -> None:
+        s = self.s
+        if now - t.recording_since < s.min_recording_age_s:
+            self._note(t, f"stop held: recording younger than {s.min_recording_age_s:g} s", actions)
+        elif now - t.session_start < s.min_app_runtime_s:
+            self._note(t, f"stop held: app on the mic less than {s.min_app_runtime_s:g} s", actions)
+        else:
+            self._stop(t, now, State.IDLE, "app left the mic", actions)
+
+    def _stop(self, t: AppTrack, now: float, new: State, reason: str,
+              actions: list[Action]) -> None:
+        duration = now - t.recording_since if t.recording_since is not None else 0.0
+        self._go(t, new, reason, actions)
+        actions.append(StopRecording(t.key, reason, round(duration, 1)))
+        t.recording_since = None
+
+    def _go(self, t: AppTrack, new: State, reason: str, actions: list[Action]) -> None:
+        actions.append(Transition(t.key, t.state, new, reason))
+        t.state = new
+        t.note = None
+
+    def _note(self, t: AppTrack, message: str, actions: list[Action]) -> None:
+        if t.note != message:
+            t.note = message
+            actions.append(Note(t.key, message))

wirenote/net/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav