@jxgame2020/dsh-token-quota 0.1.22 → 0.1.23

package/lib/index.js

@@ -23,6 +23,12 @@ import { LlmError } from "@deepseek-ai/dsh-llm";
 const TOKEN_QUOTA_NAMESPACE = "token-quota";
 /** Stable machine code thrown from `agent/request` when a model is over its daily cap. */
 const TOKEN_QUOTA_EXCEEDED_CODE = "TOKEN_QUOTA_EXCEEDED";
+/** Default music settings: silent until the user flips the panel switch. */
+const TOKEN_QUOTA_DEFAULT_MUSIC = {
+	enabled: false,
+	volume: .5,
+	style: "major"
+};
 /** Build the stable per-model key shared by the counter, settings, and snapshot. */
 function tokenQuotaKey(provider, model) {
 	return `${provider}/${model}`;
@@ -207,7 +213,16 @@ const TOKEN_QUOTA_SETTINGS_SCHEMA = z.object({
 	]).default("stop"),
 	checkUpdates: z.boolean().default(true),
 	dimWhenIdle: z.boolean().default(false),
-	reset: z.any().default(null)
+	reset: z.any().default(null),
+	music: z.object({
+		enabled: z.boolean().default(TOKEN_QUOTA_DEFAULT_MUSIC.enabled),
+		volume: z.number().min(0).max(1).default(TOKEN_QUOTA_DEFAULT_MUSIC.volume),
+		style: z.union([
+			"major",
+			"minor",
+			"pentatonic"
+		]).default(TOKEN_QUOTA_DEFAULT_MUSIC.style)
+	}).default({ ...TOKEN_QUOTA_DEFAULT_MUSIC })
 });
 /** Two-digit zero-pad helper. */
 function pad2(value) {
@@ -263,7 +278,8 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 		monitored: [],
 		onFull: "stop",
 		checkUpdates: true,
-		dimWhenIdle: false
+		dimWhenIdle: false,
+		music: { ...TOKEN_QUOTA_DEFAULT_MUSIC }
 	});
 	/** Whether update checks are enabled (mirrors the settings document). */
 	checkUpdates = true;
@@ -291,6 +307,10 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 	disposeRouteCheck;
 	/** Disposer for the optional clear-log route (`POST /token-quota/clear-log`). */
 	disposeRouteClear;
