@falling-ts/dsh-web-ding 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 falling-ts
+
+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.cn.md

@@ -0,0 +1,61 @@
+# dsh-web-ding
+
+一个 DSH Cordis 插件:当 **agent 回合结束**(所有轮次安静、转入空闲)时,在
+**浏览器里**播放一声"叮"。声音**完全由前端 JavaScript(Web Audio API)合成**——
+Node/后端从不发声,也不走 Windows/系统通知。
+
+架构参照 [dsh-force-compact](https://github.com/falling-ts/dsh-force-compact):
+纯监听器的 Host 半部 + 浏览器 client 半部,之间用官方
+`settings/document-updated` 镜像通道相连。
+
+## 工作方式
+
+| 层 | 行为 |
+|----|------|
+| Host(`index.js` + `src/`) | 监听 `agent/status` 的 **idle 转变**(全部轮次与子代理结束、下一次人为对话之前;新建会话从未运行过的首次 idle 与重复 idle tick 都保持静默)。向 `falling-ts-web-ding` 设置命名空间写入 `{ phase:'done', at, sessionId }`。绝不发声、绝不调用系统。 |
+| 浏览器(`web/client.js`) | 经 `settingsScope` 实时镜像命名空间;收到 `at` 严格更新的 `done` 信号后用 Web Audio API 合成一声短"叮"(三个正弦振荡器 + 指数衰减包络),经标签页播放。 |
+
+## 安装
+
+```bash
+dsh plugin --profile web add github:falling-ts/dsh-web-ding
+```
+
+(需要 Web 应用带上 client bundle——`package.json` 的 `dsh.client` 声明会自动
+完成。)
+
+## 配置(`falling-ts-web-ding` 命名空间,$DSH_HOME/settings.yaml)
+
+| 字段 | 类型 | 默认 | 含义 |
+|------|------|------|------|
+| `enabled` | boolean | `true` | 总开关(关闭时 Host 跳过发布)。 |
+| `volume` | number 0..1 | `0.7` | Web Audio 播放音量。 |
+| `freq` | number 80..4000 | `880` | "叮"的基频(Hz)。 |
+| `decayMs` | number 100..4000 | `900` | 音色衰减时长(ms)。 |
+
+也可以在 **设置 → 回合结束提示音** 面板里调整,面板带"试听"按钮。
+
+任何会话的 agent 回合结束(转入空闲)都会提示;同一会话内重复 idle tick 与新建后从未运行过的会话保持静默。
+
+## 浏览器自动播放策略
+
+浏览器要求一次用户手势后才允许出声。客户端在首次指针/按键交互(以及点击
+"试听"按钮)时预热 `AudioContext`,所以:与页面交互一次(或点一下试听),之后
+每次回合结束就能听到叮。后台标签页里的 AudioContext 可能被浏览器自身挂起——
+保持标签页可见才能听到声音。
+
+## 开发
+
+```bash
+# 作为开发覆盖层挂载(plain JS,无构建步骤)
+dsh web --patch $(pwd)/cordis.patch.yml   # 你的 CLI 支持该选项时
+# 或从本地路径安装
+dsh plugin --profile web add /path/to/dsh-web-ding
+```
+
+插件自身规则见 `AGENTS.md`(纯 Host 监听器、后端不发声、不弹系统通知、只用
+官方 settings 镜像通道通向浏览器)。
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,66 @@
+# dsh-web-ding
+
+A DSH Cordis plugin that plays a **"ding"** in the **browser** the moment an
+agent finishes (runs to idle). The sound is synthesized **entirely by front-end
+JavaScript (Web Audio API)** — the Node/Host side never plays audio and no
+Windows/system notification is used.
+
+Built by following the architecture of
+[dsh-force-compact](https://github.com/falling-ts/dsh-force-compact):
+a pure-listener Host half + a browser client half connected by the official
+`settings/document-updated` mirror channel.
+
+## What it does
+
+| Layer | What happens |
+|-------|--------------|
+| Host (`index.js` + `src/`) | Listens for the `agent/status` **idle transition** (all turns done, including sub-agents, before the next human turn; a fresh idle session that never ran, and repeated idle ticks, stay silent). Publishes `{ phase:'done', at, sessionId }` into the `falling-ts-web-ding` settings namespace. Never emits audio, never calls the OS. |
+| Browser (`web/client.js`) | Mirrors the namespace live via `settingsScope`. On a strictly-newer `done` signal it synthesizes a short `ding` (three sine oscillators + exponential decay envelopes) with the Web Audio API and plays it through the tab. |
+
+## Install
+
+```bash
+dsh plugin --profile web add github:falling-ts/dsh-web-ding
+```
+
+Requires the web app to ship the client bundle (the `dsh.client` declaration in
+`package.json` does that automatically).
+
+## Configuration (`falling-ts-web-ding` namespace, $DSH_HOME/settings.yaml)
+
+| Field | Type | Default | Meaning |
+|-------|------|---------|---------|
+| `enabled` | boolean | `true` | Master switch (Host skips publishing when off). |
+| `volume` | number 0..1 | `0.7` | Web Audio playback gain. |
+| `freq` | number 80..4000 | `880` | Fundamental frequency of the ding (Hz). |
+| `decayMs` | number 100..4000 | `900` | Tone decay length (ms). |
+
+Every session's agent turn end (transition to idle) rings; repeated idle ticks of an already-idle session and brand-new sessions that never ran stay silent.
+
+You can also adjust these from the **设置 → 回合结束提示音** panel, which
+includes a "试听" (preview) button.
+
+## Browser autoplay policy
+
+Browsers block audio until a user gesture. The client warms the
+`AudioContext` on the first pointer/key interaction (and on the preview
+button), so: interact with the page once (or press 试听) and you will hear the
+ding at every agent turn end. An audio context in a background tab may be
+suspended by the browser itself — keep the tab visible to hear the tone.
+
+## Development
+
+```bash
+# mount as a dev overlay (plain JS, no build step)
+dsh web --patch $(pwd)/cordis.patch.yml   # if supported by your CLI
+# or install from a local path
+dsh plugin --profile web add /path/to/dsh-web-ding
+```
+
+See `AGENTS.md` for the plugin's own rules (pure Host listener, no backend
+audio, no OS notification, only sanctioned settings-mirror channel to the
+browser).
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# Opt-in layer: mount the dsh-web-ding function plugin over the
+# current composition without changing shipped defaults.
+#
+#   dsh plugin --profile web add github:falling-ts/dsh-web-ding   # install
+#
+# The Host half is a pure listener on agent/status; it pushes a "agent
+# finished" signal into the falling-ts-web-ding settings namespace, which the
+# browser client half mirrors and answers with a Web-Audio "ding".
+
+- insert:
+    - id: web-ding
+      name: '@falling-ts/dsh-web-ding'

package/index.js

@@ -0,0 +1,140 @@
+/**
+ * dsh-web-ding — a DSH Cordis function plugin.
+ *
+ * Announces the moment an agent finishes: the Host half listens for the
+ * agent/status 'idle' TRANSITION (all turns done, including sub-agents, before
+ * the next human turn) and publishes a tiny 'done' signal into the
+ * `falling-ts-web-ding` settings namespace. The browser client half
+ * (web/client.js) mirrors that namespace live and answers the signal by
+ * synthesizing a short "ding" with the Web Audio API — ENTIRELY front-end JS.
+ *
+ * The Node/Host side deliberately never plays audio and never raises a
+ * Windows/system notification: the sound lives in the browser tab.
+ *
+ * Layout:
+ * - index.js              — this file; the Cordis plugin entry (listener registrations).
+ * - core/settings.js      — the `falling-ts-web-ding` settings namespace (parameters + schema).
+ * - core/signal.js        — the host→browser signal publisher (settings field write).
+ * - hooks/idle.js         — the `agent/status` idle-transition observer.
+ * - web/client.js         — the browser half: mirrors the namespace, plays the ding, registers a settings.section.
+ *
+ * @module @falling-ts/dsh-web-ding
+ */
+
+import { registerNamespace } from './src/core/settings.js'
+import { handleAgentStatus } from './src/hooks/idle.js'
+
+/** @type {string} the function plugin's display name. */
+export const name = 'web-ding'
+
+/**
+ * Register the `agent/status` listener and the `falling-ts-web-ding` settings
+ * namespace (the "回合结束提示音" surface).
+ *
+ * No `inject` is declared: the `settings` service arrives with the preset
+ * plane AFTER this plugin's boot-time effect runs, and a boot-time `inject`
+ * would fail the boot assertion (the same late-mount ordering documented by
+ * dsh-force-compact). The namespace registration is therefore lazy +
+ * idempotent: attempted at boot and again atop every `agent/status` emission,
+ * with a bounded self-cancelling retry while the service is still absent. The
+ * retry is installation bookkeeping (it settles and cancels itself on
+ * success) — not a persistent timer or long-lived state.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+const __applyInner = (ctx) => {
+  ctx.logger.info('[web-ding] apply START; settings=' + (ctx.get('settings') !== undefined ? 'present' : 'ABSENT'))
+
+  // ── Lazy namespace install (settings service may arrive after boot) ──────
+  const settingsState = { settled: false, installed: false }
+  const RETRY_DELAY_MS = 1000
+  const RETRY_MAX_ATTEMPTS = 30
+  const retryTimer = { value: undefined }
+  const tryRegisterOnce = async () => {
+    if (settingsState.settled) return
+    const settings = ctx.get('settings')
+    if (settings === undefined || typeof settings.register !== 'function') return // keep retrying
+    try {
+      const ok = await registerNamespace(ctx)
+      settingsState.settled = true
+      if (ok) {
+        settingsState.installed = true
+        ctx.logger.info('[web-ding] registered settings namespace "falling-ts-web-ding"')
+      } else {
+        ctx.logger.warn('[web-ding] settings present but schema build failed — namespace NOT registered')
+      }
+    } catch (error) {
+      const message = error instanceof Error ? (error.stack || error.message) : String(error)
+      ctx.logger.warn(`[web-ding] settings namespace registration threw — ${message}`)
+    }
+  }
+  const maybeRetryRegister = () => {
+    if (settingsState.settled || retryTimer.value !== undefined) return
+    let attempts = 0
+    const attempt = () => {
+      retryTimer.value = undefined
+      if (settingsState.settled) return
+      attempts += 1
+      void (async () => {
+        await tryRegisterOnce()
+        if (settingsState.settled) {
+          if (retryTimer.value !== undefined) clearTimeout(retryTimer.value)
+          retryTimer.value = undefined
+          return
+        }
+        if (attempts >= RETRY_MAX_ATTEMPTS) {
+          settingsState.settled = true // give up; agent/status listeners stay as safety net
+          return
+        }
+        retryTimer.value = setTimeout(attempt, RETRY_DELAY_MS)
+      })().catch(() => {})
+    }
+    attempt()
+  }
+  const maybeRegisterSettingsNamespace = () => {
+    if (settingsState.settled) return
+    void (async () => {
+      await tryRegisterOnce()
+      if (!settingsState.settled) maybeRetryRegister()
+    })().catch(() => {})
+  }
+  // Cancel any pending retry on teardown.
+  ctx.effect(() => () => {
+    if (retryTimer.value !== undefined) clearTimeout(retryTimer.value)
+  }, 'web-ding: settings install retry cleanup')
+
+  // Fire the eager attempt once NOW so a cold start with no agent traffic
+  // still lands the namespace (the client panel depends on it).
+  maybeRegisterSettingsNamespace()
+
+  // ── Turn-end ding: agent/status idle transition → publish 'done' signal ──
+  // agent/status is a SYNC event; the heavy work (settings write) is handed off
+  // to an async IIFE with its own catch so nothing escapes the dispatch.
+  ctx.on('agent/status', (payload) => {
+    maybeRegisterSettingsNamespace() // re-armed; cheap no-op once settled
+    void (async () => {
+      await handleAgentStatus(ctx, payload)
+    })().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error)
+      ctx.logger.warn(`[web-ding] agent/status handler degraded (swallowed) — ${message}`)
+    })
+  })
+
+  ctx.logger.info('[web-ding] apply END (listeners + namespace attempts done)')
+}
+
+/**
+ * Plugin entry.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export const apply = (ctx) => {
+  try {
+    return __applyInner(ctx)
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack || error.message) : String(error)
+    try {
+      ctx.logger.error(`[web-ding] apply FAILED — ${message}`)
+    } catch { /* never */ }
+    throw error
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@falling-ts/dsh-web-ding",
+  "version": "0.1.0",
+  "description": "DSH Cordis plugin: announces the moment an agent finishes (turns idle) by pushing a 'done' signal from the Host half into the falling-ts-web-ding settings namespace, which the browser client half mirrors live and answers with a synthesized 'ding' tone via the Web Audio API. The tone is played ENTIRELY by front-end JS in the browser — the Host/node backend never emits audio and no Windows/system notification is used.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./web/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "web/",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/falling-ts/dsh-web-ding.git"
+  },
+  "keywords": [
+    "dsh",
+    "cordis",
+    "agent",
+    "turn-end",
+    "idle",
+    "notification",
+    "ding",
+    "web-audio",
+    "sound",
+    "client"
+  ]
+}

