@openbrt/audioctl 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @openbrt/audioctl
+
+Generic WeClawBot audio-output control CLI and AI-agent plugin.
+
+It is meant for user-owned agents such as Codex, Claude Code, OpenClaw, Hermes,
+WorkBuddy, Gemini CLI, or any shell-capable agent runtime. It is not tied to one
+speaker brand. Any ESP32/Linux audio device that implements the WeClawBot MQTT
+audio command envelope can use the same package.
+
+## Tell your agent
+
+```text
+Install npm package @openbrt/audioctl, bind my audio device with pairing code 123456,
+run doctor, then use it as my default BGM/music output device.
+```
+
+## Install and bind
+
+```bash
+npm install -g @openbrt/audioctl
+audioctl bind 123456 --name codex
+audioctl doctor --online
+```
+
+One-shot usage:
+
+```bash
+npm exec --package @openbrt/audioctl -- audioctl bind 123456 --name codex
+```
+
+Credentials are saved to `~/.config/weclawbot/audio-mqtt.json` by default.
+
+## Commands
+
+```bash
+audioctl play
+audioctl pause
+audioctl toggle
+audioctl next
+audioctl previous
+audioctl volume 48
+audioctl volumeup
+audioctl volumedown
+audioctl status
+audioctl rule ./my-playlist-rule.json
+audioctl deepnight
+audioctl prompt 123456 --agent codex --alias 视听房音箱
+```
+
+`deepnight` pushes the bundled “深夜工作” playlist rule and asks the device to
+refresh/play according to its local runtime. The package never contains music
+platform private keys.
+
+## Control envelope
+
+The MQTT control message is:
+
+```json
+{
+  "schema": "weclawbot.control.v1",
+  "id": "audio_<uuid>",
+  "kind": "music_command",
+  "music": {
+    "command": "play"
+  }
+}
+```
+
+Supported commands include `play`, `pause`, `toggle`, `next`, `previous`,
+`seek`, `set_volume`, `volume_up`, `volume_down`, `status`, and `set_rule`.

package/agent-plugin.json

@@ -0,0 +1,61 @@
+{
+  "schema": "weclawbot.agent_plugin.v1",
+  "id": "audioctl",
+  "name": "audioctl",
+  "package": "@openbrt/audioctl",
+  "bin": "audioctl",
+  "description": "Bind and control WeClawBot-compatible audio output devices from user-owned AI agents.",
+  "transport": "weclawbot.link/mqtt",
+  "device_classes": [
+    "audio_output",
+    "music_player"
+  ],
+  "agents": [
+    "Codex",
+    "Claude Code",
+    "OpenClaw",
+    "Hermes",
+    "WorkBuddy",
+    "Gemini CLI",
+    "OpenCode"
+  ],
+  "capabilities": [
+    "audio.play",
+    "audio.pause",
+    "audio.toggle",
+    "audio.next",
+    "audio.previous",
+    "audio.seek",
+    "audio.set_volume",
+    "music.set_rule",
+    "music.status"
+  ],
+  "pairing": {
+    "endpoint": "https://weclawbot.link/byoa",
+    "endpoint_env": "WEC_BYOA_ENDPOINT",
+    "credentials_env": "WEC_AUDIO_CREDENTIALS",
+    "code_pattern": "^[A-Za-z0-9_-]{6,64}$"
+  },
+  "commands": [
+    {
+      "name": "bind",
+      "usage": "audioctl bind CODE --name AGENT"
+    },
+    {
+      "name": "doctor",
+      "usage": "audioctl doctor --online"
+    },
+    {
+      "name": "control",
+      "usage": "audioctl play|pause|toggle|next|previous|volumeup|volumedown|status"
+    },
+    {
+      "name": "volume",
+      "usage": "audioctl volume 0..100"
+    },
+    {
+      "name": "rule",
+      "usage": "audioctl rule RULE.json"
+    }
+  ]
+}