+	/** Disposer for the optional music-event route (`GET /token-quota/events`, SSE). */
+	disposeRouteEvents;
+	/** Live SSE subscribers receiving streamed music actions. */
+	musicClients = /* @__PURE__ */ new Set();
 	/** Disposer for the webServer-arrival watcher when the service mounts later. */
 	disposeRouteWatcher;
 	/**
@@ -312,7 +332,12 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 							onFull: doc.onFull === "switchPriority" ? "switchAll" : doc.onFull ?? "stop",
 							checkUpdates: doc.checkUpdates ?? true,
 							dimWhenIdle: doc.dimWhenIdle ?? false,
-							reset: doc.reset ?? void 0
+							reset: doc.reset ?? void 0,
+							music: {
+								enabled: doc.music?.enabled ?? TOKEN_QUOTA_DEFAULT_MUSIC.enabled,
+								volume: doc.music?.volume ?? TOKEN_QUOTA_DEFAULT_MUSIC.volume,
+								style: doc.music?.style ?? TOKEN_QUOTA_DEFAULT_MUSIC.style
+							}
 						};
 					};
 				},
@@ -439,6 +464,32 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 				});
 			}
 		});
+		this.disposeRouteEvents = server.register({
+			kind: "exact",
+			path: "/token-quota/events",
+			handler: (req, res) => {
+				res.writeHead(200, {
+					"content-type": "text/event-stream",
+					"cache-control": "no-store",
+					"connection": "keep-alive"
+				});
+				this.musicClients.add(res);
+				res.write(": token-quota music stream\n\n");
+				req.on("close", () => {
+					this.musicClients.delete(res);
+				});
+			}
+		});
+	}
+	/** Broadcast one action to every open SSE music subscriber. */
+	pushMusicAction(action) {
+		if (this.musicClients.size === 0) return;
+		const data = `event: action\ndata: ${JSON.stringify(action)}\n\n`;
+		for (const res of this.musicClients) try {
+			res.write(data);
+		} catch {
+			this.musicClients.delete(res);
+		}
 	}
 	/** Query the npm registry and rebuild the cached upgrade info (coalesced). */
 	refreshUpgrade() {
@@ -453,7 +504,7 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 		return this.upgradeCheck;
 	}
 	async doRefreshUpgrade() {
-		const current = "0.1.22";
+		const current = "0.1.23";
 		let latest;
 		try {
 			const response = await fetch(REGISTRY_LATEST_URL, {
@@ -585,20 +636,69 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 		return typeof limit === "number" && Number.isInteger(limit) && limit > 0 ? limit : 0;
 	}
 	onSessionEvent(session, event) {
-		if (event.type === "request/header") {
-			const { provider, model } = event.data.header.config;
-			this.headerKeys.set(session, tokenQuotaKey(provider, model));
-			return;
-		}
-		if (event.type === "assistant/message" && event.data.usage !== void 0) {
-			const key = this.headerKeys.get(session);
-			if (key === void 0) return;
-			if (!this.isMonitored(key)) return;
-			const tokens = usageTokens(event.data.usage);
-			if (tokens <= 0) return;
-			this.rollCycleIfNeeded();
-			this.usage[key] = (this.usage[key] ?? 0) + tokens;
-			this.scheduleWrite();
+		const sessionId = String(session.id);
+		switch (event.type) {
+			case "turn/start":
+				this.pushMusicAction({
+					type: "turn/start",
+					sessionId
+				});
+				break;
+			case "turn/end":
+				this.pushMusicAction({
+					type: "turn/end",
+					sessionId,
+					reason: event.data.reason.kind
+				});
+				break;
+			case "step/start":
+				this.pushMusicAction({
+					type: "step/start",
+					sessionId
+				});
+				break;
+			case "request/header": {
+				const { provider, model } = event.data.header.config;
+				this.headerKeys.set(session, tokenQuotaKey(provider, model));
+				this.pushMusicAction({
+					type: "request/header",
+					sessionId,
+					provider,
+					model
+				});
+				return;
+			}
+			case "tool/call":
+				this.pushMusicAction({
+					type: "tool/call",
+					sessionId,
+					name: event.data.name
+				});
+				break;
+			case "tool/result":
+				this.pushMusicAction({
+					type: "tool/result",
+					sessionId,
+					error: event.data.error !== void 0
+				});
+				break;
+			case "assistant/message":
+				this.pushMusicAction({
+					type: "assistant/message",
+					sessionId,
+					interrupted: event.data.interrupted === true
+				});
+				if (event.data.usage !== void 0) {
+					const key = this.headerKeys.get(session);
+					if (key === void 0) return;
+					if (!this.isMonitored(key)) return;
+					const tokens = usageTokens(event.data.usage);
+					if (tokens <= 0) return;
+					this.rollCycleIfNeeded();
+					this.usage[key] = (this.usage[key] ?? 0) + tokens;
+					this.scheduleWrite();
+				}
+				break;
 		}
 	}
 	/**
@@ -750,6 +850,11 @@ var TokenQuotaService = class TokenQuotaService extends Service {
 		if (this.disposeRouteLog !== void 0) this.disposeRouteLog();
 		if (this.disposeRouteCheck !== void 0) this.disposeRouteCheck();
 		if (this.disposeRouteClear !== void 0) this.disposeRouteClear();
+		if (this.disposeRouteEvents !== void 0) this.disposeRouteEvents();
+		for (const res of this.musicClients) try {
+			res.end();
+		} catch {}
+		this.musicClients.clear();
 		this.flush();
 	}
 	safeSplit(key) {

package/lib/types/client/TokenQuotaPanel.d.ts

@@ -1,6 +1,6 @@
 import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
-import type { TokenQuotaFullAction, TokenQuotaReset } from '@jxgame2020/dsh-token-quota/types';
+import type { TokenQuotaFullAction, TokenQuotaMusicStyle, TokenQuotaReset } from '@jxgame2020/dsh-token-quota/types';
 import type { createTokenQuotaPanelStore } from './store.ts';
 /** Injected business face: data loading and mutations wired in `apply`. */
 export interface TokenQuotaPanelInjected {
@@ -20,6 +20,12 @@ export interface TokenQuotaPanelInjected {
     setCheckUpdates: (enabled: boolean) => void;
     /** Persist whether the panel dims while the pointer is away / typing. */
     setDimWhenIdle: (enabled: boolean) => void;
+    /** Toggle the live music output (requires a user gesture to start audio). */
+    setMusicEnabled: (enabled: boolean) => void;
+    /** Change the live-music master volume 0..1. */
+    setMusicVolume: (volume: number) => void;
+    /** Change the live-music harmonic style. */
+    setMusicStyle: (style: TokenQuotaMusicStyle) => void;
     /** Ask the Host to check the registry right now, then refresh the snapshot. */
     checkUpdatesNow: () => void;
     /** Ask the Host to clear log entries before a date, then refresh the log. */
@@ -32,5 +38,5 @@ export type TokenQuotaPanelComponentProps = PropsRuntime<'shell.overlay'> & Prop
  * @param props - composed slot props.
  * @returns the panel element tree.
  */
-export declare function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored, setOnFull, setReset, setCheckUpdates, checkUpdatesNow, clearLogBefore, setDimWhenIdle, useStore, actions, useSessions, }: TokenQuotaPanelComponentProps): import("react").JSX.Element;
+export declare function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored, setOnFull, setReset, setCheckUpdates, checkUpdatesNow, clearLogBefore, setDimWhenIdle, setMusicEnabled, setMusicVolume, setMusicStyle, useStore, actions, useSessions, }: TokenQuotaPanelComponentProps): import("react").JSX.Element;
 //# sourceMappingURL=TokenQuotaPanel.d.ts.map

package/lib/types/client/TokenQuotaPanel.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
  * Token-quota floating panel, registered into the frame-wide `shell.overlay`
  * seat. Renders one row per MONITORED model of the current session's
@@ -86,7 +86,7 @@ function loadPanelPos() {
  * @param props - composed slot props.
  * @returns the panel element tree.
  */
-export function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored, setOnFull, setReset, setCheckUpdates, checkUpdatesNow, clearLogBefore, setDimWhenIdle, useStore, actions, useSessions, }) {
+export function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored, setOnFull, setReset, setCheckUpdates, checkUpdatesNow, clearLogBefore, setDimWhenIdle, setMusicEnabled, setMusicVolume, setMusicStyle, useStore, actions, useSessions, }) {
     const [collapsed, setCollapsed] = useState(false);
     const [drafts, setDrafts] = useState({});
     const [editingKey, setEditingKey] = useState(null);
@@ -129,6 +129,9 @@ export function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored,
     const onFull = useStore(s => s.onFull);
     const checkUpdates = useStore(s => s.checkUpdates);
     const dimWhenIdle = useStore(s => s.dimWhenIdle);
+    const musicEnabled = useStore(s => s.musicEnabled);
+    const musicVolume = useStore(s => s.musicVolume);
+    const musicStyle = useStore(s => s.musicStyle);
     const upgrade = useStore(s => s.upgrade);
     const upgradeDismissed = useStore(s => s.upgradeDismissed);
     const checkingUpdates = useStore(s => s.checkingUpdates);
@@ -294,7 +297,7 @@ export function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored,
         : '';
     return (_jsxs("div", { ref: panelRef, className: `${css.panel}${panelDimClass !== '' ? ` ${panelDimClass}` : ''}`, style: panelPos !== null ? { left: panelPos.x, top: panelPos.y, right: 'auto' } : undefined, onPointerEnter: () => { setHovered(true); }, onPointerLeave: () => { setHovered(false); }, children: [_jsxs("div", { className: css.header, onPointerDown: (event) => { beginDrag(event, panelRef.current, applyPanelPos); }, children: [_jsxs("div", { className: css.headerText, children: [_jsxs("div", { className: css.title, children: [t('title'), __TOKEN_QUOTA_VERSION__ !== undefined && __TOKEN_QUOTA_VERSION__ !== '' && (upgrade !== null
                                         ? (_jsxs("span", { className: `${css.version} ${css.versionNew}`, title: t('upgradeAvailableHint'), children: ["v", __TOKEN_QUOTA_VERSION__, " \u2192 v", upgrade.latestVersion] }))
-                                        : (_jsxs("span", { className: css.version, children: ["v", __TOKEN_QUOTA_VERSION__] })))] }), _jsx("div", { className: css.subtitle, children: t('subtitle') })] }), _jsxs("div", { className: css.headerActions, onPointerDown: (event) => { event.stopPropagation(); }, children: [_jsx("button", { type: "button", className: css.settingsBtn, onClick: () => { actions.setLogOpen(true); }, children: t('logs') }), _jsx("button", { type: "button", className: css.settingsBtn, onClick: openSettings, children: t('settings') }), _jsx("button", { type: "button", className: css.collapse, onClick: () => { setCollapsed(true); }, children: t('collapse') })] })] }), _jsxs("div", { className: css.body, children: [loading && _jsx("div", { className: css.notice, children: t('loading') }), error !== null && _jsx("div", { className: css.noticeError, children: error }), fullNotice !== null && (_jsx("div", { className: css.fullNotice, role: "alert", children: fullNotice })), upgrade !== null && !upgradeDismissed && (_jsxs("div", { className: `${css.upgradeBanner}${upgradeFlash ? ` ${css.upgradeBannerFlash}` : ''}`, role: "alert", children: [_jsx("div", { className: css.upgradeBannerText, children: t('upgradeAvailable').replace('{version}', upgrade.latestVersion) }), _jsx("div", { className: css.upgradeCommands, children: upgrade.commands.map(cmd => (_jsxs("div", { className: css.upgradeCommandRow, children: [_jsx("code", { className: css.upgradeCommand, children: cmd }), _jsx("button", { type: "button", className: `${css.copyBtn}${copiedCmd === cmd ? ` ${css.copyBtnDone}` : ''}`, onClick: () => { copyUpgradeCommand(cmd); }, children: copiedCmd === cmd ? t('copied') : t('copy') })] }, cmd))) }), _jsx("div", { className: css.upgradeHint, children: t('upgradeHint') }), _jsx("button", { type: "button", className: css.upgradeClose, onClick: () => { actions.setUpgradeDismissed(true); }, "aria-label": t('close'), children: "\u00D7" })] })), !loading && error === null && visibleRows.length === 0 && (_jsx("div", { className: css.notice, children: monitored !== null && monitored.length === 0 ? t('noMonitored') : t('waiting') })), visibleRows.map((row) => {
+                                        : (_jsxs("span", { className: css.version, children: ["v", __TOKEN_QUOTA_VERSION__] })))] }), _jsx("div", { className: css.subtitle, children: t('subtitle') })] }), _jsxs("div", { className: css.headerActions, onPointerDown: (event) => { event.stopPropagation(); }, children: [_jsx("button", { type: "button", className: `${css.settingsBtn}${musicEnabled ? ` ${css.settingsBtnActive}` : ''}`, title: t('musicHint'), onClick: () => { setMusicEnabled(!musicEnabled); }, children: musicEnabled ? '🔊' : '♪' }), _jsx("button", { type: "button", className: css.settingsBtn, onClick: () => { actions.setLogOpen(true); }, children: t('logs') }), _jsx("button", { type: "button", className: css.settingsBtn, onClick: openSettings, children: t('settings') }), _jsx("button", { type: "button", className: css.collapse, onClick: () => { setCollapsed(true); }, children: t('collapse') })] })] }), _jsxs("div", { className: css.body, children: [loading && _jsx("div", { className: css.notice, children: t('loading') }), error !== null && _jsx("div", { className: css.noticeError, children: error }), fullNotice !== null && (_jsx("div", { className: css.fullNotice, role: "alert", children: fullNotice })), upgrade !== null && !upgradeDismissed && (_jsxs("div", { className: `${css.upgradeBanner}${upgradeFlash ? ` ${css.upgradeBannerFlash}` : ''}`, role: "alert", children: [_jsx("div", { className: css.upgradeBannerText, children: t('upgradeAvailable').replace('{version}', upgrade.latestVersion) }), _jsx("div", { className: css.upgradeCommands, children: upgrade.commands.map(cmd => (_jsxs("div", { className: css.upgradeCommandRow, children: [_jsx("code", { className: css.upgradeCommand, children: cmd }), _jsx("button", { type: "button", className: `${css.copyBtn}${copiedCmd === cmd ? ` ${css.copyBtnDone}` : ''}`, onClick: () => { copyUpgradeCommand(cmd); }, children: copiedCmd === cmd ? t('copied') : t('copy') })] }, cmd))) }), _jsx("div", { className: css.upgradeHint, children: t('upgradeHint') }), _jsx("button", { type: "button", className: css.upgradeClose, onClick: () => { actions.setUpgradeDismissed(true); }, "aria-label": t('close'), children: "\u00D7" })] })), !loading && error === null && visibleRows.length === 0 && (_jsx("div", { className: css.notice, children: monitored !== null && monitored.length === 0 ? t('noMonitored') : t('waiting') })), visibleRows.map((row) => {
                         const state = barStateOf(row);
                         const pct = row.limit > 0 ? Math.min(100, Math.round((row.used / row.limit) * 100)) : 0;
                         const barClass = state === 'over'
@@ -334,7 +337,7 @@ export function TokenQuotaPanel({ t, load, setLimit, selectModel, setMonitored,
                                                 hour: reset?.hour ?? 0,
                                                 minute: Number(event.target.value),
                                             });
-                                        }, children: Array.from({ length: 12 }, (_, i) => i * 5).map(minute => (_jsxs("option", { value: minute, children: [String(minute).padStart(2, '0'), " \u5206"] }, minute))) })] })] }), _jsxs("div", { className: css.dialogSection, children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("input", { type: "checkbox", checked: dimWhenIdle, onChange: (event) => { setDimWhenIdle(event.target.checked); } }), _jsx("span", { children: t('dimWhenIdleLabel') })] }), _jsx("div", { className: css.dialogHint, children: t('dimWhenIdleHint') })] }), _jsxs("div", { className: css.dialogSection, children: [_jsxs("div", { className: css.checkUpdatesRow, children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("input", { type: "checkbox", checked: checkUpdates, onChange: (event) => { setCheckUpdates(event.target.checked); } }), _jsx("span", { children: t('checkUpdatesLabel') })] }), _jsx("button", { type: "button", className: css.checkBtn, disabled: checkingUpdates, onClick: checkUpdatesNow, children: checkingUpdates
+                                        }, children: Array.from({ length: 12 }, (_, i) => i * 5).map(minute => (_jsxs("option", { value: minute, children: [String(minute).padStart(2, '0'), " \u5206"] }, minute))) })] })] }), _jsxs("div", { className: css.dialogSection, children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("input", { type: "checkbox", checked: dimWhenIdle, onChange: (event) => { setDimWhenIdle(event.target.checked); } }), _jsx("span", { children: t('dimWhenIdleLabel') })] }), _jsx("div", { className: css.dialogHint, children: t('dimWhenIdleHint') })] }), _jsxs("div", { className: css.dialogSection, children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("input", { type: "checkbox", checked: musicEnabled, onChange: (event) => { setMusicEnabled(event.target.checked); } }), _jsx("span", { children: t('musicLabel') })] }), _jsx("div", { className: css.dialogHint, children: t('musicHint') }), musicEnabled && (_jsxs(_Fragment, { children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("span", { children: t('musicVolume') }), _jsx("input", { type: "range", min: 0, max: 1, step: 0.05, value: musicVolume, onChange: (event) => { setMusicVolume(Number(event.target.value)); } })] }), _jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("span", { children: t('musicStyle') }), _jsxs("select", { value: musicStyle, onChange: (event) => { setMusicStyle(event.target.value); }, children: [_jsx("option", { value: "major", children: t('musicStyleMajor') }), _jsx("option", { value: "minor", children: t('musicStyleMinor') }), _jsx("option", { value: "pentatonic", children: t('musicStylePentatonic') })] })] })] }))] }), _jsxs("div", { className: css.dialogSection, children: [_jsxs("div", { className: css.checkUpdatesRow, children: [_jsxs("label", { className: css.checkUpdatesLabel, children: [_jsx("input", { type: "checkbox", checked: checkUpdates, onChange: (event) => { setCheckUpdates(event.target.checked); } }), _jsx("span", { children: t('checkUpdatesLabel') })] }), _jsx("button", { type: "button", className: css.checkBtn, disabled: checkingUpdates, onClick: checkUpdatesNow, children: checkingUpdates
                                             ? t('checkingUpdates')
                                             : lastCheckResult === 'up-to-date'
                                                 ? t('checkUpToDate')

package/lib/types/client/index.js

@@ -1,5 +1,6 @@
 import { createTokenQuotaPanelStore } from "./store.js";
 import { TokenQuotaPanel } from "./TokenQuotaPanel.js";
+import { TokenQuotaMusic } from "./music.js";
 import { en, zh } from "./locales.js";
 export { mergeModelRows } from "./store.js";
 /** Dictionary namespace owning the panel copy. */
@@ -35,6 +36,28 @@ export function apply(ctx) {
     let lastMonitored = null;
     let lastOnFull = 'stop';
     let lastReset = null;
+    // Live music engine: subscribes to the plugin's SSE action stream and
+    // composes from host events. Web Audio plays by default; a detected MIDI
+    // output is driven simultaneously.
+    const music = new TokenQuotaMusic();
+    const sse = new EventSource('/token-quota/events');
+    sse.addEventListener('action', (event) => {
+        let action;
+        try {
+            action = JSON.parse(event.data);
+        }
+        catch {
+            return;
+        }
+        // Only play actions for the currently-visible session; a root overlay
+        // panel isn't bound to a specific session, but its display tracks
+        // useSessions(s => s.current), so keeping the soundtrack on the same
+        // session avoids a cacophony from background conversations.
+        if (lastSessionId !== undefined && action.sessionId !== String(lastSessionId))
+            return;
+        music.onAction(action);
+    });
+    ctx.effect(() => () => { sse.close(); }, 'token-quota-ui: music SSE');
     const keyOf = (selection) => {
         if (selection === null)
             return undefined;
@@ -190,6 +213,13 @@ export function apply(ctx) {
         bound?.setCheckUpdates(doc?.checkUpdates ?? true);
         bound?.setDimWhenIdle(doc?.dimWhenIdle ?? false);
         bound?.setReset(lastReset);
+        const musicSettings = { ...{ enabled: false, volume: 0.5, style: 'major' }, ...(doc?.music ?? {}) };
+        music.setEnabled(musicSettings.enabled);
+        music.setVolume(musicSettings.volume);
+        music.setStyle(musicSettings.style);
+        bound?.setMusicEnabled(musicSettings.enabled);
+        bound?.setMusicVolume(musicSettings.volume);
+        bound?.setMusicStyle(musicSettings.style);
         void fetch('/token-quota', { headers: { accept: 'application/json' } }).then((response) => {
             if (!response.ok) {
                 bound?.setError(`quota route: ${String(response.status)}`);
@@ -257,6 +287,29 @@ export function apply(ctx) {
         bound?.setDimWhenIdle(enabled);
         void scope.set('dimWhenIdle', enabled);
     };
+    const setMusicEnabled = (enabled) => {
+        const doc = scope.getSnapshot().value;
+        const current = { ...{ enabled: false, volume: 0.5, style: 'major' }, ...(doc?.music ?? {}) };
+        current.enabled = enabled;
+        void scope.set('music', current);
+        // First enable: start audio inside this user gesture (the panel switch
+        // click) so the AudioContext can resume; the settings pull that follows
+        // applies enabled/volume/style to the engine.
+        if (enabled)
+            void music.ensureStarted();
+    };
+    const setMusicVolume = (volume) => {
+        const doc = scope.getSnapshot().value;
+        const current = { ...{ enabled: false, volume: 0.5, style: 'major' }, ...(doc?.music ?? {}) };
+        current.volume = Math.max(0, Math.min(1, volume));
+        void scope.set('music', current);
+    };
+    const setMusicStyle = (style) => {
+        const doc = scope.getSnapshot().value;
+        const current = { ...{ enabled: false, volume: 0.5, style: 'major' }, ...(doc?.music ?? {}) };
+        current.style = style;
+        void scope.set('music', current);
+    };
     /** Ask the Host to check the registry right now, then refresh the snapshot. */
     const checkUpdatesNow = () => {
         bound?.setCheckingUpdates(true);
@@ -344,6 +397,7 @@ export function apply(ctx) {
         return {
             load, setLimit, selectModel, setMonitored, setOnFull, setReset,
             setCheckUpdates, checkUpdatesNow, clearLogBefore, setDimWhenIdle,
+            setMusicEnabled, setMusicVolume, setMusicStyle,
         };
     };
     ctx.slots.inject('shell.overlay', () => ctx.slots.register({

package/lib/types/client/locales.d.ts

@@ -66,6 +66,13 @@ export declare const zh: {
     checkUpdatesLabel: string;
     dimWhenIdleLabel: string;
     dimWhenIdleHint: string;
+    musicLabel: string;
+    musicHint: string;
+    musicVolume: string;
+    musicStyle: string;
+    musicStyleMajor: string;
+    musicStyleMinor: string;
+    musicStylePentatonic: string;
     checkUpdatesNow: string;
     checkingUpdates: string;
     checkUpToDate: string;
@@ -135,6 +142,13 @@ export declare const en: {
     checkUpdatesLabel: string;
     dimWhenIdleLabel: string;
     dimWhenIdleHint: string;
+    musicLabel: string;
+    musicHint: string;
+    musicVolume: string;
+    musicStyle: string;
+    musicStyleMajor: string;
+    musicStyleMinor: string;
+    musicStylePentatonic: string;
     checkUpdatesNow: string;
     checkingUpdates: string;
     checkUpToDate: string;

package/lib/types/client/locales.js

@@ -66,6 +66,13 @@ export const zh = {
     checkUpdatesLabel: '自动检查更新',
     dimWhenIdleLabel: '失焦时窗口透明',
     dimWhenIdleHint: '鼠标移开面板时降低不透明度，输入文字时更透明；鼠标悬停恢复',
+    musicLabel: '动作音乐',
+    musicHint: '根据 Harness 动作实时作曲：请求开始、工具调用、回合结束等（需点击开关启动音频；检测到 MIDI 输出时同步发送 MIDI）',
+    musicVolume: '音量',
+    musicStyle: '风格',
+    musicStyleMajor: '大调',
+    musicStyleMinor: '小调',
+    musicStylePentatonic: '五声',
     checkUpdatesNow: '立即检查',
     checkingUpdates: '检查中…',
     checkUpToDate: '已是最新',
@@ -133,6 +140,13 @@ export const en = {
     checkUpdatesLabel: 'Check for updates automatically',
     dimWhenIdleLabel: 'Dim panel when unfocused',
     dimWhenIdleHint: 'Fade the panel out when the pointer is away (more while typing); hover to restore',
+    musicLabel: 'Action music',
+    musicHint: 'Live-composes from Harness actions: request starts, tool calls, turn ends, etc. (click the switch to start audio; a detected MIDI output is driven as well)',
+    musicVolume: 'Volume',
+    musicStyle: 'Style',
+    musicStyleMajor: 'Major',
+    musicStyleMinor: 'Minor',
+    musicStylePentatonic: 'Pentatonic',
     checkUpdatesNow: 'Check now',
     checkingUpdates: 'Checking…',
     checkUpToDate: 'Up to date',

package/lib/types/client/music.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Live-composed soundtrack driven by host actions (turns, steps, tool calls,
+ * etc.). Outputs through Web Audio (built-in synthesis) by default, and also
+ * sends MIDI NoteOn/NoteOff to the first available MIDI output when one is
+ * detected (both play simultaneously when MIDI is present — use the panel
+ * volume for overall level, the MIDI output has its own gain on the receiver).
+ *
+ * The composition is intentionally simple: a fixed chord progression under a
+ * scale-constrained melody, with one short musical gesture per host action.
+ * It is meant as gentle ambience while waiting for LLM responses, not as a
+ * full piece — everything stays in key so you can never hit a wrong note.
+ *
+ * @module @jxgame2020/dsh-token-quota/music
+ */
+import type { TokenQuotaMusicAction, TokenQuotaMusicStyle } from '../types.ts';
+/** Live-composed music engine driven by host actions. */
+export declare class TokenQuotaMusic {
+    private audio;
+    private midiOutput;
+    private midiDetected;
+    private enabled;
+    private volume;
+    private style;
+    /** Current position in the chord progression (advances per step). */
+    private chordIndex;
+    /** Step counter — used for melody degree selection. */
+    private stepCount;
+    /** Tool counter — used for tool-note pitch. */
+    private toolCount;
+    /** Base MIDI note of the current key. C4 = middle C. */
+    private static readonly BASE_MIDI;
+    /** True once the audio context has been started (needs a user gesture). */
+    get started(): boolean;
+    /**
+     * Start the audio context and try to find a MIDI output.
+     * Must be called inside a user gesture (the panel switch click) so the
+     * AudioContext can resume. Safe to call multiple times.
+     */
+    ensureStarted(): Promise<boolean>;
+    setEnabled(value: boolean): void;
+    setVolume(value: number): void;
+    setStyle(value: TokenQuotaMusicStyle): void;
+    /** Handle one incoming host action and turn it into sound. */
+    onAction(action: TokenQuotaMusicAction): void;
+    private currentChordRoot;
+    private currentChordQuality;
+    /** Intervals of an ascending arpeggio from the chord root. */
+    private arpeggioDegrees;
+    /** Play one note: Web Audio + MIDI simultaneously when available. */
+    private playNote;
+    /** Play a three-note chord plus a bass octave below. */
+    private playChord;
+}
+//# sourceMappingURL=music.d.ts.map