package/src/core/settings.js

@@ -0,0 +1,141 @@
+/**
+ * dsh-web-ding settings — the "回合结束提示音" (turn-end ding) surface.
+ *
+ * User-tunable parameters are registered under the `falling-ts-web-ding`
+ * settings namespace (the `falling-ts-` prefix prevents collisions with
+ * other plugins' keys):
+ *
+ * - `enabled`  (boolean, default `true`): master switch. When `false` the
+ *   Host half still observes `agent/status` but skips publishing the signal,
+ *   so the browser never hears a ding.
+ * - `volume`   (number 0..1, default `0.7`): playback gain applied by the
+ *   browser client's Web Audio synth (a per-oscillator peak, not the master).
+ * - `freq`     (number 80..4000, default `880`): fundamental frequency of
+ *   the synthesized "ding" in Hz. The client stacks a soft higher-octave and
+ *   a faint bell partial on top automatically.
+ * - `decayMs`  (number 100..4000, default `900`): exponential-decay length
+ *   of the tone in milliseconds.
+ *
+ * The `signal` field is the PLUGIN-PRIVATE host→browser messenger (the same
+ * pattern dsh-force-compact uses for its `liveUi` field): the Host half is
+ * its only writer, the browser client never writes it, and it deliberately
+ * persists to settings.yaml like every other field (harmless cosmetic residue
+ * — the client's own last-at latch ignores anything it saw before load).
+ *
+ * @module @falling-ts/dsh-web-ding/settings
+ */
+
+/** The settings namespace key (settings.get / settings.register address). */
+export const NS = 'falling-ts-web-ding'
+
+/** The settings field carrying the host→browser turn-end signal. */
+export const SIGNAL_FIELD = 'signal'
+
+/** Defaults — also the base passed to settings.register. */
+export const DEFAULTS = Object.freeze({
+  enabled: true,
+  volume: 0.7,
+  freq: 880,
+  decayMs: 900,
+})
+
+/**
+ * Read ONE raw field of the namespace without a full parse. Never throws.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} field
+ * @returns {Promise<unknown>} the raw stored value, or `undefined` when the
+ *   settings service is not mounted or the field is unset.
+ */
+export async function readRawSetting(ctx, field) {
+  try {
+    const settings = ctx.get('settings')
+    if (settings === undefined || typeof settings.get !== 'function') return undefined
+    const value = settings.get(NS)
+    if (value === undefined || value === null) return undefined
+    if (typeof value !== 'object') return undefined
+    return value[field]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Resolve the schemastery `z` constructor, tolerating BOTH layouts:
+ *  - a monorepo/dev layout where `@deepseek-ai/schemastery` resolves as a
+ *    bare specifier;
+ *  - this plugin as a STANDALONE repo whose node_modules lacks schemastery
+ *    (it lives in the sibling `deepseek-harness/vendor/` copy). Then walk up
+ *    from this file looking for the vendored build and import it via a
+ *    file:// URL (required on Windows).
+ * @returns {Promise<object|undefined>} resolved `z`, or undefined.
+ */
+async function resolveZ() {
+  try {
+    const mod = await import('@deepseek-ai/schemastery')
+    const z = mod.default ?? mod
+    if (typeof z.object === 'function') return z
+  } catch { /* fall through to candidate 2 */ }
+  try {
+    const { fileURLToPath, pathToFileURL } = await import('node:url')
+    const { dirname, join } = await import('node:path')
+    const { existsSync } = await import('node:fs')
+    let dir = dirname(fileURLToPath(import.meta.url))
+    for (let hop = 0; hop < 8; hop += 1) {
+      const cand = join(dir, 'deepseek-harness/vendor/schemastery/lib/index.mjs')
+      if (existsSync(cand)) {
+        const mod = await import(pathToFileURL(cand).href)
+        const z = mod.default ?? mod
+        if (typeof z.object === 'function') return z
+      }
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  } catch { /* candidate 2 unavailable */ }
+  return undefined
+}
+
+/**
+ * Build the `falling-ts-web-ding` schema through @deepseek-ai/schemastery.
+ * @returns {Promise<((section: unknown) => unknown) & { toJSON: () => unknown } | null>}
+ */
+export async function buildSchema() {
+  try {
+    const z = await resolveZ()
+    if (z === undefined) return null
+    return z.object({
+      enabled: z.boolean().default(DEFAULTS.enabled),
+      volume: z.number().default(DEFAULTS.volume),
+      freq: z.number().default(DEFAULTS.freq),
+      decayMs: z.number().default(DEFAULTS.decayMs),
+      // TRANSIENT host→browser messenger (src/core/signal.js): host-written
+      // { phase:'done', at, sessionId }. z.any() because the vendored
+      // schemastery exposes only object/any/string/number/boolean/array.
+      signal: z.any(),
+    })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Register the namespace when a `settings` service is mounted. Idempotent.
+ * Falls back to a callable placeholder schema so the panel still loads when
+ * schemastery is unresolvable.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {Promise<boolean>}
+ */
+export async function registerNamespace(ctx) {
+  const settings = ctx.get('settings')
+  if (settings === undefined || typeof settings.register !== 'function') return false
+  const schema = await buildSchema()
+  const thirdArg = { base: { ...DEFAULTS } }
+  const placeholderSchema = (section) => section
+  placeholderSchema.toJSON = () => ({})
+  try {
+    settings.register(NS, schema !== null ? schema : placeholderSchema, thirdArg)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/core/signal.js

@@ -0,0 +1,66 @@
+/**
+ * Turn-end signal messenger — the plugin-private bridge between the HOST half
+ * ("this agent just finished") and the CLIENT half ("play the ding").
+ *
+ * Why settings at all
+ * ------------------
+ * The browser client half mirrors the `falling-ts-web-ding` namespace through
+ * `settingsScope.bind` → `createSnapshotStore`, so ANY field the Host writes
+ * here is reflected in the browser live (the SettingsScope revision-fencing
+ * contract, the same `settings/document-updated` broadcast dsh-force-compact
+ * rides for its liveUi badge). That is the ONLY sanctioned host→browser
+ * live-data channel an independent plugin bundle can use.
+ *
+ * The `signal` payload is deliberately minimal:
+ *   { phase: 'done', at: <monotonic epoch ms>, sessionId?: string }
+ * `at` doubles as the sequence number — the client ignores any signal older
+ * than the one it last played, so restarts and stale residue never re-ding.
+ *
+ * Guarantees:
+ *   • NEVER throws — a settings-service absence or a rejected write is caught
+ *     and logged at most once per lifetime (cosmetic only; the agent/status
+ *     dispatch proceeds untouched).
+ *   • Fire-and-forget from the caller's perspective.
+ *
+ * @module @falling-ts/dsh-web-ding/signal
+ */
+
+import { NS, SIGNAL_FIELD } from './settings.js'
+
+/** Process-local monotonic high-water mark so two same-millisecond idles can never collide. */
+let lastAt = 0
+
+/**
+ * Publish one "agent finished" signal onto the `signal` field of the
+ * `falling-ts-web-ding` namespace. THE host→browser delivery point.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string|undefined} sessionId the agent session id that just went idle
+ * @returns {Promise<void>}
+ */
+let warnedOnce = false
+export async function publishDingSignal(ctx, sessionId) {
+  try {
+    const settings = ctx.get('settings')
+    if (settings === undefined || typeof settings.update !== 'function') return
+    let at = Date.now()
+    if (at <= lastAt) at = lastAt + 1
+    lastAt = at
+    const signal = {
+      phase: 'done',
+      at,
+      ...(typeof sessionId === 'string' && sessionId !== '' ? { sessionId } : {}),
+    }
+    await settings.update(NS, { [SIGNAL_FIELD]: signal })
+    if (!warnedOnce) {
+      warnedOnce = true
+      try {
+        ctx.logger.debug(`[web-ding] signal published via ${NS}.${SIGNAL_FIELD} (at=${at})`)
+      } catch { /* logging must never propagate */ }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    try {
+      ctx.logger.warn(`[web-ding] signal publish failed (ignored, cosmetic only) — ${message}`)
+    } catch { /* never */ }
+  }
+}

package/src/hooks/idle.js

@@ -0,0 +1,70 @@
+/**
+ * The turn-end ding trigger — observes `agent/status` and publishes the
+ * "agent finished" signal exactly once per idle TRANSITION.
+ *
+ * Why the transition bookkeeping:
+ * - The agent starts idle for a fresh session (before any turn) — nobody
+ *   asked for a ding then, and a "new session created" ding would be noise.
+ * - The agent/status idle tick can repeat while a session stays idle (the
+ *   same recurrence dsh-force-compact documents for its idle compaction), so
+ *   the raw `status === 'idle'` guard alone would re-ding every tick.
+ *
+ * Two process-local latches (pure listener state, no timer, no persistence):
+ *   prevStatus: sessionId → last observed status (Map)
+ *   everBusy:   sessionIds that were observed in a non-idle status (Set)
+ * A signal is published only when BOTH hold: the previous status was NOT
+ * 'idle' (this is a genuine running→idle transition) AND the session was
+ * observed busy at least once (so the very first idle after session creation
+ * stays silent).
+ *
+ * @module @falling-ts/dsh-web-ding/turn-end
+ */
+
+import { readRawSetting } from '../core/settings.js'
+import { publishDingSignal } from '../core/signal.js'
+
+/** @type {Map<string,string>} sessionId → last observed agent/status. */
+const prevStatus = new Map()
+/** @type {Set<string>} sessionIds that have been observed busy (non-idle). */
+const everBusy = new Set()
+
+/**
+ * Handle one `agent/status` emission. Never throws out of the listener (any
+ * anomaly logs and settles).
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{agent: import('@deepseek-ai/dsh-agent').Agent, status: string}} payload
+ * @returns {Promise<void>}
+ */
+export async function handleAgentStatus(ctx, payload) {
+  try {
+    if (payload === null || typeof payload !== 'object') return
+    const agent = payload.agent
+    const status = payload.status
+    if (typeof status !== 'string') return
+    const session = (agent && typeof agent === 'object') ? agent.session : undefined
+    const sid = (session && typeof session.id === 'string') ? session.id : '?'
+
+    if (status !== 'idle') {
+      if (status === 'running') everBusy.add(sid)
+      prevStatus.set(sid, status)
+      return
+    }
+
+    const prev = prevStatus.get(sid)
+    prevStatus.set(sid, 'idle')
+    if (prev === 'idle') return // repeated idle tick — already handled
+    if (!everBusy.has(sid)) return // fresh session that never ran — no ding
+
+    const enabled = await readRawSetting(ctx, 'enabled')
+    if (enabled === false) {
+      ctx.logger.debug(`[web-ding] ${sid}: idle transition ignored — enabled=false`)
+      return
+    }
+    await publishDingSignal(ctx, sid)
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack || error.message) : String(error)
+    try {
+      ctx.logger.warn(`[web-ding] handleAgentStatus degraded (swallowed) — ${message}`)
+    } catch { /* never */ }
+  }
+}

package/web/client.js

@@ -0,0 +1,247 @@
+/**
+ * dsh-web-ding 浏览器半部:回合结束提示音(设置分区 + Web Audio 播放器)。
+ *
+ * 这是一个闭包工厂 artifact:window.__ModuleLoader__.load({ id, factory }),
+ * factory(require) 通过注入的 require 解析外部模块(react、client-runtime),
+ * 并返回插件面 { name, inject, apply }。宿主半部(根 index.js)与本文件是
+ * 同一 package 的两个面:宿主半部由 main 入口加载,本文件由 exports["./client"]
+ * 导出,经 dsh.client 声明被 client module 系统自动组成并服务。
+ *
+ * 职责:
+ *   1. settingsScope 镜像 falling-ts-web-ding 命名空间,订阅其快照翻转——这
+ *      就是宿主的"事件时钟":宿主在 agent/status idle 转变时写入 signal 字段,
+ *      经 settings/document-updated 广播到达这里。
+ *   2. 检测新的 'done' 信号(at 严格大于本页面最后播放的 at 才响应,首帧只做
+ *      基线不播放,重启残留/重复快照都不会重复响)后,用 Web Audio API 合成
+ *      一声"叮"。声音 100% 由浏览器 JS 生成——宿主 Node 端从不发声,也不发
+ *      Windows/系统通知。
+ *   3. 注册 settings.section "回合结束提示音" 分区:开关、音量、音色频率、
+ *      时长与"试听"按钮(点击试听同时完成音频解锁)。
+ *
+ * 浏览器自动播放策略:AudioContext 需要一次用户手势才能出声。首次
+ * pointerdown/keydown 做一次性预热(创建并 resume),"试听"按钮点击本身
+ * 也是一次手势,所以点过试听或与本页面交互过后即可正常听到回合结束的叮。
+ *
+ * @module @falling-ts/dsh-web-ding/client
+ */
+
+window.__ModuleLoader__.load({
+  id: "@falling-ts/dsh-web-ding",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    const React = require("react");
+    const h = React.createElement;
+    // 基线外部(web 平台预载):把 settingsScope 镜像成 uSES 安全的 SnapshotStore。
+    const { createSnapshotStore } = require("@deepseek-ai/dsh-client-runtime/client");
+
+    /** 宿主侧设置命名空间(settings.get 读取的键)。 */
+    const NS_SETTINGS = "falling-ts-web-ding";
+
+    /** 必需服务(slots 提供分区注册;settingsScope 由 ui-settings 提供)。 */
+    const inject = ["slots", "settingsScope"];
+
+    // ── Web Audio "叮" 播放器 --------------------------------------------------
+    // 完全前端合成:无音频资产、无系统通知。三个正弦振荡器叠加:
+    // 基频 + 高八度泛音(轻)+ 2.5 倍铃感泛音(更轻),各自带指数衰减包络。
+    let audio = null;
+    function ensureAudio() {
+      if (audio) {
+        if (audio.ctx.state === "closed") audio = null;
+        else return audio;
+      }
+      const Ctx = window.AudioContext || window.webkitAudioContext;
+      if (!Ctx) return null;
+      const ctx = new Ctx();
+      audio = { ctx };
+      return audio;
+    }
+    // 用户手势一次性预热:创建 AudioContext 并 resume,解除自动播放静音。
+    function warmup() {
+      const a = ensureAudio();
+      if (a && a.ctx.state === "suspended") {
+        void a.ctx.resume().catch(() => {});
+      }
+    }
+    if (typeof window !== "undefined") {
+      window.addEventListener("pointerdown", warmup, { once: true });
+      window.addEventListener("keydown", warmup, { once: true });
+    }
+    /**
+     * 播放一声"叮"。
+     * @param {{volume?: number, freq?: number, decayMs?: number}} opts
+     * @returns {boolean} 是否成功调度(不支持 Web Audio 时返回 false)
+     */
+    function playDing(opts) {
+      const o = opts || {};
+      const a = ensureAudio();
+      if (!a) return false;
+      const ctx = a.ctx;
+      if (ctx.state === "suspended") void ctx.resume().catch(() => {});
+      const volume = Math.min(1, Math.max(0, Number(o.volume) || 0.7));
+      const freq = Math.min(4000, Math.max(80, Number(o.freq) || 880));
+      const decay = Math.min(4000, Math.max(100, Number(o.decayMs) || 900)) / 1000;
+      const t0 = ctx.currentTime + 0.02;
+      const schedule = (f, peak, start, dur) => {
+        const osc = ctx.createOscillator();
+        const g = ctx.createGain();
+        osc.type = "sine";
+        osc.frequency.setValueAtTime(f, start);
+        g.gain.setValueAtTime(0.0001, start);
+        g.gain.exponentialRampToValueAtTime(Math.max(0.0001, peak), start + 0.012);
+        g.gain.exponentialRampToValueAtTime(0.0001, start + dur);
+        osc.connect(g);
+        g.connect(ctx.destination);
+        osc.start(start);
+        osc.stop(start + dur + 0.05);
+      };
+      schedule(freq, volume * 0.55, t0, decay);                    // 基频主体
+      schedule(freq * 2.0, volume * 0.2, t0, decay * 0.75);        // 高八度泛音
+      schedule(freq * 2.5, volume * 0.07, t0 + 0.004, decay * 0.6); // 铃感泛音
+      return true;
+    }
+
+    // ── 命名空间快照 → 信号检测 → 播放 ------------------------------------------
+    // lastAt:本页面最后响应过的 signal.at。首帧(页面加载时已存在的残留)只做
+    // 基线、不播放;之后 at 严格增长的新 'done' 信号才叮一声。
+    let lastAt = null;
+    function maybePlayFromValue(value) {
+      if (!value || typeof value !== "object") return;
+      const sig = value.signal;
+      if (!sig || typeof sig !== "object") return;
+      if (sig.phase !== "done") return;
+      const at = typeof sig.at === "number" ? sig.at : 0;
+      if (lastAt === null) {
+        lastAt = at; // 首帧基线:页面打开前已发生的信号不播
+        return;
+      }
+      if (!(at > lastAt)) return;
+      lastAt = at;
+      if (value.enabled !== false) {
+        playDing({ volume: value.volume, freq: value.freq, decayMs: value.decayMs });
+      }
+    }
+
+    // ── 设置分区 UI --------------------------------------------------------------
+    const divider = "rgba(0,0,0,0.08)";
+    const hintColor = "rgba(0,0,0,0.45)";
+    const gridCols = "200px minmax(0,1fr)";
+    const wrapStyle = { padding: "4px 0" };
+    const titleStyle = { margin: "2px 0 2px", fontSize: 15, lineHeight: 1.4 };
+    const introStyle = { margin: "0 0 6px", color: hintColor, lineHeight: 1.65, fontSize: 13, maxWidth: 680 };
+    const rowStyle = { display: "grid", gridTemplateColumns: gridCols, columnGap: 16, rowGap: 5, padding: "13px 0", borderBottom: "1px solid " + divider, alignItems: "center" };
+    const lastRowStyle = { ...rowStyle, borderBottom: "none" };
+    const labelStyle = { fontSize: 13.5, fontWeight: 500, lineHeight: 1.35 };
+    const controlStyle = { display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap" };
+    const hintStyle = { gridColumn: "1 / 3", color: hintColor, fontSize: 12, lineHeight: 1.55 };
+    const valueStyle = { fontVariantNumeric: "tabular-nums", fontSize: 13, color: hintColor, minWidth: 52, textAlign: "right" };
+    const buttonStyle = { padding: "6px 14px", borderRadius: 8, border: "1px solid rgba(0,0,0,0.22)", background: "transparent", cursor: "pointer", fontSize: 13, fontWeight: 500 };
+    const inputRangeStyle = { flex: 1, minWidth: 140 };
+
+    function DingSection(props) {
+      // The renderer binds the injected hooks compartment ('ding' key) into a
+      // use<Name> hook; the store is the bare observable, so a selector reads
+      // its latest snapshot (the sanctioned client pattern, see force-compact).
+      const { update, play } = props;
+      const snap = props.useDing((s) => s);
+      const value = snap.value;
+      const ph = hintStyle;
+      if (snap.status === "unavailable") {
+        return h("div", { style: wrapStyle },
+          h("h2", { style: titleStyle }, "回合结束提示音"),
+          h("p", { style: ph }, "设置不可用(宿主端未注册 falling-ts-web-ding 命名空间)。"));
+      }
+      if (snap.status === "loading" || value === undefined) {
+        return h("div", { style: wrapStyle },
+          h("h2", { style: titleStyle }, "回合结束提示音"),
+          h("p", { style: ph }, "加载中…"));
+      }
+      const disabled = !snap.writable;
+      const v = (value && typeof value === "object") ? value : {};
+      const pct = (n) => Math.round((Number(n) || 0) * 100) + "%";
+      const sliderRow = (labelText, props2, display) => h("div", { key: labelText, style: rowStyle },
+        h("span", { style: labelStyle }, labelText),
+        h("span", { style: controlStyle },
+          h("input", { type: "range", disabled: disabled, style: inputRangeStyle, ...props2 }),
+          h("span", { style: valueStyle }, display)),
+      );
+      return h("div", { style: wrapStyle },
+        h("h2", { style: titleStyle }, "回合结束提示音"),
+        h("p", { style: introStyle }, "agent 回合结束时(转入空闲)由浏览器 JS 播放一声合成“叮”——纯前端 Web Audio,宿主不发声、不弹 Windows/系统通知。"),
+        h("div", { key: "enabled", style: rowStyle },
+          h("span", { style: labelStyle }, "启用"),
+          h("span", { style: controlStyle },
+            h("input", {
+              type: "checkbox",
+              checked: v.enabled !== false,
+              disabled: disabled,
+              onChange: (ev) => update("enabled", ev.target.checked),
+            })),
+        ),
+        sliderRow("音量",
+          { min: 0, max: 1, step: 0.05, value: Number(v.volume) || 0.7, disabled: disabled, onChange: (ev) => update("volume", Number(ev.target.value)) },
+          pct(v.volume)),
+        sliderRow("音色频率(Hz)",
+          { min: 120, max: 2000, step: 10, value: Number(v.freq) || 880, disabled: disabled, onChange: (ev) => update("freq", Number(ev.target.value)) },
+          Math.round(Number(v.freq) || 880) + " Hz"),
+        sliderRow("衰减时长(ms)",
+          { min: 100, max: 2000, step: 50, value: Number(v.decayMs) || 900, disabled: disabled, onChange: (ev) => update("decayMs", Number(ev.target.value)) },
+          Math.round(Number(v.decayMs) || 900) + " ms"),
+        h("div", { key: "preview", style: lastRowStyle },
+          h("span", { style: labelStyle }, "试听"),
+          h("span", { style: controlStyle },
+            h("button", {
+              style: buttonStyle,
+              disabled: disabled,
+              onClick: () => play({ volume: v.volume, freq: v.freq, decayMs: v.decayMs }),
+            }, "播放一声")),
+        ),
+        h("p", { style: { gridColumn: "1 / 3", color: hintColor, fontSize: 12, lineHeight: 1.55 } },
+          "浏览器自动播放策略:首次与页面交互(点击/按键)或点击试听后,回合结束提示音才会出声。设置写入 $DSH_HOME/settings.yaml 的 falling-ts-web-ding 段。"));
+    }
+
+    /**
+     * 注册分区、绑定命名空间、把信号接进播放器。
+     * @param {import('@deepseek-ai/cordis').Context} ctx - client 根上下文。
+     */
+    function apply(ctx) {
+      const scope = ctx.settingsScope.bind({ namespace: NS_SETTINGS });
+      const store = createSnapshotStore({ status: "loading", value: undefined, writable: false });
+      const derive = () => {
+        try {
+          const s = scope.getSnapshot();
+          if (s === undefined || s === null || typeof s !== "object") return;
+          store.update((d) => {
+            d.status = s.status;
+            d.value = s.value;
+            d.writable = s.writable;
+          });
+          if (s.status === "ready") maybePlayFromValue(s.value);
+        } catch { /* never let a cosmetic derive take down the panel */ }
+      };
+      const unsub = scope.subscribe(derive);
+      derive();
+      ctx.effect(() => unsub, "web-ding: scope subscription");
+      const injected = () => ({
+        hooks: { ding: store },
+        update: (field, value) => scope.set(field, value),
+        play: (opts) => {
+          warmup();
+          return playDing(opts || {});
+        },
+      });
+      ctx.slots.inject("settings.section", () => ctx.slots.register({
+        name: "settings.section",
+        id: "web-ding",
+        order: 80,
+        label: () => "回合结束提示音",
+        inject: injected,
+      }, DingSection));
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  }
+});