diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5ac10aa..d22f955 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "devscope", "description": "Real-time developer activity monitoring for Claude Code sessions", - "version": "0.36.0", + "version": "0.37.0", "author": { "name": "Lucas Dow", "email": "lucdow7@gmail.com" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1a0c0c8..bd297a5 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "devscope", - "version": "0.36.0", + "version": "0.37.0", "description": "Real-time developer activity monitoring for Claude Code sessions", "author": { "name": "Lucas Dow", diff --git a/CHANGELOG.md b/CHANGELOG.md index 67df15e..f2b7c5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [0.37.0] - 2026-10-26 + +### Added +- **Auto voice skips background noise.** After each turn the server now + decides whether the reply is worth saying out loud. Turns started by a + background event (a monitor expiring, a task notification, a progress + update) are spoken only when they bring news: finished work, a failure, or a + new question. A reply that only restates what the last summary said is + skipped too. Turns you started are still summarized, and failures are never + skipped. The plugin tells the server whether you prompted the turn + (`prompted/`) and sends the summary it last spoke for the session + (`last/`). Skips are logged in `voice.log`. Set `"auto_skip": false` + in `voice.json` to hear every reply again. Needs a server with skip support; + older servers keep summarizing every reply. + ## [0.36.0] - 2026-10-26 ### Changed diff --git a/CLAUDE.md b/CLAUDE.md index 8fab951..5e44672 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -247,6 +247,13 @@ claude plugin disable devscope@devscope # Disable and speaks under the lock; a newer reply from the same session replaces an older one. This deliberately sends response text in `standard` mode too: the user turned the feature on for exactly that, and the endpoint stores nothing. +- **Skipping noise** (voice.json `auto_skip`, default on): the reply request carries `may_skip: true`, + `background` (no `prompt.submit` since the last turn: `prompted/` is written by the prompt + hook and consumed by Stop, so a turn started by a monitor or task notification is background) and + `previous` (the summary last spoken for the session, `last/`, written by `speak.sh` after + speaking). The server may answer `{skip: true}`; `_ds_voice_summary` then returns 2, nothing is + spoken, the job is removed and `voice.log` gets `skip reply (background|prompted)`. A server + without skip support ignores the fields and always returns text. - **Verbosity** (`/devscope:voice verbosity`, voice.json `verbosity: {explain, auto}`: short | normal | long). Auto voice sends it as `length` with the `reply` summary request. Explain mode reads it inline (`` !`cli.sh verbosity explain` `` in commands/voice.md) and its level diff --git a/README.md b/README.md index 8136898..b8b242f 100644 --- a/README.md +++ b/README.md @@ -251,6 +251,8 @@ Auto voice is a short spoken summary whenever Claude finishes a reply: the outco - `/devscope:voice auto` turns it on or off for the session you type it in (`auto on`, `auto off`; plain `auto` toggles). It lasts as long as that Claude Code window, `/clear` included. - `/devscope:voice auto-default on|off` is the setting for every session where you have not used `auto` (off unless you turn it on). +**It stays quiet on noise.** Turns you did not start yourself, such as a monitor expiring or a task notification, are only spoken when they bring news: finished work, a failure, or a new question. A reply that just repeats what the last summary told you is skipped too. Turns you started are still summarized, and failures are never skipped. Set `"auto_skip": false` in `voice.json` to hear every reply. + `/devscope:voice status` shows both. The reply is sent to your DevScope server to summarize and is not stored; in `private` mode you only hear which project finished, voiced locally. ### Explain it out loud diff --git a/commands/voice.md b/commands/voice.md index c7eb403..3c04b40 100644 --- a/commands/voice.md +++ b/commands/voice.md @@ -25,7 +25,7 @@ Three features: - **Announcer** (`on`/`off`): speaks only after a session has waited on the user past a grace delay (30 s for permission prompts and questions, 10 s for failures, 2 min for finished turns if `finished on`), then reminds every 5 min, up to 3 times. Answering in time keeps it silent. - **Auto voice**, per session: `auto` / `auto on` / `auto off` sets it for **this session only** (plain `auto` toggles; `replies` is an old name for it), lasting as long as this Claude Code window. `auto-default on|off` is the setting for sessions where `auto` was not used. Whenever Claude finishes a reply, a two-to-three sentence spoken summary of what it said. The reply is sent to the DevScope server to summarize and is not stored; in `private` mode only " is done" is spoken, locally. A turn that used `explain` is not summarized on top. -`speed slow|normal|fast` sets how fast every voice talks: 1.0x, 1.2x (default) or 1.5x; `speed ` sets any rate from 0.5 to 2 (e.g. `speed 1.35`); plain `speed` shows the current one. `stop` ends speech in progress (a long explanation or a summary). `when-locked quiet|play`: by default (`quiet`) nothing is spoken while the screen is locked (macOS `ioreg`/screensaver, Linux logind `LockedHint`): announcements wait until unlock, auto voice is skipped, an explanation stops; `play` ignores the lock. `verbosity [explain|auto] short|normal|long` sets how detailed explain and auto voice are (both when no mode is named); plain `verbosity` shows them. `auto off` turns off only auto voice; announcements and `explain` are unaffected. `mute` silences auto voice and announcements. Settings live in `~/.config/devscope/voice.json` (`delays`, `reminder_interval`, `max_reminders`, `speak_replies`, `speed` (a number, 0.5-2), `engine`: `auto`/`server`/`piper`/`system`/`off`, `voice`, `volume` (0.5-3, server default 2), `playback_volume` (0.5-3, default 1: how loud this computer plays the speech, without turning up its other sounds), `piper_model`). +`speed slow|normal|fast` sets how fast every voice talks: 1.0x, 1.2x (default) or 1.5x; `speed ` sets any rate from 0.5 to 2 (e.g. `speed 1.35`); plain `speed` shows the current one. `stop` ends speech in progress (a long explanation or a summary). `when-locked quiet|play`: by default (`quiet`) nothing is spoken while the screen is locked (macOS `ioreg`/screensaver, Linux logind `LockedHint`): announcements wait until unlock, auto voice is skipped, an explanation stops; `play` ignores the lock. `verbosity [explain|auto] short|normal|long` sets how detailed explain and auto voice are (both when no mode is named); plain `verbosity` shows them. `auto off` turns off only auto voice; announcements and `explain` are unaffected. `mute` silences auto voice and announcements. Settings live in `~/.config/devscope/voice.json` (`delays`, `reminder_interval`, `max_reminders`, `speak_replies`, `auto_skip` (default true: auto voice stays quiet on background noise and replies with nothing new; `false` speaks every reply), `speed` (a number, 0.5-2), `engine`: `auto`/`server`/`piper`/`system`/`off`, `voice`, `volume` (0.5-3, server default 2), `playback_volume` (0.5-3, default 1: how loud this computer plays the speech, without turning up its other sounds), `piper_model`). ## Explain mode (`explain [topic]`) diff --git a/scripts/voice/lib.sh b/scripts/voice/lib.sh index 5fc1762..1aa6cf9 100755 --- a/scripts/voice/lib.sh +++ b/scripts/voice/lib.sh @@ -12,6 +12,11 @@ # that session deletes it, which is how answering in # time keeps the announcer silent. # replies/.json the latest finished turn to summarize, per session. +# prompted/ the developer started the current turn (a prompt); +# a turn that ends without one was started by a +# background event, which auto voice may skip. +# last/ the reply summary last spoken for the session, so +# the server can tell whether a new one says anything new. # say/.json an explanation waiting to be spoken. # labels/ the session's spoken name from the server ("api-service, # rate limiter fix"), kept so a session keeps one name. @@ -94,7 +99,7 @@ DS_VOICE_REPLY_TAIL=1100 _ds_voice_mkdirs() { ( umask 077; mkdir -p "$DS_VOICE_PENDING" "$DS_VOICE_DIR/replies" "$DS_VOICE_DIR/say" \ "$DS_VOICE_DIR/spoke" "$DS_VOICE_DIR/speakers" "$DS_VOICE_DIR/auto" "$DS_VOICE_DIR/labels" "$DS_VOICE_DIR/queue" \ - "$DS_VOICE_DIR/sessions" ) 2>/dev/null + "$DS_VOICE_DIR/sessions" "$DS_VOICE_DIR/prompted" "$DS_VOICE_DIR/last" ) 2>/dev/null } # --- Session labels --- @@ -165,15 +170,32 @@ _ds_voice_batch_name() { # job-file } # Ask the server for the text, keep the label it returns, print the text. +# Returns 2 when the server answered that a reply is not worth saying. _ds_voice_summary() { # json-body session-id local raw text label raw=$(_ds_api POST /api/ai/voice-summary "$1" "$DS_VOICE_SUMMARY_TIMEOUT") || return 0 text=$(printf '%s' "$raw" | jq -r '.text // empty' 2>/dev/null) label=$(printf '%s' "$raw" | jq -r '.label // empty' 2>/dev/null) + if [ -z "$text" ] && [ "$(printf '%s' "$raw" | jq -r '.skip // false' 2>/dev/null)" = true ]; then + _ds_voice_keep_label "$2" "$label" + return 2 + fi [ -n "$text" ] && _ds_voice_keep_label "$2" "$label" printf '%s' "$text" } +# A session id as a file name. +_ds_voice_safe() { printf '%s' "$1" | tr -cd 'A-Za-z0-9_-'; } + +# The reply summary last spoken for a Claude Code session, and remembering one. +_ds_voice_last_said() { [ -n "$1" ] && head -c 1000 "$DS_VOICE_DIR/last/$(_ds_voice_safe "$1")" 2>/dev/null; return 0; } +_ds_voice_remember_said() { # session-id text + [ -n "$1" ] || return 0 + _ds_voice_mkdirs + ( umask 077; printf '%s' "$2" > "$DS_VOICE_DIR/last/$(_ds_voice_safe "$1")" ) 2>/dev/null || true + find "$DS_VOICE_DIR/last" "$DS_VOICE_DIR/prompted" -type f -mtime +2 -delete 2>/dev/null || true +} + _ds_voice_log() { _ds_voice_mkdirs ( umask 077; printf '%s %s\n' "$(date '+%F %T')" "$*" >> "$DS_VOICE_LOG" ) 2>/dev/null @@ -402,16 +424,29 @@ _ds_voice_on_event() { # (/devscope:voice explain) is not summarized on top of it. _ds_voice_on_reply_event() { # event-type hook-input _ds_voice_replies_on || return 0 - local et="$1" input="$2" sid pid eid job tmp cwd privacy="${DEVSCOPE_PRIVACY:-standard}" last="" + local et="$1" input="$2" sid pid eid job tmp cwd privacy="${DEVSCOPE_PRIVACY:-standard}" last="" background=true case "$et" in - prompt.submit) - # A turn interrupted after it spoke never reached Stop: forget it. - pid=$(_ds_voice_claude_pid) - [ -n "$pid" ] && rm -f "$DS_VOICE_DIR/spoke/$pid" - return 0 ;; - response.complete) ;; + prompt.submit|response.complete) ;; *) return 0 ;; esac + sid=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null) + if [ "$et" = prompt.submit ]; then + # A turn interrupted after it spoke never reached Stop: forget it. + pid=$(_ds_voice_claude_pid) + [ -n "$pid" ] && rm -f "$DS_VOICE_DIR/spoke/$pid" + # The developer started this turn; one that ends without a prompt came + # from a background event (a monitor, a task notification). + if [ -n "$sid" ]; then + _ds_voice_mkdirs + : > "$DS_VOICE_DIR/prompted/$(_ds_voice_safe "$sid")" 2>/dev/null + fi + return 0 + fi + [ -n "$sid" ] || return 0 + if [ -f "$DS_VOICE_DIR/prompted/$(_ds_voice_safe "$sid")" ]; then + background=false + rm -f "$DS_VOICE_DIR/prompted/$(_ds_voice_safe "$sid")" + fi pid=$(_ds_voice_claude_pid) if [ -n "$pid" ] && [ -f "$DS_VOICE_DIR/spoke/$pid" ]; then rm -f "$DS_VOICE_DIR/spoke/$pid" @@ -422,37 +457,46 @@ _ds_voice_on_reply_event() { # event-type hook-input # Nobody at the computer: a summary of this reply would be stale by the # time anyone hears it, and it is on screen anyway. _ds_voice_can_play || return 0 - sid=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null) - [ -n "$sid" ] || return 0 # Private sessions keep the reply on this machine and get the template. [ "$privacy" = "private" ] || last=$(printf '%s' "$input" | jq -r \ --argjson h "$DS_VOICE_REPLY_HEAD" --argjson t "$DS_VOICE_REPLY_TAIL" ' .last_assistant_message // "" | if length > ($h + $t) then .[:$h] + " ... " + .[-$t:] else . end' 2>/dev/null) eid=$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen 2>/dev/null || echo "r-$(_ds_now_ns)") _ds_voice_mkdirs - job="$DS_VOICE_DIR/replies/$(printf '%s' "$sid" | tr -cd 'A-Za-z0-9_-').json" + job="$DS_VOICE_DIR/replies/$(_ds_voice_safe "$sid").json" tmp="$job.tmp.$$" cwd=$(printf '%s' "$input" | jq -r '.cwd // ""' 2>/dev/null) jq -n --arg eid "$eid" --arg sid "$sid" --arg dsid "${DS_VOICE_SESSION:-$sid}" --arg privacy "$privacy" --arg last "$last" \ - --arg project "$(basename "${cwd:-session}")" --arg branch "$(_ds_voice_branch "$cwd")" \ - '{eventId: $eid, sessionId: $sid, dsSessionId: $dsid, project: $project, branch: $branch, lastMessage: $last, privacy: $privacy}' \ + --arg project "$(basename "${cwd:-session}")" --arg branch "$(_ds_voice_branch "$cwd")" --argjson bg "$background" \ + '{eventId: $eid, sessionId: $sid, dsSessionId: $dsid, project: $project, branch: $branch, lastMessage: $last, + privacy: $privacy, background: $bg}' \ > "$tmp" && mv "$tmp" "$job" || { rm -f "$tmp"; return 0; } _ds_voice_spawn "$DS_VOICE_LIB_DIR/speak.sh" reply "$sid" "$eid" } # The text for a queued reply: an AI summary, or the template when the session -# is private, the reply was empty or the server fails. +# is private, the reply was empty or the server fails. Fails when the server +# judged the reply not worth saying (background noise, nothing new): then +# nothing is spoken. voice.json `auto_skip: false` asks for every reply. _ds_voice_reply_text() { # job-file - local body text="" privacy sid + local body text="" privacy sid csid may_skip=true rc read -r privacy < <(jq -r '.privacy' "$1" 2>/dev/null) || return 1 sid=$(jq -r '.dsSessionId // .sessionId // ""' "$1" 2>/dev/null) + csid=$(jq -r '.sessionId // ""' "$1" 2>/dev/null) + [ "$(_ds_voice_conf .auto_skip true)" = false ] && may_skip=false if [ "$privacy" != "private" ] && [ -n "${DEVSCOPE_API_KEY:-}" ]; then body=$(jq -c --arg length "$(_ds_voice_verbosity auto)" --arg label "$(_ds_voice_label "$sid")" \ + --argjson skip "$may_skip" --arg previous "$(_ds_voice_last_said "$csid")" \ '{trigger: "reply", project: .project, last_message: .lastMessage, length: $length, session_id: (.dsSessionId // .sessionId), label: $label} + + (if $skip then {may_skip: true, background: (.background // false), previous: $previous} else {} end) | with_entries(select(.value != "" and .value != null))' "$1" 2>/dev/null) if printf '%s' "$body" | jq -e '.last_message' >/dev/null 2>&1; then - text=$(_ds_voice_summary "$body" "$sid") + text=$(_ds_voice_summary "$body" "$sid"); rc=$? + if [ "$rc" = 2 ]; then + _ds_voice_log "skip reply ($(jq -r 'if .background then "background" else "prompted" end' "$1" 2>/dev/null)): nothing worth saying" + return 1 + fi fi fi [ -n "$text" ] || text=$(_ds_voice_template finished "$(_ds_voice_name "$1")") diff --git a/scripts/voice/speak.sh b/scripts/voice/speak.sh index d06d123..49a2e6a 100755 --- a/scripts/voice/speak.sh +++ b/scripts/voice/speak.sh @@ -35,7 +35,8 @@ case "${1:-}" in export DS_VOICE_PROGRESS_PROJECT DS_VOICE_PROGRESS_SESSION # Summarized before waiting for a turn: sessions that finish together get # their summaries in parallel instead of each waiting on the others' calls. - TEXT=$(_ds_voice_reply_text "$JOB") || exit 0 + # Fails when the server judged the reply not worth saying. + TEXT=$(_ds_voice_reply_text "$JOB") || { current && rm -f "$JOB"; exit 0; } PRIVACY=$(jq -r '.privacy' "$JOB" 2>/dev/null) speak_reply() { local text="$TEXT" privacy="$PRIVACY" @@ -46,6 +47,7 @@ case "${1:-}" in _ds_voice_can_play || return 0 _ds_voice_log "speak reply: $text" _ds_voice_speak_long "$text" "$privacy" + _ds_voice_remember_said "$DS_VOICE_PROGRESS_SESSION" "$text" current && rm -f "$JOB" _ds_voice_progress_done } diff --git a/tests/voice/run.sh b/tests/voice/run.sh index f95048a..cc8eeaf 100644 --- a/tests/voice/run.sh +++ b/tests/voice/run.sh @@ -399,6 +399,27 @@ wait_spoken 1 5; [ "$(last_at $S_AT .body.length)" = short ] && ok "auto voice s jq 'del(.verbosity)' "$CONF" > "$TMP/c" && mv "$TMP/c" "$CONF" [ "$(lines)" = 1 ] && [ ! -d "$PENDING" ] || [ -z "$(ls "$PENDING" 2>/dev/null)" ] && ok "no announcer marker when the announcer is off" || bad "announcer" "$(ls "$PENDING")" +# 12a. The server may judge a reply not worth saying (background noise, nothing new). +VLOG="$HOME/.cache/devscope/voice/voice.log" +PROMPT='{hook_event_name: "UserPromptSubmit", prompt: "fix the timer"}' +reset; respond '{"skip": true, "label": "plugin, reminder timer"}' +hook response-stop.sh k1 /work/plugin "$STOP"; sleep 2 +[ "$(lines)" = 0 ] && ok "skip: nothing spoken" || bad "skip spoken" "$(spoken)" +[ "$(last_at $S_AT .body.may_skip)/$(last_at $S_AT .body.background)" = "true/true" ] && ok "a turn without a prompt is sent as background, skippable" || bad "skip body" "$(last_at $S_AT .body)" +grep -q "skip reply (background)" "$VLOG" && ok "skip is logged" || bad "skip log" "$(tail -3 "$VLOG")" +[ ! -f "$HOME/.cache/devscope/voice/replies/k1.json" ] && ok "skip: job removed" || bad "skip job" "left behind" +[ "$(cat "$HOME/.cache/devscope/voice/labels/k1" 2>/dev/null)" = "plugin, reminder timer" ] && ok "skip still keeps the label" || bad "skip label" "$(ls "$HOME/.cache/devscope/voice/labels")" +reset; respond '{"text": "The timer is fixed."}' +hook prompt-submit.sh k2 /work/plugin "$PROMPT"; hook response-stop.sh k2 /work/plugin "$STOP" +wait_spoken 1 5; [ "$(last_at $S_AT .body.background)" = false ] && ok "a prompted turn is not background" || bad "prompted" "$(last_at $S_AT .body)" +[ "$(last_at $S_AT .body.previous)" = null ] && ok "no previous summary on a first turn" || bad "first previous" "$(last_at $S_AT .body)" +reset; hook response-stop.sh k2 /work/plugin "$STOP" +wait_spoken 1 5; [ "$(last_at $S_AT .body.previous)/$(last_at $S_AT .body.background)" = "The timer is fixed./true" ] && ok "sends the last spoken summary; the prompt marker is used once" || bad "previous" "$(last_at $S_AT .body)" +reset; jq '.auto_skip = false' "$CONF" > "$TMP/c" && mv "$TMP/c" "$CONF" +hook response-stop.sh k3 /work/plugin "$STOP" +wait_spoken 1 5; [ "$(last_at $S_AT .body.may_skip)/$(last_at $S_AT .body.previous)" = "null/null" ] && ok "auto_skip false: every reply summarized" || bad "auto_skip off" "$(last_at $S_AT .body)" +jq 'del(.auto_skip)' "$CONF" > "$TMP/c" && mv "$TMP/c" "$CONF" + reset DEVSCOPE_PRIVACY=private hook response-stop.sh r2 /work/secret "$STOP" wait_spoken 1 5 && [ "$(spoken)" = "secret is done and waiting for you." ] && ok "private: template only" || bad "reply private" "$(spoken)"