oc-sounds 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,257 @@
+# oc-sounds
+
+Plugin for OpenCode V2 that makes prompting a more **sensual** experience.
+Hear the agent think, read, search, edit, run commands, delegate, and finish with
+the [Cuelume](https://github.com/Danilaa1/cuelume) sound palette.
+
+## Install
+
+Requires Node.js 22+ and OpenCode V2. Built against
+`@opencode/plugin@0.0.0-beta-19398`.
+
+Once the first release is published to npm, install globally with:
+
+```sh
+opencode2 plugin add oc-sounds
+```
+
+All sounds are enabled at **100% volume** by default. No individual sound setup
+is required. The package includes all 17 sound files and needs no browser or
+sound renderer at runtime.
+
+For project-only installation, add `oc-sounds` to `plugins` in your project's
+`opencode.jsonc` instead:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "oc-sounds",
+      "options": { "volume": 1 }
+    }
+  ]
+}
+```
+
+OpenCode watches its configuration for changes. If sounds do not start after
+installation, restart its background service:
+
+```sh
+opencode2 service restart
+```
+
+Update an installed package with:
+
+```sh
+opencode2 plugin update oc-sounds
+```
+
+Until the first npm release, follow [Use a local checkout](#use-a-local-checkout).
+
+### Audio playback
+
+The plugin automatically chooses an installed player:
+
+| Platform | Players, in preference order |
+| --- | --- |
+| Linux | `paplay`, `pw-play`, `ffplay` |
+| macOS | Built-in `afplay`, then `ffplay` |
+| Windows | `ffplay` (install FFmpeg and add it to `PATH`) |
+
+On Debian/Ubuntu, `sudo apt install pulseaudio-utils` provides `paplay`.
+On Arch, `sudo pacman -S libpulse` provides it. PipeWire's PulseAudio compatibility
+server also supports `paplay`.
+
+Sound plays on the **machine running the OpenCode server**. For a local TUI,
+desktop app, or browser connected to a local server, that is your computer. A
+remote/headless server needs its own accessible audio output.
+
+Playback runs asynchronously. Concurrent actions can overlap, and no action is
+throttled. If a player fails, automatic mode tries the next player; if none work,
+the plugin logs one warning and lets the agent continue. Unloading the plugin
+stops its audio processes and event subscription.
+
+## What makes a sound?
+
+Each tool invocation gets a starting cue and a success/error cue, including
+custom tools, MCP tools, and nested calls that OpenCode exposes through its tool
+hooks. The built-in tool palette is:
+
+| Tool action | Sound |
+| --- | --- |
+| Read files | `page` |
+| Glob, grep, web search | `scan` |
+| Fetch a URL | `droplet` |
+| Write, edit, patch | `toggle` |
+| Shell / code execution | `pulse` |
+| Delegate to a subagent | `arrival` |
+| Load a skill | `sparkle` |
+| Ask the user a question | `chime` |
+| Other tools | `tick` |
+| Tool succeeds / fails | `release` / `error` |
+
+Session actions also have cues. The option keys are listed below:
+
+| Option key | Action | Default |
+| --- | --- | --- |
+| `prompt` | Input enters the session inbox | `press` |
+| `start` | Agent execution starts | `loading` |
+| `step` | Model step starts | `pulse` |
+| `thinking` | Reasoning block starts | `whisper` |
+| `reply` | Reply block starts | `chime` |
+| `tool` | Fallback tool-start cue | `tick` |
+| `toolComplete` | Tool completes | `release` |
+| `toolError` | Tool fails | `error` |
+| `question` | Question tool starts | `chime` |
+| `permission` | Permission request appears | `bloom` |
+| `permissionReply` | Permission request is answered | `toggle` |
+| `retry` | Model retry is scheduled | `scan` |
+| `complete` | Agent execution succeeds | `success` |
+| `error` | Execution or compaction fails | `error` |
+| `interrupt` | Agent execution is interrupted | `droplet` |
+| `compact` | Context compaction starts | `page` |
+| `compactComplete` | Context compaction finishes | `ready` |
+| `skill` | Skill is activated | `sparkle` |
+| `agent` | Session agent is switched | `arrival` |
+
+Reasoning and replies sound once per block, rather than on every streamed token.
+Tool progress updates do not repeat the start cue. Public events are scoped to
+the plugin's location and repeated event IDs are deduplicated.
+
+## Customize
+
+Edit the existing plugin entry in `~/.config/opencode/opencode.jsonc` (global)
+or your project's `opencode.jsonc`. Merge it with your other settings:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "oc-sounds",
+      "options": {
+        "enabled": true,
+        "volume": 0.35,
+        "player": "auto",
+        "cues": {
+          "thinking": "whisper",
+          "complete": "ready",
+          "step": false
+        },
+        "tools": {
+          "read": "tick",
+          "shell": "pulse",
+          "my_mcp_tool": "sparkle"
+        }
+      }
+    }
+  ]
+}
+```
+
+- `enabled`: defaults to `true`. Set to `false` to disable all sounds.
+- `volume`: from `0` to `1`, defaults to `1` (100%). Zero disables playback.
+- `player`: `auto`, `paplay`, `pw-play`, `afplay`, or `ffplay`. An explicit player
+  disables automatic fallback to other players.
+- `cues`: override any action in the table, or set it to `false` to mute it.
+  Setting `cues.tool` replaces the built-in starting palette for all ordinary
+  tools. `question` is configured separately.
+- `tools`: override starting cues by exact effective tool name or built-in short
+  name (`read` also matches `functions.read` / `functions_read`). Exact names
+  take precedence. `false` mutes that tool's starting cue; completion and error
+  cues are controlled separately. Tool overrides take precedence over `cues.tool`.
+
+All 17 Cuelume sounds are available:
+`chime`, `sparkle`, `droplet`, `bloom`, `whisper`, `tick`, `press`, `release`,
+`toggle`, `success`, `error`, `page`, `loading`, `ready`, `pulse`, `scan`, `arrival`.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack
+```
+
+### Use a local checkout
+
+From the repository directory:
+
+```sh
+npm ci
+npm run build
+```
+
+Add the checkout's **absolute directory path** to `plugins` in your global or
+project OpenCode configuration:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "/absolute/path/to/oc-sounds",
+      "options": { "volume": 1 }
+    }
+  ]
+}
+```
+
+Rebuild after changing TypeScript source. Restart OpenCode's background service
+if it does not pick up changes to the local plugin.
+
+### Regenerate the sounds
+
+The 17 mono, 48kHz PCM WAVs are checked into `sounds/` and included in the package.
+Normal builds and installs use these files directly. To regenerate them:
+
+```sh
+npm run sounds:render
+```
+
+The renderer runs the unmodified Cuelume 0.2.2 engine through
+`node-web-audio-api`'s offline context, using seeded noise and preserving the
+sound envelopes and shimmer tails. It requires no browser, Playwright, or audio
+device. Cuelume and the native offline renderer are development dependencies;
+neither is needed by the installed plugin.
+
+Tests cover the V2 plugin lifecycle, event isolation/deduplication, concurrent
+tools, muting, cleanup, player fallback, and bundled WAV integrity. Linux player
+tests use fake executables and do not play audio.
+
+### Publish to npm
+
+Review and test the package before publishing:
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+The `prepack` hook builds the plugin automatically. The package contains `dist/`,
+`sounds/`, the README, and the license notices; development dependencies and
+rendering scripts are excluded.
+
+Sign in to an npm account with publishing access, then publish:
+
+```sh
+npm login
+npm publish --access public
+```
+
+For subsequent releases, commit your changes, bump the version, and publish:
+
+```sh
+npm version patch
+npm publish
+```
+
+Use `minor` or `major` instead of `patch` when appropriate. Each npm release needs
+a new version number. After the first release, update the installation section
+to remove the pending-release wording.
+
+## License
+
+MIT. Cuelume sounds are by Daniel Belyi, also MIT. See
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attribution and license text.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+# Cuelume
+
+The bundled WAV files in `sounds/` are rendered from the unmodified sound engine
+and recipes of [Cuelume](https://github.com/Danilaa1/cuelume) v0.2.2 by Daniel Belyi.
+They are generated by `scripts/render-sounds.mjs` using `node-web-audio-api`'s
+offline Web Audio renderer. Cuelume is used only at build time.
+
+MIT License
+
+Copyright (c) 2026 Daniel Belyi
+
+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/dist/config.d.ts

@@ -0,0 +1,34 @@
+export declare const sounds: readonly ["chime", "sparkle", "droplet", "bloom", "whisper", "tick", "press", "release", "toggle", "success", "error", "page", "loading", "ready", "pulse", "scan", "arrival"];
+export type SoundName = (typeof sounds)[number];
+export declare const defaultCues: {
+    readonly prompt: "press";
+    readonly start: "loading";
+    readonly step: "pulse";
+    readonly thinking: "whisper";
+    readonly reply: "chime";
+    readonly tool: "tick";
+    readonly toolComplete: "release";
+    readonly toolError: "error";
+    readonly permission: "bloom";
+    readonly permissionReply: "toggle";
+    readonly question: "chime";
+    readonly retry: "scan";
+    readonly complete: "success";
+    readonly error: "error";
+    readonly interrupt: "droplet";
+    readonly compact: "page";
+    readonly compactComplete: "ready";
+    readonly skill: "sparkle";
+    readonly agent: "arrival";
+};
+export type Action = keyof typeof defaultCues;
+export declare const defaultToolCues: Record<string, SoundName>;
+export type PlayerName = "auto" | "paplay" | "pw-play" | "afplay" | "ffplay";
+export interface Options {
+    enabled: boolean;
+    volume: number;
+    player: PlayerName;
+    cues: Record<Action, SoundName | false>;
+    tools: Record<string, SoundName | false>;
+}
+export declare function parseOptions(input: unknown): Options;

package/dist/config.js

@@ -0,0 +1,83 @@
+export const sounds = [
+    "chime", "sparkle", "droplet", "bloom", "whisper", "tick", "press",
+    "release", "toggle", "success", "error", "page", "loading", "ready",
+    "pulse", "scan", "arrival",
+];
+export const defaultCues = {
+    prompt: "press",
+    start: "loading",
+    step: "pulse",
+    thinking: "whisper",
+    reply: "chime",
+    tool: "tick",
+    toolComplete: "release",
+    toolError: "error",
+    permission: "bloom",
+    permissionReply: "toggle",
+    question: "chime",
+    retry: "scan",
+    complete: "success",
+    error: "error",
+    interrupt: "droplet",
+    compact: "page",
+    compactComplete: "ready",
+    skill: "sparkle",
+    agent: "arrival",
+};
+export const defaultToolCues = {
+    read: "page",
+    glob: "scan",
+    grep: "scan",
+    websearch: "scan",
+    webfetch: "droplet",
+    write: "toggle",
+    edit: "toggle",
+    patch: "toggle",
+    apply_patch: "toggle",
+    shell: "pulse",
+    bash: "pulse",
+    execute: "pulse",
+    subagent: "arrival",
+    task: "arrival",
+    skill: "sparkle",
+};
+function object(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    throw new Error("oc-sounds: expected an options object");
+}
+function cue(value) {
+    if (value === false || sounds.includes(value))
+        return value;
+    throw new Error(`oc-sounds: unknown sound ${String(value)}`);
+}
+export function parseOptions(input) {
+    const raw = object(input);
+    for (const key of Object.keys(raw)) {
+        if (!["enabled", "volume", "player", "cues", "tools"].includes(key)) {
+            throw new Error(`oc-sounds: unknown option ${key}`);
+        }
+    }
+    const enabled = raw.enabled ?? true;
+    if (typeof enabled !== "boolean")
+        throw new Error("oc-sounds: enabled must be a boolean");
+    const volume = raw.volume ?? 1;
+    if (typeof volume !== "number" || !Number.isFinite(volume) || volume < 0 || volume > 1) {
+        throw new Error("oc-sounds: volume must be between 0 and 1");
+    }
+    const player = raw.player ?? "auto";
+    if (!["auto", "paplay", "pw-play", "afplay", "ffplay"].includes(player)) {
+        throw new Error(`oc-sounds: unknown player ${String(player)}`);
+    }
+    const cues = { ...defaultCues };
+    for (const [key, value] of Object.entries(object(raw.cues ?? {}))) {
+        if (!Object.hasOwn(cues, key))
+            throw new Error(`oc-sounds: unknown action ${key}`);
+        cues[key] = cue(value);
+    }
+    const tools = Object.create(null);
+    for (const [key, value] of Object.entries(object(raw.tools ?? {})))
+        tools[key] = cue(value);
+    return { enabled, volume, player: player, cues, tools };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from "@opencode/plugin";
+import { type Action, type Options } from "./config.js";
+import { type Player } from "./player.js";
+export { defaultCues, defaultToolCues, sounds } from "./config.js";
+export type { Action, Options, SoundName } from "./config.js";
+type Event = ReturnType<Plugin.Context["event"]["subscribe"]> extends AsyncIterable<infer E> ? E : never;
+export declare function actionForEvent(event: Event): Action | undefined;
+export declare function setup(ctx: Plugin.Context, makePlayer?: (selection: Options["player"], volume: number) => Player): Promise<Plugin.Cleanup | void>;
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,139 @@
+import { Plugin } from "@opencode/plugin";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { defaultToolCues, parseOptions } from "./config.js";
+import { createPlayer } from "./player.js";
+export { defaultCues, defaultToolCues, sounds } from "./config.js";
+const eventActions = {
+    "session.inbox.enqueued": "prompt",
+    "session.execution.started": "start",
+    "session.step.started": "step",
+    "session.reasoning.started": "thinking",
+    "session.text.started": "reply",
+    "session.execution.succeeded": "complete",
+    "session.execution.failed": "error",
+    "session.execution.interrupted": "interrupt",
+    "session.retry.scheduled": "retry",
+    "session.compaction.started": "compact",
+    "session.compaction.ended": "compactComplete",
+    "session.compaction.failed": "error",
+    "session.skill.activated": "skill",
+    "session.agent.selected": "agent",
+    "permission.asked": "permission",
+    "permission.replied": "permissionReply",
+};
+export function actionForEvent(event) {
+    return eventActions[event.type];
+}
+// Exported separately to exercise the actual plugin lifecycle with a fake player.
+export async function setup(ctx, makePlayer = createPlayer) {
+    const options = parseOptions(ctx.options);
+    if (!options.enabled || options.volume === 0)
+        return;
+    const player = makePlayer(options.player, options.volume);
+    const controller = new AbortController();
+    const registrations = [];
+    const emit = (action, tool) => {
+        if (controller.signal.aborted)
+            return;
+        let sound = options.cues[action];
+        if (tool !== undefined) {
+            const name = tool.split(".").at(-1);
+            const short = name.replace(/^(functions|tools)_/, "");
+            if (Object.hasOwn(options.tools, tool))
+                sound = options.tools[tool];
+            else if (Object.hasOwn(options.tools, short))
+                sound = options.tools[short];
+            // An explicit tool cue replaces the built-in palette for all tools.
+            else if (action === "tool" && !Object.hasOwn(ctx.options.cues ?? {}, "tool")) {
+                if (Object.hasOwn(defaultToolCues, short))
+                    sound = defaultToolCues[short];
+            }
+        }
+        if (sound)
+            player.play(sound);
+    };
+    const cleanup = async () => {
+        controller.abort();
+        player.dispose();
+        await Promise.all(registrations.map((registration) => registration.dispose()));
+    };
+    try {
+        registrations.push(await ctx.tool.hook("execute.before", (event) => {
+            const name = event.tool.split(/[._]/).at(-1);
+            emit(name === "question" ? "question" : "tool", event.tool);
+        }));
+        registrations.push(await ctx.tool.hook("execute.after", (event) => {
+            emit(event.status === "error" ? "toolError" : "toolComplete");
+        }));
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+    // The public stream is server-wide, while each plugin instance belongs to a
+    // location. Resolve events without location metadata before making a sound.
+    const locations = new Map();
+    const seen = new Set();
+    const matches = (location) => resolve(location.directory) === resolve(ctx.location.directory)
+        && location.workspaceID === ctx.location.workspaceID;
+    const belongsHere = async (event) => {
+        if (event.location)
+            return matches(event.location);
+        if (!("sessionID" in event.data))
+            return false;
+        const sessionID = event.data.sessionID;
+        const cached = locations.get(sessionID);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const session = await ctx.session.get({ sessionID }, { signal: controller.signal });
+            const result = matches(session.location);
+            if (locations.size >= 1024)
+                locations.delete(locations.keys().next().value);
+            locations.set(sessionID, result);
+            return result;
+        }
+        catch {
+            return false;
+        }
+    };
+    const consume = async () => {
+        let warned = false;
+        while (!controller.signal.aborted) {
+            try {
+                for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+                    if (controller.signal.aborted)
+                        break;
+                    if (event.type === "session.moved" || event.type === "session.deleted") {
+                        locations.delete(event.data.sessionID);
+                    }
+                    const action = actionForEvent(event);
+                    if (!action || seen.has(event.id))
+                        continue;
+                    if (!(await belongsHere(event)))
+                        continue;
+                    seen.add(event.id);
+                    if (seen.size > 4096)
+                        seen.delete(seen.values().next().value);
+                    emit(action);
+                }
+            }
+            catch {
+                if (!controller.signal.aborted && !warned) {
+                    warned = true;
+                    console.warn("oc-sounds: event stream disconnected; retrying in one second.");
+                }
+            }
+            if (!controller.signal.aborted) {
+                await delay(1000, undefined, { signal: controller.signal }).catch(() => { });
+            }
+        }
+    };
+    const task = consume();
+    return async () => {
+        await cleanup();
+        await task;
+    };
+}
+export default Plugin.define({ id: "oc-sounds", setup: (ctx) => setup(ctx) });

package/dist/player.d.ts

@@ -0,0 +1,9 @@
+import type { PlayerName, SoundName } from "./config.js";
+type Backend = Exclude<PlayerName, "auto">;
+export interface Player {
+    play(sound: SoundName): void;
+    dispose(): void;
+}
+export declare function playerArgs(player: Backend, file: string, volume: number): string[];
+export declare function createPlayer(selection: PlayerName, volume: number, warn?: (message: string) => void): Player;
+export {};

package/dist/player.js

@@ -0,0 +1,102 @@
+import { accessSync, constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function playerArgs(player, file, volume) {
+    switch (player) {
+        case "paplay": return [`--volume=${Math.round(volume * 65536)}`, file];
+        case "pw-play": return [`--volume=${volume}`, file];
+        case "afplay": return ["-v", String(volume), file];
+        case "ffplay": return ["-nodisp", "-autoexit", "-loglevel", "quiet", "-volume", String(Math.round(volume * 100)), file];
+    }
+}
+function executable(name) {
+    const names = process.platform === "win32" ? [`${name}.exe`, name] : [name];
+    for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+        if (!directory)
+            continue;
+        for (const candidate of names) {
+            const file = join(directory, candidate);
+            try {
+                accessSync(file, constants.X_OK);
+                return file;
+            }
+            catch { /* Try the next PATH entry. */ }
+        }
+    }
+}
+export function createPlayer(selection, volume, warn = console.warn) {
+    const order = selection !== "auto" ? [selection]
+        : process.platform === "darwin" ? ["afplay", "ffplay"]
+            : process.platform === "win32" ? ["ffplay"] : ["paplay", "pw-play", "ffplay"];
+    const backends = order.flatMap((name) => {
+        const command = executable(name);
+        return command ? [{ name, command }] : [];
+    });
+    const children = new Set();
+    let index = 0;
+    let disposed = false;
+    let warned = false;
+    const unavailable = () => {
+        if (warned || disposed)
+            return;
+        warned = true;
+        warn("oc-sounds: audio playback unavailable; install/configure paplay, pw-play, afplay (macOS), or ffplay. Sounds run on the OpenCode server's machine.");
+    };
+    if (!backends.length)
+        unavailable();
+    function play(sound) {
+        if (disposed || volume === 0)
+            return;
+        const backend = backends[index];
+        if (!backend)
+            return;
+        const file = fileURLToPath(new URL(`../sounds/${sound}.wav`, import.meta.url));
+        let child;
+        try {
+            child = spawn(backend.command, playerArgs(backend.name, file, volume), {
+                stdio: "ignore",
+                windowsHide: true,
+                shell: false,
+            });
+        }
+        catch {
+            fail();
+            return;
+        }
+        children.add(child);
+        // Bound hung audio processes; playback never blocks hooks or the event stream.
+        const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+        timer.unref();
+        let finished = false;
+        const finish = (failed) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            children.delete(child);
+            if (failed && !disposed)
+                fail();
+        };
+        function fail() {
+            if (backends[index] === backend)
+                index++;
+            if (backends[index])
+                play(sound);
+            else
+                unavailable();
+        }
+        child.once("error", () => finish(true));
+        child.once("close", (code) => finish(code !== 0));
+        child.unref();
+    }
+    return {
+        play,
+        dispose() {
+            disposed = true;
+            for (const child of children)
+                child.kill("SIGKILL");
+            children.clear();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "oc-sounds",
+  "version": "0.1.0",
+  "description": "Cuelume sound feedback for OpenCode V2 agent actions",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": ["dist", "sounds", "THIRD_PARTY_NOTICES.md"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "sounds:render": "node scripts/render-sounds.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@opencode/plugin": "0.0.0-beta-19398"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "cuelume": "0.2.2",
+    "node-web-audio-api": "2.2.0",
+    "typescript": "^5.9.0"
+  }
+}