sessionvoice 0.3.2__tar.gz → 0.3.3__tar.gz

{sessionvoice-0.3.2 → sessionvoice-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessionvoice
-Version: 0.3.2
+Version: 0.3.3
 Summary: One listening engine for coding agents and the Delta bot: Apple / Nemotron / whisper -> one event stream -> VAD -> turns
 Author-email: Mike Bailey <mike@sessionkit.ai>
 License-Expression: AGPL-3.0-or-later
@@ -92,9 +92,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Capture** (`src/ears/listen`): `ears.listen capture` reads one input
   device and writes every partial, turn and heartbeat to the **heard log**
   (`src/ears/heard.py`):
-  `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<home>` is
-  `~/.voicemode` on a host that already keeps it there, else
-  `~/.sessionvoice` ([docs/logs.md](docs/logs.md#sessionvoices-home)).
+  `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<root>` is the
+  state root: `~/.sessionkit/voice/state` on a new host, or the old
+  `~/.sessionvoice` or `~/.voicemode` on a host that already keeps its heard
+  log there ([docs/logs.md](docs/logs.md#the-state-root)).
+  `ears home state-dir` prints it.
   On a fresh host that also runs VoiceMode's `converse` as a heard guest,
   set `SESSIONVOICE_HOME=~/.voicemode` (or `VOICEMODE_BASE_DIR`), so that
   both write one log.
@@ -128,9 +130,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Sounds** (`keeper/ears-sounds.py`, launchd `dev.sessionkit.voice.ears-sounds`):
   a short sound in the user's ears when the ears log an event, so they know
   they were heard. Its partner, `keeper/mouth-sounds.py`
-  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. Opt-in:
-  `ears services install --only sounds` loads both, from an installed
-  package or a checkout; a bare install never does.
+  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. A bare
+  `ears services install` loads both, from an installed package or a
+  checkout. From the first turn the ears' turn and partial ticks are on
+  (Settings turns them off), and so are the mouth's five cues
+  (`mouth-sounds.json` in the settings folder turns each off).
 - **Turn mail** (`keeper/ears-mail.py`, launchd `dev.sessionkit.voice.ears-mail`):
   mails each of the user's finished turns To and From
   `heard+room@<host>`, whatever input device the capture is following, with
@@ -159,6 +163,12 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   label is dropped: the remaining words get `--speaker` (else
   `unknown@<host>`), never the seat whose echo was cut, and they can be a
   reply to that seat. A label naming anyone else is kept.
+  `Ears-Addressed` lists the seats a turn names, as `<seat>@<host>`, wherever
+  the name falls in the turn, plus `everyone` for "hey everyone":
+  `Ears-Addressed: everyone, ivy@<host>`. A seat is named by its `names` in
+  the wake file. The header carries names only, never the turn's words, and a
+  turn that names nobody has no `Ears-Addressed`. It goes on the room mail
+  only. [docs/ears.md](docs/ears.md) gives the rules.
   `Ears-Echo` says a mouth line heard back through the mic was cut out of
   the turn. On the speakers the mic hears the mouth, so a line's
   words are cut wherever they sit in the user's turn: at its start (up to `3 + 5
@@ -187,6 +197,25 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   have opened within 2 s of the line beginning, unless the turn is mostly
   the line. On the `ts − (t1 − t0)` estimate, only the first two guards
   apply. Numerals (`9%` for "nine percent") still slip past the word match.
+  `Ears-Said` names each session's own line the turn came after, so the
+  pager can keep that session's window open (its linger):
+  `Ears-Said: <session>@<host>=<end>, ...`. `<session>` is the full session
+  id on the line's `said` row, `<host>` the keeper's, and `<end>` that
+  row's `ts`, as it was written. Each session gets one entry: its newest line
+  that finished at or before the turn's `Ears-Start`, within 600 s. It
+  carries spoken lines only: a line on `lane: file` (a music bed or a sound
+  file) is left out, so a bed that ends after a line leaves that line the
+  session's newest. A line with `interest: zero`, or one cut before it
+  played a word (`played_s` 0), is left out. A line the user barged into after part of it played counts,
+  at its cut. Entries are sorted, and the header holds names and times,
+  never a line's words. It goes on the device mail and the `--to seats`
+  mail, never on a cut notice or a call turn; with no entry there is no
+  header.
+  `Ears-Film: playing` marks a turn the keeper heard while a film was
+  playing (`--kodi`: the state that holds `reply` and `light`), so the
+  pager can tell film dialogue from the user. It is a fact about the turn,
+  with one value, on the device mail only; with no film playing, or no
+  `--kodi`, there is no header. Kodi is asked at most once per turn.
 - **Waiter** (`bin/heard-first`): an agent blocks on the heard log
   until a line is for it, by `--rule`: its name in a partial or a
   turn (`partial:REGEX`, `turn:REGEX`), a reply to its last line
@@ -229,10 +258,11 @@ Three JSON settings files, each reread with no restart:
   read only their own file.
 
 Environment variables win over single keys (`EARS_RECORD` over `record`,
-`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the home that holds
-the heard log and each part's state; by default it is `~/.sessionvoice`, or
-`~/.voicemode` on a host that already keeps its heard log there. The launch
-agents are in `~/Library/LaunchAgents/`.
+`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the state root,
+which holds the heard log and each part's state; by default it is
+`~/.sessionkit/voice/state`, or the old `~/.sessionvoice` or `~/.voicemode` on
+a host that already keeps its heard log there. The launch agents are in
+`~/Library/LaunchAgents/`.
 
 Which files and which variables each part reads, and where each one lives:
 [docs/configuration.md](docs/configuration.md).
@@ -241,9 +271,9 @@ Every key, its type and its default:
 
 ## Logs
 
-- **The heard log:** `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
+- **The heard log:** `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
   one JSON line for each thing the ears heard and the mouth said, where
-  `<home>` is the home above. A new file starts each day.
+  `<root>` is the state root above (`ears home state-dir` prints it). A new file starts each day.
 - **The services' logs:** `~/.sessionkit/voice/log/` (`EARS_LOG_DIR` moves it).
   `ears-keeper.log` is what the keeper did (devices, restarts, calls, a
   deaf mic); `ears-keeper-capture.log` is the room capture's own output;
@@ -253,7 +283,7 @@ Every key, its type and its default:
 
 Follow one with `tail -F`, for example
 `tail -F ~/.sessionkit/voice/log/ears-keeper.log`, or today's heard log with
-`tail -F <home>/logs/conversations/heard_$(date +%F).jsonl`.
+`tail -F "$(ears home state-dir)/logs/conversations/heard_$(date +%F).jsonl"`.
 Every log file and what each line means:
 [docs/logs.md](docs/logs.md).
 
@@ -302,7 +332,8 @@ conversation either. On the host, run `talk pair` in a terminal and open the
 link it prints; `talk token --rotate` makes every browser pair again. Open talk
 at `http://127.0.0.1:<port>/`, never at `localhost`. The code is `src/talk/`.
 `ears services install --only talk` keeps it running as a launch agent
-(opt-in; a bare install never does).
+(opt-in; a bare install never does); add `--allow-host
+machine.example.ts.net` for a phone behind `tailscale serve`.
 
 In the kit's web page, Talk is a room: the kit's front door runs
 `talk serve --kit` on a unix socket and logs you in, so there is nothing to
@@ -321,8 +352,7 @@ import that needs one fails naming it, as `pip install 'sessionvoice[EXTRA]'`.
 
     uv venv && uv pip install -e '.[all]'  # onnxruntime + mlx-audio
     ears install
-    ears services install --agent NAME     # the launch agents: mouth, keeper, mail
-    ears services install --only sounds    # opt-in: the ears and mouth sounds
+    ears services install --agent NAME     # the launch agents: mouth, keeper, mail, sounds
     ears services install --only talk      # opt-in: talk serve, the live view
 
 A phone-only Mac (for example one that runs a Delta bot, with no agent
@@ -395,11 +425,12 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   postfix and makes the `heard` box with `message setup --box heard`
   (which also makes sessionmail's mail root, your own box and its notmuch
   profile, if they are missing, and prints each one). On a host that
-  sends by postfix, it makes the `heard` box NESTED under the store dir
-  that carries `.tm-store`, as `~/.mail/agents/<store>/heard/`, when there
-  is exactly one such dir, then runs `vmailbox-gen` if that is on `PATH`,
-  and otherwise prints the commands (`~/.mail/.postfix/vmailbox-gen`:
-  sessionmail keeps it off `PATH`). When sessionmail's answer cannot be
+  sends by postfix, it makes the `heard` box NESTED under the store box
+  (`message box list` names it; `message path <store>` is its folder), as
+  `<store>/heard/`, when there is exactly one, then runs this host's
+  `vmailbox-gen` as sessionmail names it (`message path --generator`), and
+  otherwise prints the commands. sessionvoice never spells the mail root:
+  every box is sessionmail's answer. When sessionmail's answer cannot be
   read (no `message`, or one older than 0.2.0), it warns, makes no box,
   checks neither, and goes on.
   On a postfix host it also prints the box to subscribe to:
@@ -413,7 +444,9 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   `ears services install --agent NAME` for a Mac where an agent seat should
   be woken when you speak, and `ears services install --no-agent` for a
   phone-only Mac (for example a Delta bot), where nobody is woken and the
-  notices go to the log; then `ears wake add NAME`, to add a seat later. Inside
+  notices go to the log; then `ears wake add NAME`, to add a seat later, or
+  `ears wake add --self` in the seat's agent file, to register it at every
+  launch ([docs/ears.md](docs/ears.md#wake-seats)). Inside
   an agent seat (`TM_AGENT_ADDRESS` set) it suggests that address's local
   part as NAME; it never installs on the suggestion. `--no-agent` installs
   anyway, and install warns that NOBODY is woken. A wake file that already

{sessionvoice-0.3.2 → sessionvoice-0.3.3}/README.md

@@ -48,9 +48,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Capture** (`src/ears/listen`): `ears.listen capture` reads one input
   device and writes every partial, turn and heartbeat to the **heard log**
   (`src/ears/heard.py`):
-  `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<home>` is
-  `~/.voicemode` on a host that already keeps it there, else
-  `~/.sessionvoice` ([docs/logs.md](docs/logs.md#sessionvoices-home)).
+  `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<root>` is the
+  state root: `~/.sessionkit/voice/state` on a new host, or the old
+  `~/.sessionvoice` or `~/.voicemode` on a host that already keeps its heard
+  log there ([docs/logs.md](docs/logs.md#the-state-root)).
+  `ears home state-dir` prints it.
   On a fresh host that also runs VoiceMode's `converse` as a heard guest,
   set `SESSIONVOICE_HOME=~/.voicemode` (or `VOICEMODE_BASE_DIR`), so that
   both write one log.
@@ -84,9 +86,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Sounds** (`keeper/ears-sounds.py`, launchd `dev.sessionkit.voice.ears-sounds`):
   a short sound in the user's ears when the ears log an event, so they know
   they were heard. Its partner, `keeper/mouth-sounds.py`
-  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. Opt-in:
-  `ears services install --only sounds` loads both, from an installed
-  package or a checkout; a bare install never does.
+  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. A bare
+  `ears services install` loads both, from an installed package or a
+  checkout. From the first turn the ears' turn and partial ticks are on
+  (Settings turns them off), and so are the mouth's five cues
+  (`mouth-sounds.json` in the settings folder turns each off).
 - **Turn mail** (`keeper/ears-mail.py`, launchd `dev.sessionkit.voice.ears-mail`):
   mails each of the user's finished turns To and From
   `heard+room@<host>`, whatever input device the capture is following, with
@@ -115,6 +119,12 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   label is dropped: the remaining words get `--speaker` (else
   `unknown@<host>`), never the seat whose echo was cut, and they can be a
   reply to that seat. A label naming anyone else is kept.
+  `Ears-Addressed` lists the seats a turn names, as `<seat>@<host>`, wherever
+  the name falls in the turn, plus `everyone` for "hey everyone":
+  `Ears-Addressed: everyone, ivy@<host>`. A seat is named by its `names` in
+  the wake file. The header carries names only, never the turn's words, and a
+  turn that names nobody has no `Ears-Addressed`. It goes on the room mail
+  only. [docs/ears.md](docs/ears.md) gives the rules.
   `Ears-Echo` says a mouth line heard back through the mic was cut out of
   the turn. On the speakers the mic hears the mouth, so a line's
   words are cut wherever they sit in the user's turn: at its start (up to `3 + 5
@@ -143,6 +153,25 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   have opened within 2 s of the line beginning, unless the turn is mostly
   the line. On the `ts − (t1 − t0)` estimate, only the first two guards
   apply. Numerals (`9%` for "nine percent") still slip past the word match.
+  `Ears-Said` names each session's own line the turn came after, so the
+  pager can keep that session's window open (its linger):
+  `Ears-Said: <session>@<host>=<end>, ...`. `<session>` is the full session
+  id on the line's `said` row, `<host>` the keeper's, and `<end>` that
+  row's `ts`, as it was written. Each session gets one entry: its newest line
+  that finished at or before the turn's `Ears-Start`, within 600 s. It
+  carries spoken lines only: a line on `lane: file` (a music bed or a sound
+  file) is left out, so a bed that ends after a line leaves that line the
+  session's newest. A line with `interest: zero`, or one cut before it
+  played a word (`played_s` 0), is left out. A line the user barged into after part of it played counts,
+  at its cut. Entries are sorted, and the header holds names and times,
+  never a line's words. It goes on the device mail and the `--to seats`
+  mail, never on a cut notice or a call turn; with no entry there is no
+  header.
+  `Ears-Film: playing` marks a turn the keeper heard while a film was
+  playing (`--kodi`: the state that holds `reply` and `light`), so the
+  pager can tell film dialogue from the user. It is a fact about the turn,
+  with one value, on the device mail only; with no film playing, or no
+  `--kodi`, there is no header. Kodi is asked at most once per turn.
 - **Waiter** (`bin/heard-first`): an agent blocks on the heard log
   until a line is for it, by `--rule`: its name in a partial or a
   turn (`partial:REGEX`, `turn:REGEX`), a reply to its last line
@@ -185,10 +214,11 @@ Three JSON settings files, each reread with no restart:
   read only their own file.
 
 Environment variables win over single keys (`EARS_RECORD` over `record`,
-`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the home that holds
-the heard log and each part's state; by default it is `~/.sessionvoice`, or
-`~/.voicemode` on a host that already keeps its heard log there. The launch
-agents are in `~/Library/LaunchAgents/`.
+`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the state root,
+which holds the heard log and each part's state; by default it is
+`~/.sessionkit/voice/state`, or the old `~/.sessionvoice` or `~/.voicemode` on
+a host that already keeps its heard log there. The launch agents are in
+`~/Library/LaunchAgents/`.
 
 Which files and which variables each part reads, and where each one lives:
 [docs/configuration.md](docs/configuration.md).
@@ -197,9 +227,9 @@ Every key, its type and its default:
 
 ## Logs
 
-- **The heard log:** `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
+- **The heard log:** `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
   one JSON line for each thing the ears heard and the mouth said, where
-  `<home>` is the home above. A new file starts each day.
+  `<root>` is the state root above (`ears home state-dir` prints it). A new file starts each day.
 - **The services' logs:** `~/.sessionkit/voice/log/` (`EARS_LOG_DIR` moves it).
   `ears-keeper.log` is what the keeper did (devices, restarts, calls, a
   deaf mic); `ears-keeper-capture.log` is the room capture's own output;
@@ -209,7 +239,7 @@ Every key, its type and its default:
 
 Follow one with `tail -F`, for example
 `tail -F ~/.sessionkit/voice/log/ears-keeper.log`, or today's heard log with
-`tail -F <home>/logs/conversations/heard_$(date +%F).jsonl`.
+`tail -F "$(ears home state-dir)/logs/conversations/heard_$(date +%F).jsonl"`.
 Every log file and what each line means:
 [docs/logs.md](docs/logs.md).
 
@@ -258,7 +288,8 @@ conversation either. On the host, run `talk pair` in a terminal and open the
 link it prints; `talk token --rotate` makes every browser pair again. Open talk
 at `http://127.0.0.1:<port>/`, never at `localhost`. The code is `src/talk/`.
 `ears services install --only talk` keeps it running as a launch agent
-(opt-in; a bare install never does).
+(opt-in; a bare install never does); add `--allow-host
+machine.example.ts.net` for a phone behind `tailscale serve`.
 
 In the kit's web page, Talk is a room: the kit's front door runs
 `talk serve --kit` on a unix socket and logs you in, so there is nothing to
@@ -277,8 +308,7 @@ import that needs one fails naming it, as `pip install 'sessionvoice[EXTRA]'`.
 
     uv venv && uv pip install -e '.[all]'  # onnxruntime + mlx-audio
     ears install
-    ears services install --agent NAME     # the launch agents: mouth, keeper, mail
-    ears services install --only sounds    # opt-in: the ears and mouth sounds
+    ears services install --agent NAME     # the launch agents: mouth, keeper, mail, sounds
     ears services install --only talk      # opt-in: talk serve, the live view
 
 A phone-only Mac (for example one that runs a Delta bot, with no agent
@@ -351,11 +381,12 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   postfix and makes the `heard` box with `message setup --box heard`
   (which also makes sessionmail's mail root, your own box and its notmuch
   profile, if they are missing, and prints each one). On a host that
-  sends by postfix, it makes the `heard` box NESTED under the store dir
-  that carries `.tm-store`, as `~/.mail/agents/<store>/heard/`, when there
-  is exactly one such dir, then runs `vmailbox-gen` if that is on `PATH`,
-  and otherwise prints the commands (`~/.mail/.postfix/vmailbox-gen`:
-  sessionmail keeps it off `PATH`). When sessionmail's answer cannot be
+  sends by postfix, it makes the `heard` box NESTED under the store box
+  (`message box list` names it; `message path <store>` is its folder), as
+  `<store>/heard/`, when there is exactly one, then runs this host's
+  `vmailbox-gen` as sessionmail names it (`message path --generator`), and
+  otherwise prints the commands. sessionvoice never spells the mail root:
+  every box is sessionmail's answer. When sessionmail's answer cannot be
   read (no `message`, or one older than 0.2.0), it warns, makes no box,
   checks neither, and goes on.
   On a postfix host it also prints the box to subscribe to:
@@ -369,7 +400,9 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   `ears services install --agent NAME` for a Mac where an agent seat should
   be woken when you speak, and `ears services install --no-agent` for a
   phone-only Mac (for example a Delta bot), where nobody is woken and the
-  notices go to the log; then `ears wake add NAME`, to add a seat later. Inside
+  notices go to the log; then `ears wake add NAME`, to add a seat later, or
+  `ears wake add --self` in the seat's agent file, to register it at every
+  launch ([docs/ears.md](docs/ears.md#wake-seats)). Inside
   an agent seat (`TM_AGENT_ADDRESS` set) it suggests that address's local
   part as NAME; it never installs on the suggestion. `--no-agent` installs
   anyway, and install warns that NOBODY is woken. A wake file that already

{sessionvoice-0.3.2 → sessionvoice-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sessionvoice"
-version = "0.3.2"
+version = "0.3.3"
 description = "One listening engine for coding agents and the Delta bot: Apple / Nemotron / whisper -> one event stream -> VAD -> turns"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

{sessionvoice-0.3.2 → sessionvoice-0.3.3}/src/ears/_keeper/call-ears

@@ -12,8 +12,8 @@ A call already live when this starts keeps the ear it has (one restarted with th
 leaves its captures running), and one with no ear gets one. Once, every already-live
 call was left alone, so a restart mid-call left that call deaf to the end.
 Stop: touch $CALL_EARS_DIR/STOP. Log: stdout (the keeper's $EARS_LOG_DIR/ears-keeper-calls.log);
-each ear's in $CALL_EARS_DIR/capture-N.log. CALL_EARS_DIR defaults to
-${XDG_STATE_HOME:-~/.local/state}/ears/call-ears (it was ~/.<agent>/call-ears).
+each ear's in $CALL_EARS_DIR/capture-N.log. CALL_EARS_DIR defaults to the state item
+call-ears (`ears home state-dir call-ears`; it was ~/.<agent>/call-ears, then an XDG folder).
 
 The room and the calls were once two launch agents; now they are one, so
 this is not a launch
@@ -30,9 +30,42 @@ if os.path.dirname(os.path.abspath(__file__)) not in sys.path:
 import phone_roots  # noqa: E402  (keeper/ is not a package)
 
 HOME = Path.home()
-# The keeper passes its own; the default is the keeper's (keeper/ears-keeper.sh), change both.
-DIR = Path(os.environ.get("CALL_EARS_DIR")
-           or Path(os.environ.get("XDG_STATE_HOME") or HOME / ".local/state") / "ears/call-ears")
+HERE = Path(__file__).resolve().parent
+
+
+def voice_home():
+    """ears/home.py, the ONE place voice names its state items.
+    keeper/ imports nothing from the ears package, so it loads home.py (standard library
+    only) by its path, once: the checkout's src/ears/home.py, else the wheel's ears/home.py
+    above ears/_keeper/. Not there: exit 2, naming where it looked; there is no copy of the
+    rule to fall back on."""
+    mod = getattr(voice_home, "mod", None)
+    if mod is None:
+        import importlib.util
+        tried = [HERE.parent / "src/ears/home.py", HERE.parent / "home.py"]
+        f = next((f for f in tried if f.is_file()), None)
+        if f is None:
+            print(f"call-ears: no ears/home.py at {' nor '.join(map(str, tried))}: it names "
+                  "voice's state folders. Run it from a sessionvoice checkout, the plugin or the "
+                  "package, or set CALL_EARS_DIR", file=sys.stderr)
+            sys.exit(2)
+        spec = importlib.util.spec_from_file_location("_voice_home", f)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        voice_home.mod = mod
+    return mod
+
+
+def voice_state_path(item: str) -> Path:
+    """The state item ITEM's path, as the PACKAGE answers it (ears.home.asked_state_path):
+    its own variable wins and asks nothing; else exit 2, naming both answers, when the package
+    cannot be asked or disagrees with this checkout's home.py."""
+    return voice_home().asked_state_path(item, "call-ears")
+
+
+# The keeper passes its own (CALL_EARS_DIR, always): this default is for a run by hand, and it
+# is the keeper's, the state item call-ears (ears-keeper.sh asks the same).
+DIR = voice_state_path("call-ears")
 STOP = DIR / "STOP"
 # The calls the probe finds live, "call:N,call:M", rewritten every loop (so its age says this
 # is alive): the keeper's room-off rule reads it. A capture is no proof of a live call - one

{sessionvoice-0.3.2 → sessionvoice-0.3.3}/src/ears/_keeper/ears-keeper.sh

@@ -57,7 +57,7 @@
 # 5 min; back to 2 s after a run of a minute). It stands aside while another job runs a
 # call-ears (the old com.voicemode.ears-call), so a cutover never puts two ears on a call.
 # EARS_CALLS=0: the room only. The call ears' own stop file still works: touch
-# $CALL_EARS_DIR/STOP (default ${XDG_STATE_HOME:-~/.local/state}/ears/call-ears/STOP); rm it and
+# $CALL_EARS_DIR/STOP (default: the state item call-ears, `ears home state-dir call-ears`); rm it and
 # the keeper starts them again.
 set -uo pipefail
 DEVICE="${1:-airpods}"
@@ -103,6 +103,14 @@ NOTIFY="${EARS_NOTIFY:-}"
 VOICE_SETTINGS="$HOME/.sessionkit/voice/settings"
 CONF="${EARS_CONF:-$VOICE_SETTINGS/ears.json}"
 LOGDIR="$("$PY" -m ears.home log-dir)" && [ -n "$LOGDIR" ] || { echo "ears-keeper: $PY -m ears.home log-dir named no log folder - run \`uv sync\` in $ROOT, or set EARS_PY" >&2; exit 2; }
+# The state root, for the heard log's folder (HEARD_DIR, with the heard region below): the
+# PACKAGE's answer, "$PY" -m ears.home state-dir, as for the log folder.
+# $PY is the package's python and every writer this keeper starts runs under it, so its answer is
+# the one they write to; there is no copy of the rule here. No answer (a 0.3.2 package has no
+# state-dir): exit 2 before anything is read or written, never a guess. $EARS_HEARD_DIR asks nothing.
+if [ -z "${EARS_HEARD_DIR:-}" ]; then
+  STATE_DIR="$("$PY" -m ears.home state-dir)" && [ -n "$STATE_DIR" ] || { echo "ears-keeper: $PY -m ears.home state-dir named no state root (a package older than 0.3.3 has none) - upgrade the package and the plugin together, run \`uv sync\` in $ROOT, or set EARS_PY" >&2; exit 2; }
+fi
 RUN="${EARS_RUN:-$HOME/.cache/ears/run}"
 mkdir -p "$LOGDIR" "$RUN"
 # The settings-schema copies (.ears.schema.json and the rest), brought up to date with the
@@ -238,7 +246,9 @@ OUT_EVERY="${EARS_OUT_EVERY:-30}"          # 0: no backstop, only after an input
 OUT_FALLBACK="${EARS_OUTPUT_FALLBACK:-1}"   # 0: never touch the Mac's default output
 # Here, between OUT_EVERY= and listen_on(): tests/test_keeper_fallback.py runs this region
 # alone under set -u, so an assignment outside it would make every test fall back unseen.
-AUDIO_DEVICES="${AUDIO_DEVICES_FILE:-${XDG_STATE_HOME:-$HOME/.local/state}/audio/devices.json}"
+# The state item audio-devices: AUDIO_DEVICES_FILE, else the package's
+# answer (its old file while that is real, else in the state root). No answer: exit 2.
+AUDIO_DEVICES="${AUDIO_DEVICES_FILE:-$("$PY" -m ears.home state-dir audio-devices)}" && [ -n "$AUDIO_DEVICES" ] || { echo "ears-keeper: $PY -m ears.home state-dir audio-devices named no devices file - upgrade the package and the plugin together, or set AUDIO_DEVICES_FILE" >&2; exit 2; }
 out_tried=""; out_src="file"
 audio_outputs() {  # line 1 = the default output ("" if none), then one output name per
   # line, from $AUDIO_DEVICES while it is fresh. Exit 1 = stale or missing: do your own read.
@@ -394,7 +404,9 @@ call_live() {  # the live calls the ears hear, "call:N[,call:M]"; "" when none,
 }
 calls_published() {  # call-ears' probe, "call:N[,call:M]" from $CALL_EARS_DIR/live; "" when the
   # file is absent or older than EARS_CALLS_LIVE_AGE seconds (call-ears is down: captures decide)
-  local f="${CALL_EARS_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/ears/call-ears}/live" m
+  local f m
+  f="${CALL_EARS_DIR:-$("$PY" -m ears.home state-dir call-ears)}" && [ -n "$f" ] || return 0
+  f="$f/live"
   # macOS stat by path: Homebrew's GNU stat can come first on PATH, and reads -f as --file-system
   m="$(/usr/bin/stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)" || return 0
   [ $(( $(date +%s) - m )) -le "${EARS_CALLS_LIVE_AGE:-5}" ] || return 0
@@ -403,9 +415,11 @@ calls_published() {  # call-ears' probe, "call:N[,call:M]" from $CALL_EARS_DIR/l
 # --- calls: the call ears, this keeper's child (tests/test_keeper_calls.py runs these alone) ---
 CALLS="${EARS_CALLS:-1}"
 CALL_EARS="${EARS_CALL_EARS:-$(cd "$(dirname "$0")" && pwd)/call-ears}"
-# call-ears' own dir (STOP, live, its log): user state, as bin/call-tap's RUN is
-# (a host keeping its old dir sets CALL_EARS_DIR to it). keeper/call-ears has the same default.
-CALL_EARS_DIR="${CALL_EARS_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/ears/call-ears}"; export CALL_EARS_DIR
+# call-ears' own dir (STOP, live, its log): the state item call-ears, as
+# bin/call-tap's RUN is call-tap: CALL_EARS_DIR, else the package's answer (its old folder while
+# that is real, else in the state root). keeper/call-ears asks the same item. No answer: exit 2.
+CALL_EARS_DIR="${CALL_EARS_DIR:-$("$PY" -m ears.home state-dir call-ears)}" && [ -n "$CALL_EARS_DIR" ] || { echo "ears-keeper: $PY -m ears.home state-dir call-ears named no call ears folder - upgrade the package and the plugin together, or set CALL_EARS_DIR" >&2; exit 2; }
+export CALL_EARS_DIR
 # A call-ears is a python running a file named call-ears: the old launch agent's, ~/.<agent>/tools'
 # or ours. Not a capture's `--session call-ears-N`, not `less keeper/call-ears`.
 CALL_EARS_PAT="${EARS_CALL_EARS_PAT:-[Pp]ython[0-9.]* [^ ]*/call-ears( |$)}"
@@ -624,26 +638,7 @@ model_started() {  # $1 = the device: a capture is running, so a model DEAF epis
 # listen-stopped and its partials and turns go to the stt region. The speaker side-car's
 # rows, speakers_DAY.jsonl beside the heard log, are read in the SAME python, with their own offset
 # and the same day-roll and cut-short rules, and go to the speakers region.
-# --- sessionvoice_home: a copy of ears.home.sessionvoice_home (tests/test_home.py holds it) ---
-# $SESSIONVOICE_HOME, $VOICEMODE_BASE_DIR, ~/.sessionvoice or ~/.voicemode if it holds the
-# heard log (a heard.lock or a heard_*.jsonl in logs/conversations), else ~/.sessionvoice.
-sessionvoice_home() {
-  local v d
-  for v in "${SESSIONVOICE_HOME:-}" "${VOICEMODE_BASE_DIR:-}"; do
-    [ -n "$v" ] || continue
-    case $v in "~" | "~/"*) v="$HOME${v#\~}" ;; esac
-    echo "$v"; return 0
-  done
-  for d in "$HOME/.sessionvoice" "$HOME/.voicemode"; do
-    if [ -e "$d/logs/conversations/heard.lock" ] \
-        || compgen -G "$d/logs/conversations/heard_*.jsonl" >/dev/null; then
-      echo "$d"; return 0
-    fi
-  done
-  echo "$HOME/.sessionvoice"
-}
-# --- end sessionvoice_home ---
-HEARD_DIR="${EARS_HEARD_DIR:-$(sessionvoice_home)/logs/conversations}"
+HEARD_DIR="${EARS_HEARD_DIR:-${STATE_DIR:-}/logs/conversations}"   # STATE_DIR: asked at the top (or exit 2)
 heard_file=""; heard_off=0; spk_file=""; spk_off=0
 heard_events() {  # $1 = heard log, $2 = byte offset -> line 1 the offset after the last whole line,
   # then one TAB line per event in between:
@@ -1179,7 +1174,8 @@ stop_pid() {  # $1 pid, $2 what it is, $3 its stop file ("" for none): the stop
 #   nothing on a loop that finds nothing to stop.
 # ears_off runs every loop while off (and at a start that is off), so an ear started behind the
 # keeper's back is stopped within a loop too.
-TAP_RUN="${EARS_CALL_TAP_RUN:-${XDG_STATE_HOME:-$HOME/.local/state}/ears/call-tap}"   # bin/call-tap's RUN
+# bin/call-tap's RUN: the state item call-tap, asked as call-tap asks it (EARS_CALL_TAP_RUN wins)
+TAP_RUN="${EARS_CALL_TAP_RUN:-$("$PY" -m ears.home state-dir call-tap)}" && [ -n "$TAP_RUN" ] || { echo "ears-keeper: $PY -m ears.home state-dir call-tap named no call-tap folder - upgrade the package and the plugin together, or set EARS_CALL_TAP_RUN" >&2; exit 2; }
 off_other=""
 call_legs() {  # the running call-leg captures (`--source call:N`), one pid per line
   local p args