@daobrew/wellness-mcp 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @daobrew/wellness-mcp
+
+Biometric stress detection & TCM-guided recovery for developers using Claude Code.
+
+Reads your health data (Apple Watch, Oura Ring), detects stress patterns through Traditional Chinese Medicine theory, and plays therapeutic breathing music with binaural beats — right inside your coding session.
+
+## Install
+
+```bash
+npm install -g @daobrew/wellness-mcp
+npx daobrew-wellness-setup
+```
+
+Setup asks two questions (data source + ambient mode). Done in 30 seconds.
+
+## What it does
+
+- **Detects stress** from real biometrics (HRV, heart rate, steps, sleep)
+- **Maps to TCM patterns**: Wood/Tension, Fire/Overdrive, Earth/Stagnation, Metal/Constriction, Water/Depletion
+- **Plays breathing music** with binaural beats (4Hz theta) and breath-paced volume modulation
+- **Works inside Claude Code** — no app switching, no popups
+
+## Usage
+
+**On-demand** — ask anytime:
+```
+/stress     → check your current wellness state
+/breathe    → start a breathing session for your top stress pattern
+/stop       → stop current session
+```
+
+**Ambient** — auto-plays when stress is detected:
+- Enable with: `"enable ambient mode"` in Claude Code
+- Requires headphones (binaural beats need stereo separation)
+- 30-minute cooldown between sessions
+- Say `"disable wellness"` to turn off
+
+## Data Sources
+
+| Source | Data | Setup |
+|--------|------|-------|
+| **Apple Watch** | HRV, HR, steps, sleep | Install [DaoBrew Health Sync](https://testflight.apple.com/join/6XTNFvv5) on iPhone |
+| **Oura Ring** | HRV, HR, sleep, readiness | Say `"connect oura"` in Claude Code |
+
+Without a wearable, only step count is available (Earth/Spleen pattern only).
+
+## 9 Tools + 3 Prompts
+
+| Tool | Description |
+|------|-------------|
+| `daobrew_get_wellness_state` | Current Yin/Yang balance + Five Element stress scores |
+| `daobrew_get_element_detail` | Deep-dive evidence for a specific stress pattern |
+| `daobrew_start_breathing_session` | Start guided breathing with audio playback |
+| `daobrew_get_session_result` | Post-session HRV improvement metrics |
+| `daobrew_get_session_history` | Recent session history and trends |
+| `daobrew_stop_session` | Stop current breathing session |
+| `daobrew_status` | Server mode, headphones, preferences, active session |
+| `daobrew_set_monitoring` | Configure ambient mode, volume, cooldown |
+| `daobrew_connect_source` | Connect Oura Ring or Apple Watch |
+
+## How it works
+
+```
+Apple Watch / Oura
+        ↓
+  DaoBrew Backend (Gemini LLM + TCM scoring)
+        ↓
+  MCP Server (local, TypeScript)
+        ↓
+  Claude Code ←→ afplay/mpv (binaural + breath modulation)
+```
+
+## Privacy
+
+- Only scored wellness data — no raw health records in agent context
+- Health data stored locally (`~/.daobrew/`)
+- Headphone detection prevents accidental speaker playback
+- Ambient mode requires explicit opt-in
+
+## Configuration
+
+Change settings in Claude Code: `"set volume to 0.5"`, `"change cooldown to 15 minutes"`, `"disable wellness"`
+
+Or edit `~/.daobrew/prefs.json` directly.
+
+## Development
+
+```bash
+cd daobrew-wellness-mcp
+npm install
+npm run build
+npm test          # 74 tests
+npm run setup     # interactive setup
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: daobrew-wellness
+description: "DaoBrew Wellness is a biometric stress detection and micro-recovery skill powered by Traditional Chinese Medicine theory. It reads health data (Apple Health, Health Connect, or DaoBrew Cuff) and identifies five stress patterns: Wood/Tension, Fire/Overdrive, Earth/Stagnation, Metal/Constriction, Water/Depletion. Use this skill whenever: the user has been coding for 30+ minutes without a break, the user mentions feeling stressed/tired/burned out/unfocused, the user asks about their health or energy state, you notice a long unbroken work session, the user asks for a break or recovery suggestion, OR at regular intervals during extended work sessions (every 30 minutes recommended). This skill should be checked proactively — don't wait for the user to ask. Developers who install this skill want their agent to watch out for them."
+---
+
+# DaoBrew Wellness — Agent Skill for Biometric Stress Detection & Recovery
+
+## What This Skill Does
+
+DaoBrew reads the user's real-time biometric data and returns a structured wellness assessment based on two systems:
+
+1. **Yin/Yang Balance** — Two independent 0-100 scores measuring Recovery Reservoir (Yin, parasympathetic) and Vitality Engine (Yang, sympathetic activity). Both can be high or low simultaneously — they are NOT opposites.
+
+2. **Five Element Patterns** (Wu Xing) — Five organ-system detectors mapped to TCM, any combination can co-occur:
+
+| Element | Organ | What It Detects | Key Signal |
+|---------|-------|----------------|------------|
+| **Wood** | Liver 肝 | Qi stagnation, fight-or-flight stuck ON | HRV below baseline + erratic HR |
+| **Fire** | Heart 心 | Heart Fire rising, restlessness | Elevated resting HR at night |
+| **Earth** | Spleen 脾 | Spleen Qi sluggish, low energy | Low step count + low active energy |
+| **Metal** | Lung 肺 | Lung Qi faltering, shallow breathing | Abnormal respiratory rate |
+| **Water** | Kidney 肾 | Kidney Essence low, deep depletion | HRV declining over 2+ weeks |
+
+## Two Modes
+
+### On-Demand Mode (default)
+User-initiated. Triggered by `/breathe`, `/stress`, or explicit user request. Uses `force_refresh: true` for fresh data.
+
+### Ambient Mode (proactive)
+Agent-initiated. Requires explicit user opt-in via `daobrew_set_monitoring({ ambient_optin: true })`. Use cached data (no `force_refresh`). Present results in one brief line. Never interrupt mid-task — only at natural breakpoints. Ambient sessions use separate cooldown from on-demand.
+
+**Block list** — Do NOT trigger ambient checks:
+- While the user is actively debugging
+- Mid-sentence in a conversation
+- During urgent/time-sensitive tasks the user flagged
+- During git operations (rebase, merge, conflict resolution)
+- If the user said "stop checking" or "I don't want wellness updates"
+
+## Available Tools (9 tools)
+
+### `daobrew_get_wellness_state`
+Returns the user's current wellness snapshot.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `force_refresh` | boolean | No | Bypass 30-min cache. Use `true` for on-demand, `false`/omit for ambient. |
+
+**Returns:** Yin/Yang scores, quadrant, element scores, top signal, recommendation, `cache_age_seconds`, optional `active_session`.
+
+**Quadrant meanings:**
+- `peak` (Yin ≥ 50, Yang ≥ 50) → "In Flow"
+- `pushing_it` (Yin < 50, Yang ≥ 50) → "Pushing It"
+- `recharging` (Yin ≥ 50, Yang < 50) → "Recharging"
+- `burnout` (Yin < 50, Yang < 50) → "Running on Empty"
+
+### `daobrew_get_element_detail`
+Returns detailed evidence for a specific stress pattern.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `element` | string | Yes | `wood`, `fire`, `earth`, `metal`, `water` |
+
+### `daobrew_start_breathing_session`
+Starts a guided resonance breathing session matched to the user's stress pattern.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `element` | string | Yes | Stress pattern to address |
+| `tier` | string | No | `text` (terminal), `audio` (system audio), `full` (browser PWA). Default: `audio` |
+| `mode` | string | No | `ambient` (agent-initiated) or `ondemand` (user-requested). Default: `ondemand` |
+| `force` | boolean | No | Bypass cooldown timer for acute stress spikes. Default: `false` |
+
+**Guard sequence** (checked in order):
+1. `disabled` → rejects with `status: "disabled"`
+2. `mode=ambient` without `ambient_optin` → rejects with `status: "requires_optin"`
+3. Session already running → rejects with `status: "session_active"`
+4. Cooldown active (unless `force=true`) → rejects with `status: "cooldown"`
+5. No headphones detected (audio/full tier, unless `headphones_trusted`) → rejects with `status: "no_headphones"`
+
+If audio playback fails, automatically falls back to text tier with explanation.
+
+### `daobrew_get_session_result`
+Retrieves the outcome of a completed breathing session including HRV changes.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | string | Yes | From `start_breathing_session` |
+
+### `daobrew_get_session_history`
+Returns recent session history and trends.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `days` | integer | No | Lookback window. Default: 7 |
+
+### `daobrew_stop_session`
+Stops the current breathing session.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | string | No | Stops current if omitted |
+
+### `daobrew_status`
+Returns server mode, connected data sources, headphone status, preferences, active session. Use for first-run onboarding.
+
+**Parameters:** none
+
+### `daobrew_set_monitoring`
+Persists user preferences to `~/.daobrew/prefs.json`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ambient_optin` | boolean | No | Enable/disable ambient mode |
+| `disabled` | boolean | No | Disable all wellness checks |
+| `preferred_volume` | number | No | Audio volume 0.0-1.0 |
+| `cooldown_minutes` | integer | No | Minutes between sessions |
+| `headphones_trusted` | boolean | No | Skip headphone detection |
+| `voiceover` | boolean | No | Enable/disable intro voiceover |
+
+### `daobrew_connect_source`
+Connect a wearable data source for real biometric data.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | Yes | `oura`, `google_fit`, `apple_watch` |
+
+- **Oura/Google Fit**: Opens OAuth flow in browser, waits for callback
+- **Apple Watch**: Returns TestFlight install link for DaoBrew Health Sync iPhone app
+
+## Prompts (3)
+
+| Prompt | Description |
+|--------|-------------|
+| `/breathe` | Check wellness state and start a breathing session for top stress pattern |
+| `/stress` | Check current stress levels and biometric wellness state |
+| `/stop` | Stop the current breathing session |
+
+## How to Present Wellness Information
+
+Keep it brief and natural. Do NOT dump raw JSON. Translate data into conversational TCM language.
+
+**Good — proactive (ambient), mild concern:**
+> Quick Qi check — you've been in "Pushing It" for a while. Yin Running Low (35), Yang Moving (72). Wood Qi activated. Want a 5-min breathing reset?
+
+**Good — proactive (ambient), no concern:**
+> Quick Qi check — In Flow. All clear.
+
+**Good — on-demand, user asked:**
+> Right now your Yin (recovery) is at 35 — Running Low. Yang (activity) is 72 — Moving. That puts you in "Pushing It" territory.
+>
+> Wood · Liver is activated (score 68) — low HRV, Liver Qi stagnation. Deep breathing would help. Want to try it?
+
+**Bad — data dump:**
+> Your daobrew_get_wellness_state returned yin=35, yang=72, quadrant=pushing_it...
+
+**After a session:**
+> Nice — HRV improved 46%, heart rate dropped 11bpm. Wood Qi rebalancing, score 68 → 42.
+
+## Safety & Privacy
+
+- **Never hallucinate biometrics** — only report what the API returns
+- **Never share health data** in outputs visible to others
+- **Frame as wellness observations**, never medical advice ("biometrics suggest" not "you have")
+- **Scored output only** — no raw health data in agent context
+- **Disable immediately** when user says "stop checking": call `daobrew_set_monitoring({ disabled: true })`
+
+## Data Sources
+
+| Source | Connection Method | Data |
+|--------|------------------|------|
+| **Oura Ring** | OAuth via `daobrew_connect_source({ source: "oura" })` | HRV, HR, sleep, readiness |
+| **Google Fit** | OAuth via `daobrew_connect_source({ source: "google_fit" })` | HR, activity, sleep |
+| **Apple Watch** | TestFlight iPhone app via `daobrew_connect_source({ source: "apple_watch" })` | HRV, HR, steps, respiratory, sleep |
+
+## Data Tiers
+
+| Tier | Hardware | What Works | Limitations |
+|------|----------|-----------|-------------|
+| **Tier 1** | Phone only | Yang score, Earth pattern, basic screen/movement | Yin stays neutral, reduced Wood/Fire/Water accuracy |
+| **Tier 2** | + Wearable | Full Yin/Yang, all five patterns, session HRV | — |
+| **Tier 3** | + DaoBrew Cuff | All Tier 2 + thermal/haptic, continuous HRV | — |
+
+The `data_tier` field tells you the user's tier. Don't reference HRV data for Tier 1 users.
+
+## Troubleshooting
+
+- **No data**: Health permissions not granted or companion app not running
+- **Stale data** (`cache_age_seconds` very high): Use `force_refresh: true`
+- **All elements at 0**: System needs 3-7 days to establish baselines — skip proactive checks
+- **Mock mode**: Results are simulated. Summary prefixed with `[Mock]`. Connect a wearable for real data.

package/dist/src/audio.d.ts

@@ -0,0 +1,13 @@
+import { Element } from "./types.js";
+export interface PlaybackResult {
+    status: "playing" | "no_file" | "no_player" | "error";
+    pid: number | null;
+    file?: string;
+    error?: string;
+}
+/** Map task type to audio file suffix */
+type TaskType = "breathing" | "meditation" | "zhanZhuang";
+export declare function playAudio(element: Element, task?: TaskType, volume?: number): Promise<PlaybackResult>;
+export declare function stopPlayback(): boolean;
+export declare function generateTextBreathingScript(element: Element, durationSec: number, bpm: number): string;
+export {};

package/dist/src/audio.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playAudio = playAudio;
+exports.stopPlayback = stopPlayback;
+exports.generateTextBreathingScript = generateTextBreathingScript;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const types_js_1 = require("./types.js");
+// Bundled audio inside the package (works standalone)
+const PACKAGE_AUDIO_DIR = (0, path_1.join)(__dirname, "..", "..", "audio");
+// User-level cache (e.g. prebaked binaural versions)
+const AUDIO_CACHE_DIR = (0, path_1.join)((0, os_1.homedir)(), ".daobrew", "audio");
+let currentProcess = null;
+/** Resolve the audio file for an element + task. Checks cache dir, then bundled package audio. */
+function resolveAudioFile(element, task = "breathing") {
+    const filename = `${element}_${task}.m4a`;
+    // 1. Check user cache dir (prebaked binaural versions take priority)
+    const cachePath = (0, path_1.join)(AUDIO_CACHE_DIR, filename);
+    if ((0, fs_1.existsSync)(cachePath))
+        return cachePath;
+    // 2. Check bundled audio inside the package
+    const packagePath = (0, path_1.join)(PACKAGE_AUDIO_DIR, filename);
+    if ((0, fs_1.existsSync)(packagePath))
+        return packagePath;
+    // 3. Legacy naming fallback ({element}_{bpm}bpm.m4a)
+    if ((0, fs_1.existsSync)(AUDIO_CACHE_DIR)) {
+        const files = (0, fs_1.readdirSync)(AUDIO_CACHE_DIR).filter(f => f.startsWith(`${element}_`) && f.endsWith(".m4a"));
+        if (files.length > 0)
+            return (0, path_1.join)(AUDIO_CACHE_DIR, files[0]);
+    }
+    return null;
+}
+async function playAudio(element, task = "breathing", volume = 0.4) {
+    if (process.platform !== "darwin" && process.platform !== "linux") {
+        return { status: "no_player", pid: null, error: `Unsupported platform: ${process.platform}` };
+    }
+    const audioPath = resolveAudioFile(element, task);
+    if (!audioPath) {
+        return { status: "no_file", pid: null, error: `Audio file not found for ${element}_${task}.m4a — check ~/.daobrew/audio/ or package audio/ directory.` };
+    }
+    stopPlayback();
+    try {
+        if (process.platform === "darwin") {
+            currentProcess = (0, child_process_1.spawn)("afplay", ["-v", String(volume), audioPath], {
+                stdio: "ignore", detached: true,
+            });
+        }
+        else {
+            currentProcess = (0, child_process_1.spawn)("mpv", [
+                "--no-video", "--really-quiet", `--volume=${Math.round(volume * 100)}`, audioPath,
+            ], { stdio: "ignore", detached: true });
+        }
+        currentProcess.unref();
+        const pid = currentProcess.pid ?? null;
+        currentProcess.on("exit", () => { currentProcess = null; });
+        return { status: "playing", pid, file: audioPath };
+    }
+    catch (err) {
+        return { status: "error", pid: null, error: err.message };
+    }
+}
+function stopPlayback() {
+    if (currentProcess) {
+        currentProcess.kill("SIGTERM");
+        currentProcess = null;
+        return true;
+    }
+    return false;
+}
+function generateTextBreathingScript(element, durationSec, bpm) {
+    const cycleDuration = 60 / bpm;
+    const inhaleDuration = cycleDuration / 3;
+    const exhaleDuration = (cycleDuration * 2) / 3;
+    const cycles = Math.floor(durationSec / cycleDuration);
+    let script = `\n${types_js_1.ELEMENT_LABELS[element]} · ${types_js_1.ELEMENT_ORGANS[element]} — ${types_js_1.ELEMENT_SHORT_SUMMARIES[element]}\n`;
+    script += `${cycles} breathing cycles at ${bpm} BPM\n\n`;
+    for (let i = 1; i <= Math.min(cycles, 6); i++) {
+        script += `Cycle ${i}/${cycles}:\n`;
+        script += `  Inhale... (${inhaleDuration.toFixed(1)}s)\n`;
+        script += `  Exhale slowly... (${exhaleDuration.toFixed(1)}s)\n\n`;
+    }
+    if (cycles > 6)
+        script += `  ... (${cycles - 6} more cycles)\n\n`;
+    script += `Session complete. Call daobrew_get_session_result for HRV changes.\n`;
+    return script;
+}

package/dist/src/cache.d.ts

@@ -0,0 +1,7 @@
+export declare function get<T>(key: string): {
+    data: T;
+    age_seconds: number;
+} | null;
+export declare function set<T>(key: string, data: T): void;
+export declare function invalidate(key: string): void;
+export declare function ageSeconds(key: string): number;

package/dist/src/cache.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.get = get;
+exports.set = set;
+exports.invalidate = invalidate;
+exports.ageSeconds = ageSeconds;
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const store = new Map();
+function get(key) {
+    const entry = store.get(key);
+    if (!entry)
+        return null;
+    const age = Date.now() - entry.timestamp;
+    if (age > DEFAULT_TTL_MS) {
+        store.delete(key);
+        return null;
+    }
+    return { data: entry.data, age_seconds: Math.round(age / 1000) };
+}
+function set(key, data) {
+    store.set(key, { data, timestamp: Date.now() });
+}
+function invalidate(key) {
+    store.delete(key);
+}
+function ageSeconds(key) {
+    const entry = store.get(key);
+    if (!entry)
+        return -1;
+    return Math.round((Date.now() - entry.timestamp) / 1000);
+}

package/dist/src/client.d.ts

@@ -0,0 +1,22 @@
+import { Element, WellnessState, ElementDetail, SessionStart, SessionResult, SessionHistoryEntry, HealthSampleDTO } from "./types.js";
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export declare class DaoBrewClient {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: ClientConfig);
+    private request;
+    getWellnessState(): Promise<WellnessState>;
+    getElementDetail(element: Element): Promise<ElementDetail>;
+    startSession(element: Element, tier?: string): Promise<SessionStart>;
+    getSessionResult(sessionId: string): Promise<SessionResult>;
+    getSessionHistory(days?: number): Promise<SessionHistoryEntry[]>;
+    pushHealthSamples(samples: HealthSampleDTO[]): Promise<{
+        samples_received: number;
+        message: string;
+    }>;
+}

