dsh-chime-sound 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VviLliAm-qwq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# dsh-chime-sound
+
+dsh-tui 提示音效插件（原名 dsh-notice-sound，2026-09-07 更名）/ Notification sounds for dsh-tui.
+
+- 触发:女仆调用询问模块 `ask_user_question`(`session/event` `tool/call`,提醒主人回来回答问题)与回复完成(`session/event` `turn/end`,agent-loop 每回合仅发一次;`assistant/message` 会随每个工具步骤多次触发,不采用),区分终端聚焦/未聚焦
+- 4 组音效(清脆电子 / 木质敲击 / 八比特 / 温馨钢琴)× 4 情景,设置页「提示音效」类中可选择或关闭
+- **0.2.0 新增:主音量设置**(设置页「音量 / Volume」项):0%~150%,每档 5%(31 档),默认 100% = 原音量。←/→ 单按 ±5%,**长按连续调节**(dsh-tui 输入层把长按重复展开为逐档事件,无需额外配置);修改后立即试听。>100% 时样本做 16-bit 饱和削波(峰值约 105%,仅极短时段削波;如需无失真可后续改软限幅)。音量仅在插件内部对 WAV 样本增益,不影响系统音量
+- 音效由本仓库 `scripts/gen-sounds.mjs` 生成(WAV,16-bit/48kHz)
+- 设置与文案支持中英文
+
+## ⚠️ 平台限制（Windows only）
+
+本插件通过 **Win32 API**（koffi → `winmm.dll` `PlaySoundW` / `user32.dll` 焦点检测）播放声音，**仅支持 Windows（Windows Terminal / conhost）**。其他平台（Linux/macOS）上插件静默降级为 no-op（不播放、不拖垮启动），并在日志中给出 `Win32-only` 警告。请勿在非 Windows 环境期待提示音。
+
+## 安装
+
+**方式一（dsh CLI，推荐）：**
+
+```sh
+dsh plugin --profile <profile> add dsh-chime-sound
+```
+
+（或从 dsh 插件市场 / GitHub 安装：`dsh plugin add github:VviLliAm-qwq/dsh-chime`。）
+
+**方式二（手动，与生态常见流程一致）：**
+
+1. 把插件包复制到 `~/.dsh/profiles/dsh-tui/node_modules/dsh-chime-sound/`
+2. 在 `~/.dsh/profiles/dsh-tui/package.json` 的 `dsh.profile.bundles` 追加 `"dsh-chime-sound"`（声明了 `dsh.bundle.patch`，启动时自动挂载）
+3. 重启 dsh-tui（`/restart`）生效
+
+**兼容性**：dsh-tui 0.10.x（`ctx.tuiSettingsSections` / `session/event` 软探测接缝）；dsh 0.1.2-rc.1+；Node `^22.19 || >=24`；纯 ESM。配置键均有默认值，缺配置时行为退化为"什么都不发生"。
+
+## 配置
+
+设置项在 dsh-tui 设置页「提示音效 / Notice Sounds」类（或 `~/.dsh/settings.yaml` 的 `chime:` 命名空间）：
+
+```yaml
+chime:
+  doneFocus: g2   # 完成对话·聚焦时: g1-g4 / off
+  doneBlur: g2    # 完成对话·未聚焦时
+  askFocus: g2    # 提问·聚焦时
+  askBlur: g2     # 提问·未聚焦时
+  volume: "50"    # 0-150, 5% 步进, 默认 "100"
+```
+
+## 事件源说明(0.1.1 修复)
+
+此前用 dsh-tui 的 mediated `tuiMessageObserver.subscribe()` 订阅消息事件,但该 API 要求插件激活先通过 host admission 绑定已验证的 Component 身份;bundle-patch 挂载的插件不经过 admission,所有订阅被拒绝(`COMPONENT_NOT_ADMITTED`),导致提示音完全不触发。
+
+0.1.1 改用 `@deepseek-ai/dsh-session` 发布的 `session/event` cordis bus 事件(官方 `dsh-working-activity` 扩展同款通道),无需 Component identity:
+
+- `tool/call` 且 `name === 'ask_user_question'` → 提问音(askFocus/askBlur)
+- `turn/end` → 完成音(doneFocus/doneBlur),子代理会话不触发
+- 焦点判定:GetForegroundWindow 句柄 == GetConsoleWindow 或窗口类名匹配(`CASCADIA_HOSTING_WINDOW_CLASS`=Windows Terminal / `ConsoleWindowClass`=传统 conhost)。ConPTY 下 GetConsoleWindow 返回隐藏的 `PseudoConsoleWindow`(永非前台),旧代码仅按句柄/类名读法均有缺陷,现双判据+修正的类名读取
+- `dsh-plugin.json` 已移除不再使用的 `messages.observe` 声明
+
+安装后需重启 dsh-tui 生效。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-chime-sound bundle patch: mounts the notification-sound plugin.
+- insert:
+    - id: chime
+      name: 'dsh-chime-sound'