package/bin/audioctl.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import process from "node:process";
+
+import {
+  COMMAND_NAME,
+  DEFAULT_CREDENTIALS_PATH,
+  DEFAULT_ENDPOINT,
+  DEEPNIGHT_RULE,
+  PACKAGE_NAME,
+  bindAgent,
+  buildAgentPrompt,
+  buildAudioControl,
+  expandPath,
+  normalizeCredentials,
+  publishAudioControl,
+  readCredentials,
+  summarizePlayback,
+  testConnection,
+  validateRule,
+} from "../lib/index.mjs";
+
+const [command, ...rawArguments] = process.argv.slice(2);
+
+if (!command || new Set(["help", "-h", "--help"]).has(command)) {
+  usage(command ? 0 : 64);
+} else {
+  try {
+    await run(command, rawArguments);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  }
+}
+
+async function run(name, values) {
+  if (name === "bind") return commandBind(values);
+  if (name === "doctor") return commandDoctor(values);
+  if (name === "prompt") return commandPrompt(values);
+  if (name === "manifest") return commandManifest();
+  if (name === "rule") return commandRule(values);
+  if (name === "deepnight") return commandDeepnight(values);
+  if (name === "volume") return commandVolume(values);
+  if (name === "seek") return commandSeek(values);
+  return commandControl(name, values);
+}
+
+function usage(exitCode = 0) {
+  process.stdout.write(`Usage:
+  ${COMMAND_NAME} bind CODE [--name AGENT]
+  ${COMMAND_NAME} doctor [--online] [--json]
+  ${COMMAND_NAME} prompt CODE [--agent AGENT] [--alias NAME]
+  ${COMMAND_NAME} play|pause|toggle|next|previous|volumeup|volumedown|status
+  ${COMMAND_NAME} volume 0..100
+  ${COMMAND_NAME} seek MILLISECONDS
+  ${COMMAND_NAME} rule RULE.json
+  ${COMMAND_NAME} deepnight
+  ${COMMAND_NAME} manifest
+
+Options:
+  --credentials FILE   default: ${DEFAULT_CREDENTIALS_PATH}
+  --endpoint URL       default: ${DEFAULT_ENDPOINT}
+  --timeout SECONDS    default: 12
+  --json               machine-readable output
+  --nowait             publish without waiting for device status
+`);
+  process.exit(exitCode);
+}
+
+async function commandBind(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    endpoint: process.env.WEC_BYOA_ENDPOINT || DEFAULT_ENDPOINT,
+    name: process.env.WEC_AGENT_NAME || "user-agent",
+    timeout: 15,
+  });
+  const code = String(options._[0] || "");
+  const result = await bindAgent({
+    code,
+    name: options.name,
+    endpoint: options.endpoint,
+    credentialsPath: options.credentials,
+    timeoutMs: Number(options.timeout) * 1000,
+  });
+  process.stdout.write(
+    `paired ${result.credentials.binding?.device_id || "audio-device"} -> ${result.credentialsPath}\n`,
+  );
+}
+
+async function commandDoctor(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    online: false,
+    json: false,
+    timeout: 12,
+  });
+  const file = expandPath(options.credentials);
+  const credentials = await readCredentials(file);
+  const profile = normalizeCredentials(credentials);
+  const status = {
+    ok: true,
+    paired: true,
+    credentials: file,
+    device_id: credentials.binding?.device_id || "",
+    control_topic: profile.controlTopic,
+    status_topic: profile.statusTopic,
+    online: null,
+  };
+  if (options.online) {
+    await testConnection(credentials, { timeoutMs: Number(options.timeout) * 1000 });
+    status.online = true;
+  }
+  print(status, options.json);
+}
+
+async function commandPrompt(values) {
+  const options = parseOptions(values, {
+    agent: process.env.WEC_AGENT_NAME || "agent",
+    alias: "音频设备",
+    profile: "深夜工作",
+  });
+  process.stdout.write(`${buildAgentPrompt({
+    code: options._[0],
+    agentName: options.agent,
+    alias: options.alias,
+    profile: options.profile,
+  })}\n`);
+}
+
+async function commandManifest() {
+  const manifest = JSON.parse(
+    await fs.readFile(new URL("../agent-plugin.json", import.meta.url), "utf8"),
+  );
+  process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+async function commandRule(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  const file = String(options._[0] || "");
+  if (!file) throw new Error("rule_requires_file");
+  const rule = validateRule(JSON.parse(await fs.readFile(file, "utf8")));
+  await send("set_rule", options, { rule });
+}
+
+async function commandDeepnight(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  await send("set_rule", options, { rule: DEEPNIGHT_RULE });
+}
+
+async function commandVolume(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  await send("set_volume", options, { volume: options._[0] });
+}
+
+async function commandSeek(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  await send("seek", options, { positionMs: options._[0] });
+}
+
+async function commandControl(name, values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  await send(name, options);
+}
+
+async function send(name, options, payload = {}) {
+  const control = buildAudioControl(name, payload);
+  const credentials = await readCredentials(options.credentials);
+  const delivery = await publishAudioControl(credentials, control, {
+    timeoutMs: Number(options.timeout) * 1000,
+    wait: !options.nowait,
+  });
+  print(delivery.status || delivery, options.json);
+  if (delivery.status?.kind === "rejected") process.exitCode = 1;
+}
+
+function parseOptions(values, defaults = {}) {
+  const options = {
+    _: [],
+    ...defaults,
+  };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (!value.startsWith("--")) {
+      options._.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    if (key === "json" || key === "online" || key === "nowait") {
+      options[key] = true;
+      continue;
+    }
+    if (!new Set([
+      "agent",
+      "alias",
+      "credentials",
+      "endpoint",
+      "name",
+      "profile",
+      "timeout",
+    ]).has(key)) {
+      throw new Error(`option_unknown: --${key}`);
+    }
+    options[key] = values[++index];
+    if (options[key] === undefined) throw new Error(`option_value_missing: --${key}`);
+  }
+  return options;
+}
+
+function credentialsPath() {
+  return (
+    process.env.WEC_AUDIO_CREDENTIALS ||
+    process.env.WEC_MQTT_CREDENTIALS ||
+    DEFAULT_CREDENTIALS_PATH
+  );
+}
+
+function print(value, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    return;
+  }
+  if (value?.kind === "applied" || value?.kind === "rejected") {
+    const playback = summarizePlayback(value);
+    const track = playback.track || "no track";
+    process.stdout.write(
+      `${value.kind}: ${value.detail || ""}\n` +
+        `playback: ${playback.desired}, volume ${playback.volume ?? "-"}, ${track}\n`,
+    );
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+

package/lib/index.mjs

@@ -0,0 +1,388 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import mqtt from "mqtt";
+
+export const PACKAGE_NAME = "@openbrt/audioctl";
+export const COMMAND_NAME = "audioctl";
+export const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
+export const DEFAULT_CREDENTIALS_PATH = path.join(
+  os.homedir(),
+  ".config",
+  "weclawbot",
+  "audio-mqtt.json",
+);
+
+export const DEEPNIGHT_RULE = Object.freeze({
+  schemaVersion: 1,
+  title: "深夜工作",
+  source: "网易云音乐官方歌单：深夜刷题党｜轻缓律动伴你专注学习",
+  sourcePlaylist: Object.freeze({
+    originalId: "8383869866",
+    encryptedId: "661561242F7B3CE80B5AB760DB171EB4",
+  }),
+  fetchLimit: 60,
+  targetTrackCount: 20,
+  minimumTrackCount: 8,
+  qualityPolicy: "highest-available",
+  refreshHintSeconds: 21600,
+});
+
+export function validateBindingCode(code) {
+  const value = string(code).replace(/\s/gu, "");
+  if (!/^[A-Za-z0-9_-]{6,64}$/u.test(value)) {
+    throw new Error("binding_code_invalid");
+  }
+  return value;
+}
+
+export function expandPath(file) {
+  const value = string(file);
+  if (!value) return DEFAULT_CREDENTIALS_PATH;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return path.resolve(value);
+}
+
+export async function bindAgent(options = {}) {
+  const code = validateBindingCode(options.code);
+  const endpoint = string(options.endpoint) || DEFAULT_ENDPOINT;
+  const agentName = string(options.name || options.agentName || "user-agent")
+    .slice(0, 80);
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({
+      schema: "weclawbot.byoa.v1",
+      operation: "claim",
+      code,
+      agent_name: agentName,
+    }),
+    signal: AbortSignal.timeout(Math.max(1000, Number(options.timeoutMs) || 15_000)),
+  });
+  const payload = await response.json().catch(() => null);
+  if (
+    !response.ok ||
+    !payload?.ok ||
+    payload?.schema !== "weclawbot.byoa.agent_credentials.v1"
+  ) {
+    throw new Error(`pairing_failed: ${payload?.error || `HTTP ${response.status}`}`);
+  }
+
+  const credentials = {
+    schema: "weclawbot.agent_credentials.v1",
+    binding: payload.binding,
+    mqtt: payload.mqtt,
+    delivery: payload.delivery,
+    created_at: new Date().toISOString(),
+  };
+  normalizeCredentials(credentials);
+  const credentialsPath = expandPath(options.credentialsPath || options.credentials);
+  await writeCredentials(credentialsPath, credentials);
+  return { credentials, credentialsPath };
+}
+
+export async function writeCredentials(file, credentials) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, `${JSON.stringify(credentials, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await fs.chmod(file, 0o600);
+}
+
+export async function readCredentials(file = DEFAULT_CREDENTIALS_PATH) {
+  const credentialsPath = expandPath(file);
+  let value;
+  try {
+    value = JSON.parse(await fs.readFile(credentialsPath, "utf8"));
+  } catch {
+    throw new Error(`credentials_unavailable: ${credentialsPath}`);
+  }
+  return value;
+}
+
+export function normalizeCredentials(value) {
+  const profile = value?.mqtt && typeof value.mqtt === "object" ? value.mqtt : value;
+  const topics = profile?.topics || {};
+  if (
+    typeof profile?.url !== "string" ||
+    !profile.url.startsWith("wss://") ||
+    typeof profile?.username !== "string" ||
+    typeof profile?.password !== "string" ||
+    typeof profile?.client_id !== "string" ||
+    typeof topics.control !== "string" ||
+    !topics.control
+  ) {
+    throw new Error("credentials_invalid");
+  }
+  return {
+    url: profile.url,
+    username: profile.username,
+    password: profile.password,
+    clientId: profile.client_id,
+    controlTopic: topics.control,
+    statusTopic: typeof topics.status === "string" ? topics.status : "",
+    eventTopic: typeof topics.events === "string" ? topics.events : "",
+  };
+}
+
+export async function testConnection(credentials, options = {}) {
+  const profile = normalizeCredentials(credentials);
+  const client = connectMqtt(profile, options);
+  try {
+    await onceConnected(client, options.timeoutMs);
+  } finally {
+    client.end(true);
+  }
+  return {
+    ok: true,
+    url: profile.url,
+    username: profile.username,
+    client_id: profile.clientId,
+    control_topic: profile.controlTopic,
+    status_topic: profile.statusTopic,
+  };
+}
+
+export function buildAudioControl(command, options = {}) {
+  const music = normalizeAudioCommand(command, options);
+  return {
+    schema: "weclawbot.control.v1",
+    id: string(options.id) || `audio_${crypto.randomUUID()}`,
+    kind: "music_command",
+    music,
+  };
+}
+
+export function normalizeAudioCommand(command, options = {}) {
+  const aliases = new Map([
+    ["resume", "play"],
+    ["prev", "previous"],
+    ["volume-up", "volume_up"],
+    ["volumeup", "volume_up"],
+    ["volup", "volume_up"],
+    ["volume-down", "volume_down"],
+    ["volumedown", "volume_down"],
+    ["voldown", "volume_down"],
+    ["reload", "reload"],
+    ["refresh", "reload"],
+  ]);
+  const raw = string(command).replace(/_/gu, "-").toLowerCase();
+  const normalized = aliases.get(raw) || raw.replace(/-/gu, "_");
+  const supported = new Set([
+    "play",
+    "pause",
+    "toggle",
+    "next",
+    "previous",
+    "seek",
+    "set_volume",
+    "volume_up",
+    "volume_down",
+    "reload",
+    "status",
+    "set_rule",
+  ]);
+  if (!supported.has(normalized)) throw new Error(`command_unsupported: ${command}`);
+
+  const music = { command: normalized };
+  if (normalized === "set_volume") {
+    const volume = Number(options.volume ?? options.value);
+    if (!Number.isFinite(volume) || volume < 0 || volume > 100) {
+      throw new Error("volume_invalid");
+    }
+    music.volume = Math.round(volume);
+  }
+  if (normalized === "seek") {
+    const position = Number(options.positionMs ?? options.position_ms ?? options.value);
+    if (!Number.isFinite(position) || position < 0) {
+      throw new Error("position_invalid");
+    }
+    music.position_ms = Math.round(position);
+  }
+  if (normalized === "set_rule") {
+    music.rule = validateRule(options.rule);
+  }
+  return music;
+}
+
+export function validateRule(rule) {
+  if (
+    !rule ||
+    rule.schemaVersion !== 1 ||
+    typeof rule.title !== "string" ||
+    !rule.title.trim() ||
+    !/^[0-9A-F]+$/u.test(rule.sourcePlaylist?.encryptedId || "")
+  ) {
+    throw new Error("rule_invalid");
+  }
+  return {
+    schemaVersion: 1,
+    title: rule.title.slice(0, 120),
+    source: string(rule.source || "NetEase Cloud Music").slice(0, 240),
+    sourcePlaylist: {
+      originalId: string(rule.sourcePlaylist.originalId),
+      encryptedId: string(rule.sourcePlaylist.encryptedId),
+    },
+    fetchLimit: clamp(Number(rule.fetchLimit) || 60, 10, 100),
+    targetTrackCount: clamp(Number(rule.targetTrackCount) || 20, 1, 40),
+    minimumTrackCount: clamp(Number(rule.minimumTrackCount) || 8, 1, 40),
+    qualityPolicy:
+      rule.qualityPolicy === "highest-available" ? "highest-available" : "bounded",
+    bitrateKbps: clamp(Number(rule.bitrateKbps) || 320, 64, 999_999),
+    refreshHintSeconds: Math.max(900, Number(rule.refreshHintSeconds) || 2700),
+  };
+}
+
+export async function publishAudioControl(credentials, control, options = {}) {
+  const profile = normalizeCredentials(credentials);
+  if (options.wait !== false && !profile.statusTopic) {
+    throw new Error("status_topic_missing");
+  }
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs) || 12_000);
+  const client = connectMqtt(profile, { timeoutMs });
+  try {
+    await onceConnected(client, timeoutMs);
+    if (options.wait === false) {
+      await publishJson(client, profile.controlTopic, control);
+      return { ok: true, published: true, applied: null };
+    }
+    await subscribe(client, profile.statusTopic);
+    const statusPromise = waitForStatus(client, {
+      correlationId: control.id,
+      timeoutMs,
+    });
+    await publishJson(client, profile.controlTopic, control);
+    const status = await statusPromise;
+    return { ok: status.kind === "applied", published: true, applied: true, status };
+  } finally {
+    client.end(true);
+  }
+}
+
+export function buildAgentPrompt(options = {}) {
+  const code = validateBindingCode(options.code);
+  const agentName = string(options.agentName || options.name || "agent");
+  const alias = string(options.alias || "音频设备");
+  const profile = string(options.profile || "深夜工作");
+  const expires = Number(options.expiresAt || options.expires_at || 0);
+  const expiresLine = expires > 0 ? `绑定码过期时间：${new Date(expires).toISOString()}` : "";
+  return [
+    `请作为我的 AI agent 绑定并控制一台 WeClawBot 音频输出设备。`,
+    `设备别名：${alias}`,
+    `绑定码：${code}`,
+    expiresLine,
+    `请在你的运行环境安装 npm 包 ${PACKAGE_NAME}，然后执行：`,
+    `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} bind ${code} --name ${shellToken(agentName)}`,
+    `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} doctor --online`,
+    `绑定成功后，把它作为默认 BGM/音乐输出设备。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、rule。`,
+    `如果我要播放「${profile}」，请优先执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} deepnight`,
+    `不要向设备写入音乐平台私钥；音乐平台授权、歌单刷新和长期规则由设备侧已配置的安全运行时处理。`,
+  ].filter(Boolean).join("\n");
+}
+
+export function summarizePlayback(status) {
+  const playback = status?.playback || {};
+  const track = playback.track
+    ? `${playback.track.artist || ""} - ${playback.track.title || ""}`
+      .replace(/^\s*-\s*|\s*-\s*$/gu, "")
+    : "";
+  return {
+    desired: string(playback.desired || "unknown"),
+    volume: playback.volume ?? null,
+    playlist: string(playback.playlist),
+    track_index: playback.track_index ?? null,
+    track_count: playback.track_count ?? null,
+    track,
+  };
+}
+
+function connectMqtt(profile, options = {}) {
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs) || 12_000);
+  return mqtt.connect(profile.url, {
+    clientId: profile.clientId,
+    username: profile.username,
+    password: profile.password,
+    clean: true,
+    reconnectPeriod: 0,
+    connectTimeout: timeoutMs,
+    protocolVersion: 4,
+  });
+}
+
+function onceConnected(client, timeoutMs = 12_000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(new Error("mqtt_connect_timeout")), timeoutMs);
+    const finish = (error) => {
+      clearTimeout(timer);
+      client.removeListener("connect", onConnect);
+      client.removeListener("error", onError);
+      error ? reject(error) : resolve();
+    };
+    const onConnect = () => finish();
+    const onError = (error) => finish(error);
+    client.once("connect", onConnect);
+    client.once("error", onError);
+  });
+}
+
+function publishJson(client, topic, value) {
+  return new Promise((resolve, reject) => {
+    client.publish(topic, JSON.stringify(value), { qos: 1, retain: false }, (error) => {
+      error ? reject(error) : resolve();
+    });
+  });
+}
+
+function subscribe(client, topic) {
+  return new Promise((resolve, reject) => {
+    client.subscribe(topic, { qos: 1 }, (error) => {
+      error ? reject(error) : resolve();
+    });
+  });
+}
+
+function waitForStatus(client, options) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => finish(new Error("device_status_timeout")),
+      options.timeoutMs,
+    );
+    const finish = (error, value) => {
+      clearTimeout(timer);
+      client.removeListener("message", onMessage);
+      error ? reject(error) : resolve(value);
+    };
+    const onMessage = (_topic, payload) => {
+      try {
+        const status = JSON.parse(payload.toString("utf8"));
+        if (
+          status?.schema === "weclawbot.device_status.v1" &&
+          status.correlation_id === options.correlationId &&
+          new Set(["applied", "rejected"]).has(status.kind)
+        ) {
+          finish(null, status);
+        }
+      } catch {
+        // Ignore unrelated or malformed status traffic.
+      }
+    };
+    client.on("message", onMessage);
+  });
+}
+
+function shellToken(value) {
+  const text = string(value) || "agent";
+  if (/^[A-Za-z0-9_./:@+-]+$/u.test(text)) return text;
+  return JSON.stringify(text);
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.min(maximum, Math.max(minimum, Math.round(value)));
+}
+
+function string(value) {
+  return typeof value === "string" ? value.trim() : "";
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@openbrt/audioctl",
+  "version": "0.1.0",
+  "description": "Generic WeClawBot audio-output control CLI and AI-agent plugin.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "weclawbot",
+    "audio",
+    "music",
+    "mqtt",
+    "esp32",
+    "agent",
+    "byoa",
+    "openclaw",
+    "codex",
+    "claude-code",
+    "hermes",
+    "workbuddy",
+    "netease-cloud-music"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "agent-plugin.json",
+    "bin",
+    "lib",
+    "rules",
+    "README.md"
+  ],
+  "bin": {
+    "audioctl": "bin/audioctl.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./manifest": "./agent-plugin.json",
+    "./rules/deepnight": "./rules/deepnight.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "node --check lib/index.mjs && node --check bin/audioctl.mjs && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "mqtt": "^5.15.1"
+  }
+}

package/rules/deepnight.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "title": "深夜工作",
+  "source": "网易云音乐官方歌单：深夜刷题党｜轻缓律动伴你专注学习",
+  "sourcePlaylist": {
+    "originalId": "8383869866",
+    "encryptedId": "661561242F7B3CE80B5AB760DB171EB4"
+  },
+  "fetchLimit": 60,
+  "targetTrackCount": 20,
+  "minimumTrackCount": 8,
+  "qualityPolicy": "highest-available",
+  "refreshHintSeconds": 21600
+}