package/dist/src/client.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DaoBrewClient = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const DEFAULT_BASE_URL = "https://api.daobrew.com/api/v1";
+const DEFAULT_TIMEOUT_MS = 15000;
+class DaoBrewClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const args = [
+            "-sS", "--max-time", String(Math.ceil(this.timeoutMs / 1000)),
+            "-H", `Authorization: Bearer ${this.apiKey}`,
+            "-H", "Content-Type: application/json",
+        ];
+        if (options.method === "POST") {
+            args.push("-X", "POST");
+            if (options.body)
+                args.push("-d", options.body);
+        }
+        args.push(url);
+        const { stdout } = await execFileAsync("curl", args, { timeout: this.timeoutMs + 2000 });
+        const json = JSON.parse(stdout);
+        if (json.success === false) {
+            throw new Error(`DaoBrew API error: ${json.error?.message ?? json.error ?? "Unknown error"}`);
+        }
+        return json.data;
+    }
+    async getWellnessState() {
+        return this.request("/state/current?format=mcp");
+    }
+    async getElementDetail(element) {
+        return this.request(`/element/${element}/detail`);
+    }
+    async startSession(element, tier = "audio") {
+        return this.request("/session/start", {
+            method: "POST",
+            body: JSON.stringify({ element, tier }),
+        });
+    }
+    async getSessionResult(sessionId) {
+        return this.request(`/session/${sessionId}/outcome`);
+    }
+    async getSessionHistory(days = 7) {
+        return this.request(`/session/logs?limit=${days * 5}`);
+    }
+    async pushHealthSamples(samples) {
+        if (samples.length === 0)
+            return { samples_received: 0, message: "No samples to push" };
+        return this.request("/healthkit/samples", {
+            method: "POST",
+            body: JSON.stringify({ samples }),
+        });
+    }
+}
+exports.DaoBrewClient = DaoBrewClient;