package/dsh-plugin.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://dsh.community/schemas/dsh-plugin-0.15.json",
+  "manifestVersion": "0.15",
+  "id": "com.dsh-tui.chime",
+  "name": "chime",
+  "version": "0.2.0",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": []
+  },
+  "permissions": [],
+  "subscriptions": [],
+  "contributes": {
+    "commands": []
+  },
+  "source": {
+    "repository": "https://github.com/VviLliAm-qwq/dsh-chime"
+  },
+  "compat": {
+    "hosts": [
+      "dsh-tui"
+    ]
+  },
+  "license": "MIT"
+}

package/lib/index.js

@@ -0,0 +1,435 @@
+/**
+ * dsh-chime — notification sounds for dsh-tui.
+ *
+ * Plays a distinct sound on two conversation events:
+ *   - the agent asks the user something via the ask_user_question tool
+ *     (session/event `tool/call`, `name === 'ask_user_question'`) — the
+ *     "user has to answer, come back" cue
+ *   - the assistant turn finishes    (session/event `turn/end`)
+ * with separate variants for focused vs unfocused terminal windows.
+ * Four sound groups (g1 crisp / g2 wood / g3 chiptune / g4 warm) are
+ * selectable per scenario in a dedicated settings section (zh/en); a master
+ * volume (0%–150%, 5% steps) gains the PCM samples before playback
+ * (lib/wav.js scales in memory; PlaySoundW gets SND_MEMORY buffers, so
+ * >100% just saturates — no global waveOut volume is touched).
+ *
+ * Windows integration is done through koffi (user32/kernel32/winmm):
+ * focus polling = GetForegroundWindow vs GetConsoleWindow handle OR the
+ * window class (CASCADIA_HOSTING_WINDOW_CLASS for Windows Terminal,
+ * ConsoleWindowClass for classic conhost; ConPTY's hidden
+ * PseudoConsoleWindow is never the foreground), playback via PlaySoundW
+ * (async, no console output).
+ *
+ * Event source: the `session/event` cordis bus, published by
+ * `@deepseek-ai/dsh-session` on every committed session event (the same
+ * channel the official `dsh-working-activity` extension uses) — NOT the
+ * grant-gated `tuiMessageObserver.subscribe` mediated API.
+ *
+ * Why: a bundle-patch mounted plugin is never put through host admission, so
+ * its Cordis activation has no verified dsh-plugin.json Component identity
+ * and the mediated observer rejects every subscribe
+ * (`COMPONENT_NOT_ADMITTED`), leaving the plugin deaf. The bus subscription
+ * needs no identity: the same events, no admission.
+ *
+ * Host services (settings / settings-sections) are resolved at runtime and
+ * retried until they appear — the issue-#183 pattern: an absent service
+ * degrades THIS plugin, never the boot.
+ *
+ * @module dsh-chime
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import z from '@deepseek-ai/schemastery';
+import koffi from 'koffi';
+import { scaleWav } from './wav.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SOUND_DIR = join(HERE, '..', 'assets', 'sounds');
+const DIAG_LOG = join(homedir(), '.dsh-tui', 'dsh-chime.log');
+
+/** Append a diagnostic line (best-effort; never throws). */
+function diag(line) {
+    try { appendFileSync(DIAG_LOG, `${new Date().toISOString()} ${line}\n`); } catch { /* ignore */ }
+}
+
+/** Plugin name; always the install id. */
+export const name = 'chime';
+
+/** Settings schema: one sound group per scenario plus a master volume. */
+export const Config = z.object({
+    doneFocus: z.string().default('g1'),
+    doneBlur: z.string().default('g2'),
+    askFocus: z.string().default('g3'),
+    askBlur: z.string().default('g4'),
+    /** Volume in percent, as a string (select values are strings): '0'..'150'. */
+    volume: z.string().default('100'),
+});
+/** Explicit boot defaults (mirrors the schema defaults). */
+const DEFAULT_CONFIG = { doneFocus: 'g1', doneBlur: 'g2', askFocus: 'g3', askBlur: 'g4', volume: '100' };
+
+/** scenario key -> wav file stem. */
+const SCENARIO_FILE = {
+    doneFocus: 'done-focus',
+    doneBlur: 'done-blur',
+    askFocus: 'ask-focus',
+    askBlur: 'ask-blur',
+};
+const GROUP_OPTIONS = [
+    { value: 'g1', label: 'Crisp', descriptions: { zh: '清脆电子', en: 'Crisp' } },
+    { value: 'g2', label: 'Wood', descriptions: { zh: '木质敲击', en: 'Wood' } },
+    { value: 'g3', label: 'Chiptune', descriptions: { zh: '八比特', en: 'Chiptune' } },
+    { value: 'g4', label: 'Warm', descriptions: { zh: '温馨钢琴', en: 'Warm' } },
+    { value: 'off', label: 'Off', descriptions: { zh: '关闭', en: 'Off' } },
+];
+/** Volume choices: 0%–150% in 5% steps (stored as plain value strings). */
+const VOLUME_OPTIONS = Array.from({ length: 31 }, (_, i) => {
+    const v = i * 5;
+    return { value: String(v), label: `${v}%` };
+});
+const VOLUME_MIN = 0;
+const VOLUME_MAX = 150;
+/** scenario field key -> [en label, localized descriptions]. */
+const FIELD_LABELS = {
+    doneFocus: ['Done (focused)', { zh: '完成对话·聚焦时', en: 'Done (focused)' }],
+    doneBlur: ['Done (unfocused)', { zh: '完成对话·未聚焦时', en: 'Done (unfocused)' }],
+    askFocus: ['Question (focused)', { zh: '提问·聚焦时', en: 'Question (focused)' }],
+    askBlur: ['Question (unfocused)', { zh: '提问·未聚焦时', en: 'Question (unfocused)' }],
+};
+
+// Win32 constants for PlaySoundW (memory playback, async, no system beep).
+const SND_MEMORY = 0x0004;
+const SND_ASYNC = 0x0001;
+const SND_NODEFAULT = 0x0002;
+const THROTTLE_MS = 700;
+const RETRY_MS = 400;
+const RETRY_LIMIT = 60; // ~24s of service readiness attempts
+// Playback pool: SND_MEMORY playback needs the buffer alive until the sound
+// finishes; slots are reused only after a long cooldown (sounds ≤1.3s, so 8
+// slots × 5s covers 40s of uninterrupted play — an idle slot is a safe one).
+const POOL_SIZE = 8;
+const POOL_COOLDOWN_MS = 5000;
+
+/** Lazy, shared Win32 bindings (koffi). */
+let win32 = null;
+function loadWin32() {
+    if (win32 === null) {
+        const pvoid = koffi.pointer('void');
+        const api = (lib, name, result, args) => lib.func('__stdcall', name, result, args);
+        const user32 = koffi.load('user32.dll');
+        const winmm = koffi.load('winmm.dll');
+        const kernel32 = koffi.load('kernel32');
+        const win32Local = {
+            getForegroundWindow: api(user32, 'GetForegroundWindow', 'uintptr_t', []),
+            getClassNameW: api(user32, 'GetClassNameW', 'int', ['uintptr_t', 'void*', 'int']),
+            playSound: api(winmm, 'PlaySoundW', 'int', ['void*', pvoid, 'uint32']),
+            consoleWindow: null,
+            // console hosts accept these two top-level window classes (fallback
+            // only — the primary check is the handle comparison below)
+            hostClasses: ['ConsoleWindowClass', 'CASCADIA_HOSTING_WINDOW_CLASS'],
+        };
+        try {
+            win32Local.consoleWindow = api(kernel32, 'GetConsoleWindow', 'uintptr_t', []);
+        }
+        catch {
+            win32Local.consoleWindow = null;
+        }
+        win32 = win32Local;
+    }
+    return win32;
+}
+
+/**
+ * Whether the current foreground window is THIS terminal window.
+ * Two reliable checks, OR'ed:
+ *   1. handle equality with GetConsoleWindow — classic console hosts expose
+ *      their own top-level window there;
+ *   2. class-name match — Windows Terminal (CASCADIA_HOSTING_WINDOW_CLASS)
+ *      and classic conhost (ConsoleWindowClass); needed because on ConPTY
+ *      GetConsoleWindow returns the hidden PseudoConsoleWindow, never the
+ *      foreground window. Class text is read as `n` UTF-16 chars (the
+ *      byte-index scan miss-reads the alternating NUL bytes).
+ */
+function isTerminalFocused(w) {
+    try {
+        const fg = w.getForegroundWindow();
+        if (fg === null || fg === 0) return false;
+        if (w.consoleWindow !== null) {
+            const own = w.consoleWindow();
+            if (own !== null && own !== 0 && fg === own) return true;
+        }
+        const buf = Buffer.alloc(400);
+        const n = w.getClassNameW(fg, buf, 200);
+        if (n > 0) {
+            const cls = buf.subarray(0, Math.min(n, 200) * 2).toString('utf16le');
+            if (w.hostClasses.includes(cls)) return true;
+        }
+        return false;
+    }
+    catch {
+        return true; // keep the previous (focused) assumption on Win32 hiccups
+    }
+}
+
+function sessionIdOf(session) {
+    if (session == null) return undefined;
+    return session.id ?? session.header?.id ?? session.sessionId;
+}
+
+/** Whether a session is a subagent child (its own event stream). */
+function isSubagentSession(session) {
+    try {
+        const header = session?.header ?? session?.meta;
+        return header?.origin === 'subagent' || (header?.delegationDepth ?? 0) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+
+/** Mount the settings section (display metadata only). */
+function registerSection(sections) {
+    const fields = [
+        {
+            path: ['volume'],
+            label: 'Volume',
+            descriptions: { zh: '音量', en: 'Volume' },
+            hint: '←/→ steps 5%, hold to repeat; >100% may clip',
+            hintDescriptions: { zh: '←/→ 每次 ±5%，长按连续调节；超过 100% 可能削波', en: '←/→ steps 5%, hold to repeat; >100% may clip' },
+            kind: 'select',
+            options: VOLUME_OPTIONS,
+        },
+        ...['doneFocus', 'doneBlur', 'askFocus', 'askBlur'].map((key) => {
+            const [label, descriptions] = FIELD_LABELS[key];
+            return {
+                path: [key],
+                label,
+                descriptions,
+                kind: 'select',
+                options: GROUP_OPTIONS,
+            };
+        }),
+    ];
+    return sections.register({
+        ns: 'chime',
+        title: 'Notice Sounds',
+        descriptions: { zh: '提示音效', en: 'Notice Sounds' },
+        fields,
+    });
+}
+
+/**
+ * Cordis plugin entry. All services are resolved at runtime through
+ * ctx.get (retried until they appear) so an absent/late service degrades
+ * this plugin, never the boot. Message events come from the session/event
+ * bus (no Component identity required — see module header).
+ */
+export function apply(ctx, config) {
+    diag('apply started');
+    if (process.platform !== 'win32') {
+        // TUI-RUN-001: the plugin is Win32-only (winmm/user32 via koffi); on
+        // other platforms it degrades to a no-op — never a boot failure.
+        diag(`platform=${process.platform}: sounds disabled (Win32-only)`);
+        ctx.logger.warn(`chime: Win32-only plugin (winmm/user32); notification sounds will not play on ${process.platform}`);
+    }
+    ctx.effect(function* () {
+        let scope = null;
+        let sectionRegistered = false;
+        let sectionDisposer = null;
+        let focusStarted = false;
+        let attempts = 0;
+        let retryTimer = null;
+
+        // ── playback state ────────────────────────────────────────────
+        const lastPlay = new Map();
+        const wavCache = new Map(); // wav file path -> source Buffer
+        const playPool = Array.from({ length: POOL_SIZE }, () => ({ buf: null, usedAt: 0 }));
+        let wrappedPrev = { ...DEFAULT_CONFIG };
+        let focused = true;
+        let focusTimer = null;
+        let loaded = null;
+
+        /** Clamp the stored volume string to 0..150 (invalid -> 100). */
+        function clampVolume(raw) {
+            const n = Number.parseInt(String(raw ?? ''), 10);
+            if (!Number.isFinite(n)) return 100;
+            return Math.min(VOLUME_MAX, Math.max(VOLUME_MIN, n));
+        }
+
+        /** Oldest pool slot past its cooldown, else the oldest slot (reuse).
+         *  All slots start cold, so a playing buffer is never overwritten
+         *  within 5s — far beyond the longest sound's 1.3s. */
+        function takePoolSlot() {
+            const now = Date.now();
+            let candidate = null;
+            let oldest = playPool[0];
+            for (const slot of playPool) {
+                if (slot.usedAt < oldest.usedAt) oldest = slot;
+                if (now - slot.usedAt > POOL_COOLDOWN_MS &&
+                    (candidate === null || slot.usedAt < candidate.usedAt)) {
+                    candidate = slot;
+                }
+            }
+            const slot = candidate ?? oldest;
+            slot.usedAt = now;
+            return slot;
+        }
+
+        function play(scenarioKey) {
+            try {
+                const cfg = scope !== null && scope.get() ? { ...DEFAULT_CONFIG, ...scope.get() } : { ...DEFAULT_CONFIG };
+                const group = cfg[scenarioKey];
+                if (group === undefined || group === null || group === 'off') { diag(`play ${scenarioKey}: off/empty`); return; }
+                const now = Date.now();
+                const prev = lastPlay.get(scenarioKey) ?? 0;
+                if (now - prev < THROTTLE_MS) { diag(`play ${scenarioKey}: throttled`); return; }
+                lastPlay.set(scenarioKey, now);
+                const file = join(SOUND_DIR, `${group}-${SCENARIO_FILE[scenarioKey]}.wav`);
+                const volume = clampVolume(cfg.volume);
+                let source = wavCache.get(file);
+                if (source === undefined) {
+                    source = readFileSync(file);
+                    wavCache.set(file, source);
+                }
+                const buffer = scaleWav(source, volume);
+                const slot = takePoolSlot();
+                slot.buf = buffer; // keep alive while winmm plays it
+                loaded ??= loadWin32();
+                const result = loaded.playSound(buffer, null, SND_MEMORY | SND_ASYNC | SND_NODEFAULT);
+                diag(`play ${scenarioKey}: group=${group} file=${file} volume=${volume}% winmm=${result}`);
+            }
+            catch (error) {
+                diag(`play FAIL ${scenarioKey}: ${error instanceof Error ? error.message : String(error)}`);
+                ctx.logger.warn(`chime: play failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+
+        // ── session/event bus listener (one subscription, all sessions) ─
+        // Diag keeps only low-volume events: assistant/chunk fires hundreds of
+        // times per second and would grow the log unboundedly.
+        const DIAG_TYPES = new Set([
+            'user/message', 'turn/start', 'turn/end', 'assistant/message',
+            'tool/call', 'tool/result', 'step/start', 'step/end', 'request/header',
+        ]);
+        function onSessionEvent(session, event) {
+            const type = event?.type;
+            if (DIAG_TYPES.has(type)) diag(`session/event type=${type} session=${sessionIdOf(session) ?? '?'}`);
+            if (type === 'tool/call' && event?.data?.name === 'ask_user_question') {
+                // The maid invoked the user-question module: the user has to
+                // answer something — cue them even when the terminal is blurred.
+                diag(`ask_user_question detected (session=${sessionIdOf(session) ?? '?'})`);
+                play(focused ? 'askFocus' : 'askBlur');
+            }
+            else if (type === 'turn/end') {
+                // agent-loop emits exactly one turn/end per assistant round
+                // (assistant/message would fire once per tool step — noise).
+                // Subagent children have their own stream; a parent's turn is
+                // what the user waits on, so their sound would be noise too.
+                if (isSubagentSession(session)) return;
+                play(focused ? 'doneFocus' : 'doneBlur');
+            }
+        }
+        ctx.on('session/event', onSessionEvent);
+        diag('session/event listener attached');
+
+        // ── focus polling (console-window handle based) ───────────────
+        function startFocus() {
+            if (focusStarted) return;
+            try {
+                const w = loadWin32();
+                focusStarted = true;
+                focusTimer = setInterval(() => {
+                    try {
+                        const isFocused = isTerminalFocused(w);
+                        if (isFocused !== focused) {
+                            focused = isFocused;
+                            ctx.logger.debug(`chime: terminal ${focused ? 'focused' : 'blurred'}`);
+                        }
+                    }
+                    catch {
+                        // transient Win32 failure — keep the last known state
+                    }
+                }, 750);
+            }
+            catch (error) {
+                ctx.logger.warn(`chime: focus detection unavailable (always treated as focused): ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+
+        // ── service-readiness poll ────────────────────────────────────
+        function tryOnce() {
+            // settings namespace + settings section
+            if (scope === null) {
+                const settings = ctx.get('settings');
+                if (settings !== undefined) {
+                    try {
+                        scope = settings.register('chime', Config);
+                        diag('settings namespace registered');
+                        ctx.logger.info('chime: settings namespace registered');
+                        // preview: play the newly selected group for the changed scenario
+                        let prev = { ...DEFAULT_CONFIG };
+                        try { prev = { ...DEFAULT_CONFIG, ...scope.get() }; } catch { /* ignore */ }
+                        scope.watch((next) => {
+                            const merged = { ...DEFAULT_CONFIG, ...next };
+                            let played = false;
+                            for (const key of ['doneFocus', 'doneBlur', 'askFocus', 'askBlur']) {
+                                if (merged[key] !== undefined && wrappedPrev[key] !== merged[key] && merged[key] !== 'off') {
+                                    play(key);
+                                    played = true;
+                                }
+                            }
+                            // Volume-only change: preview one live scenario so the
+                            // user hears the new level immediately (group-change
+                            // previews above take precedence).
+                            if (!played && merged.volume !== wrappedPrev.volume) {
+                                const key = ['doneFocus', 'doneBlur', 'askFocus', 'askBlur']
+                                    .find(k => merged[k] !== undefined && merged[k] !== 'off');
+                                if (key !== undefined) play(key);
+                            }
+                            wrappedPrev = { ...merged };
+                        });
+                    }
+                    catch (error) {
+                        ctx.logger.warn(`chime: settings register failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+            if (!sectionRegistered) {
+                const sections = ctx.get('tuiSettingsSections');
+                if (sections !== undefined) {
+                    try {
+                        sectionDisposer = registerSection(sections);
+                        sectionRegistered = true;
+                    }
+                    catch (error) {
+                        ctx.logger.warn(`chime: settings section failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+            startFocus();
+
+            // done?
+            if (scope !== null && sectionRegistered && focusStarted) {
+                if (retryTimer !== null) { clearInterval(retryTimer); retryTimer = null; }
+                diag('readiness complete');
+            }
+            else if (++attempts >= RETRY_LIMIT) {
+                diag(`readiness timeout (settings=${scope !== null}, section=${sectionRegistered}, focus=${focusStarted})`);
+                ctx.logger.warn(`chime: services did not all appear within ${(RETRY_LIMIT * RETRY_MS) / 1000}s (settings=${scope !== null}, section=${sectionRegistered}, focus=${focusStarted})`);
+                if (retryTimer !== null) { clearInterval(retryTimer); retryTimer = null; }
+            }
+        }
+
+        retryTimer = setInterval(tryOnce, RETRY_MS);
+        tryOnce();
+
+        yield () => {
+            if (retryTimer !== null) clearInterval(retryTimer);
+            if (focusTimer !== null) clearInterval(focusTimer);
+            try { sectionDisposer?.(); } catch { /* best-effort */ }
+            // The session/event listener is owned by this activation: cordis
+            // removes it on fiber teardown, nothing else to do.
+        };
+    }, 'chime lifecycle');
+}

package/lib/wav.js

@@ -0,0 +1,72 @@
+/**
+ * dsh-chime — WAV gain scaling (pure functions, no I/O).
+ *
+ * `scaleWav` scales a RIFF/WAVE (PCM, 16-bit) buffer's samples by
+ * `volumePercent / 100` with 16-bit saturation, preserving the original
+ * layout (header and unknown chunks untouched, only the `data` block is
+ * rewritten). The result can be handed to PlaySoundW with SND_MEMORY.
+ *
+ * >100% gain saturates at ±32767 — a short notification tone tolerates the
+ * clipping; a soft-limiter pass could be a future refinement.
+ *
+ * @module dsh-chime/wav
+ */
+
+const FORMAT_PCM = 1;
+
+/** Read a RIFF chunk; returns `{ header, size }` (header = chunk payload offset). */
+function findChunk(buf, id, from) {
+    let off = from;
+    while (off + 8 <= buf.length) {
+        if (buf.toString('ascii', off, off + 4) === id) {
+            return { header: off + 8, size: buf.readUInt32LE(off + 4) };
+        }
+        const size = buf.readUInt32LE(off + 4);
+        off += 8 + size + (size % 2); // chunks pad to even lengths
+    }
+    return null;
+}
+
+/**
+ * Scale the PCM samples of a WAV buffer by `volumePercent / 100`.
+ *
+ * Supports PCM only (format 1, any channel count, 16-bit samples — exactly
+ * what `scripts/gen-sounds.mjs` produces). 100% returns the input buffer
+ * unchanged; the caller keeps the buffer alive as long as it is in use.
+ *
+ * @param {Buffer} wav - Source WAV (RIFF/WAVE, PCM 16-bit).
+ * @param {number|string} volumePercent - 0..150 (clamped); anything invalid
+ *   falls back to 100.
+ * @returns {Buffer} The scaled buffer (same Buffer for 100%, otherwise a copy).
+ */
+export function scaleWav(wav, volumePercent) {
+    if (!Buffer.isBuffer(wav)) throw new TypeError('scaleWav: expected a Buffer');
+    if (wav.length < 44) throw new Error('scaleWav: not a WAV (too short)');
+    if (wav.toString('ascii', 0, 4) !== 'RIFF' || wav.toString('ascii', 8, 12) !== 'WAVE') {
+        throw new Error('scaleWav: not a RIFF/WAVE file');
+    }
+    const fmt = findChunk(wav, 'fmt ', 12);
+    const data = findChunk(wav, 'data', 12);
+    if (fmt === null || data === null) throw new Error('scaleWav: missing fmt or data chunk');
+    const format = fmt.header + 0;
+    const channels = fmt.header + 2;
+    const bitsPerSample = fmt.header + 14;
+    if (wav.readUInt16LE(format) !== FORMAT_PCM) throw new Error('scaleWav: only PCM WAV supported');
+    if (wav.readUInt16LE(bitsPerSample) !== 16) throw new Error('scaleWav: only 16-bit PCM supported');
+    if (wav.readUInt16LE(channels) < 1) throw new Error('scaleWav: bad channel count');
+
+    const raw = Number.parseFloat(String(volumePercent ?? ''));
+    const value = Number.isFinite(raw) ? raw : 100;
+    const gain = Math.min(150, Math.max(0, value)) / 100;
+    if (gain === 1) return wav;
+
+    const count = Math.floor(data.size / 2);
+    const out = Buffer.allocUnsafe(wav.length);
+    wav.copy(out);
+    for (let i = 0; i < count; i++) {
+        const at = data.header + i * 2;
+        const scaled = Math.round(wav.readInt16LE(at) * gain);
+        out.writeInt16LE(scaled > 32767 ? 32767 : scaled < -32768 ? -32768 : scaled, at);
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "dsh-chime-sound",
+  "version": "0.2.0",
+  "description": "Notification sounds for dsh-tui: distinct tones for conversation done / user question, focused vs unfocused terminal, 4 selectable sound groups, master volume 0-150% in 5% steps, settings section, zh/en",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VviLliAm-qwq/dsh-chime.git"
+  },
+  "author": "VviLliAm-qwq",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-tui",
+    "deepseek-harness",
+    "notification",
+    "sound",
+    "chime",
+    "win32"
+  ],
+  "files": [
+    "lib",
+    "assets",
+    "dsh-plugin.json",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "koffi": "^3.1.0"
+  }
+}