package/dist/src/cooldown.d.ts

@@ -0,0 +1,5 @@
+export declare function activate(mode: "ambient" | "ondemand", durationMs?: number): void;
+export declare function isActive(mode: "ambient" | "ondemand"): boolean;
+export declare function remainingMinutes(mode: "ambient" | "ondemand"): number;
+export declare function clear(mode: "ambient" | "ondemand"): void;
+export declare function clearAll(): void;

package/dist/src/cooldown.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.isActive = isActive;
+exports.remainingMinutes = remainingMinutes;
+exports.clear = clear;
+exports.clearAll = clearAll;
+const DEFAULT_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
+let ambientCooldownEnd = 0;
+let ondemandCooldownEnd = 0;
+function activate(mode, durationMs = DEFAULT_COOLDOWN_MS) {
+    if (mode === "ambient")
+        ambientCooldownEnd = Date.now() + durationMs;
+    else
+        ondemandCooldownEnd = Date.now() + durationMs;
+}
+function isActive(mode) {
+    const end = mode === "ambient" ? ambientCooldownEnd : ondemandCooldownEnd;
+    return Date.now() < end;
+}
+function remainingMinutes(mode) {
+    const end = mode === "ambient" ? ambientCooldownEnd : ondemandCooldownEnd;
+    const remaining = end - Date.now();
+    return remaining > 0 ? Math.ceil(remaining / 60000) : 0;
+}
+function clear(mode) {
+    if (mode === "ambient")
+        ambientCooldownEnd = 0;
+    else
+        ondemandCooldownEnd = 0;
+}
+function clearAll() {
+    ambientCooldownEnd = 0;
+    ondemandCooldownEnd = 0;
+}

package/dist/src/headphones.d.ts

@@ -0,0 +1,6 @@
+export interface HeadphoneStatus {
+    connected: boolean;
+    device: string | null;
+    detection_method: "switchaudio" | "system_profiler" | "pactl" | "none";
+}
+export declare function detectHeadphones(): Promise<HeadphoneStatus>;

package/dist/src/headphones.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectHeadphones = detectHeadphones;
+const child_process_1 = require("child_process");
+const os_1 = require("os");
+const util_1 = require("util");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+// Blocklist: known built-in speakers to REJECT.
+// Everything else (USB-C, DAC, Bluetooth, unknown external) = allowed.
+const BUILTIN_SPEAKER_PATTERNS = [
+    "macbook pro speakers", "macbook air speakers", "macbook speakers",
+    "built-in output", "built-in speaker", "internal speakers",
+    "display audio", "imac speakers", "mac mini", "mac pro speakers",
+    "mac studio speakers",
+];
+async function detectHeadphones() {
+    const os = (0, os_1.platform)();
+    if (os === "darwin") {
+        try {
+            const { stdout } = await execAsync("SwitchAudioSource -c -t output");
+            const device = stdout.trim();
+            const deviceLower = device.toLowerCase();
+            const isBuiltIn = BUILTIN_SPEAKER_PATTERNS.some(p => deviceLower.includes(p));
+            return { connected: !isBuiltIn, device, detection_method: "switchaudio" };
+        }
+        catch {
+            try {
+                const { stdout } = await execAsync("system_profiler SPBluetoothDataType -json 2>/dev/null");
+                const hasConnectedAudio = stdout.includes('"attrib_Connected" : "attrib_Yes"');
+                return { connected: hasConnectedAudio, device: null, detection_method: "system_profiler" };
+            }
+            catch {
+                return { connected: true, device: null, detection_method: "none" };
+            }
+        }
+    }
+    if (os === "linux") {
+        try {
+            const { stdout } = await execAsync("pactl list sinks short");
+            const hasExternal = stdout.toLowerCase().includes("bluetooth") ||
+                stdout.toLowerCase().includes("headphone") ||
+                stdout.toLowerCase().includes("usb");
+            return { connected: hasExternal, device: null, detection_method: "pactl" };
+        }
+        catch {
+            return { connected: true, device: null, detection_method: "none" };
+        }
+    }
+    return { connected: true, device: null, detection_method: "none" };
+}