roger-roger 0.1.0

package/skills/roger-roger/scripts/agent.mjs

@@ -0,0 +1,132 @@
+// Working out who is calling, without knowing what they are.
+//
+// The skill is used by whatever agent the user runs, so nothing here may depend on one product.
+// Identity is resolved in layers, best first:
+//
+//   1. explicit      — `--session-id`, or ROGER_ROGER_SESSION_ID
+//   2. published     — a session id the agent puts in the environment. Some are named here, but
+//                      anything shaped like `*_SESSION_ID` counts, so an agent nobody has heard of
+//                      still gets a stable id.
+//   3. named         — the `--session` name the skill asks every agent to pass and keep for the
+//                      whole session, hashed with the directory. Works anywhere, for anything.
+//   4. terminal      — the terminal and directory, for a bare command with none of the above.
+//
+// Only the first two know anything about a particular agent; the rest work for anything that can run
+// a command. The daemon also remembers which session a terminal belonged to, so a later call that
+// leaves `--session` off still lands in the same place (see sessions.mjs).
+
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { herdrContext } from "./herdr.mjs";
+
+const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : "");
+const hash = (value) => crypto.createHash("sha1").update(value).digest("hex").slice(0, 16);
+
+/** Session-id variables we know by name, tried in this order. */
+const SESSION_VARS = [
+  "CLAUDE_CODE_SESSION_ID",
+  "CODEX_SESSION_ID", "CODEX_THREAD_ID", "CODEX_CONVERSATION_ID",
+  "OPENCODE_SESSION_ID", "OPENCODE_SESSION",
+  "CURSOR_SESSION_ID", "AIDER_SESSION_ID", "GEMINI_CLI_SESSION_ID",
+  "GOOSE_SESSION_ID", "AMP_SESSION_ID", "COPILOT_SESSION_ID", "AGENT_SESSION_ID",
+];
+
+/** …and the shape of one we don't, so a new agent needs no change here. */
+const SESSION_VAR = /^[A-Z][A-Z0-9_]*_(?:SESSION|THREAD|CONVERSATION)_ID$/;
+
+/** Things that own a "session" but are not the agent running this command. */
+const NOT_AN_AGENT = /^(?:AWS|AZURE|GCP|GOOGLE|GITHUB|GITLAB|DOCKER|K8S|KUBE|DB|DATABASE|BROWSER|SSH|XDG|DBUS|SYSTEMD|CI|BUILD|TEST|SENTRY|DATADOG|NEW_RELIC|OTEL)_/;
+
+/** Agent process ids, which tell a dead session from a quiet one. Only trusted when named. */
+const PID_VARS = ["ROGER_ROGER_AGENT_PID", "CLAUDE_PID", "CODEX_PID", "OPENCODE_PID", "AIDER_PID", "GOOSE_PID"];
+
+/** Env prefixes that give the agent's name, for the label on Slack messages. */
+const AGENT_PREFIXES = {
+  CLAUDECODE: "claude", CLAUDE_CODE: "claude", CLAUDE: "claude",
+  CODEX: "codex", OPENCODE: "opencode", CURSOR: "cursor", AIDER: "aider",
+  GEMINI_CLI: "gemini", GOOSE: "goose", AMP: "amp", COPILOT: "copilot",
+  CLINE: "cline", CONTINUE: "continue", WINDSURF: "windsurf", CRUSH: "crush", DROID: "droid",
+};
+
+const AGENT_NAMES = { "claude-code": "claude" };
+
+/**
+ * The agent's name from the environment: AI_AGENT if it is set (`claude-code_2-1-273_agent` →
+ * `claude`), otherwise whichever product's variables are present. Empty when nothing says.
+ */
+export function detectAgent(env = process.env) {
+  const declared = str(env.AI_AGENT).split(/[_\s/@]/)[0].toLowerCase();
+  if (declared) return AGENT_NAMES[declared] ?? declared;
+  const keys = Object.keys(env);
+  for (const [prefix, name] of Object.entries(AGENT_PREFIXES)) {
+    if (keys.some((k) => k === prefix || k.startsWith(`${prefix}_`))) return name;
+  }
+  return "";
+}
+
+/** A session id the agent published, from a name we know or from the shape of the variable. */
+export function publishedSessionId(env = process.env) {
+  for (const name of SESSION_VARS) if (str(env[name])) return str(env[name]);
+  for (const key of Object.keys(env).sort()) {
+    if (SESSION_VAR.test(key) && !NOT_AN_AGENT.test(key) && str(env[key])) return str(env[key]);
+  }
+  return "";
+}
+
+/** The agent's own process, when it says which. 0 when we can't know, which is not an error. */
+export function agentPid(env = process.env, about = {}) {
+  const candidates = [about.agentPid, ...PID_VARS.map((name) => env[name])];
+  for (const value of candidates) {
+    const pid = Number(value);
+    if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) return pid;
+  }
+  return 0;
+}
+
+/**
+ * A stand-in id for agents that publish nothing: the terminal and directory. Deliberately free of
+ * anything per-command — an agent that runs each tool call in a fresh shell must still look like one
+ * session, so the parent process is no use here.
+ */
+export function terminalFingerprint(env = process.env, cwd = process.cwd()) {
+  const parts = [
+    cwd,
+    env.WT_SESSION, env.TERM_SESSION_ID, env.ITERM_SESSION_ID, env.TMUX_PANE, env.STY,
+    env.SSH_TTY, env.WINDOWID, env.KONSOLE_DBUS_SESSION, env.VSCODE_PID, env.HERDR_PANE_ID,
+    env.SESSIONNAME, env.TERM_PROGRAM, env.TERM,
+    os.userInfo?.().username,
+  ];
+  return `term-${hash(parts.filter(Boolean).join("|"))}`;
+}
+
+/** True when the agent says the user is watching; unknown counts as not watching. */
+function isAttended(env) {
+  const key = Object.keys(env).find((k) => k.endsWith("_SESSION_ATTENDED"));
+  return key ? ["1", "true", "yes"].includes(String(env[key]).toLowerCase()) : false;
+}
+
+/**
+ * Who is calling. `about` is what this command was told: `sessionId` (--session-id), `session` (the
+ * --session name) and `agentPid` (--agent-pid). `source` records which layer answered, which
+ * `status` shows so an unfamiliar agent can be diagnosed.
+ */
+export function identity(env = process.env, cwd = process.cwd(), about = {}) {
+  const explicit = str(about.sessionId) || str(env.ROGER_ROGER_SESSION_ID);
+  const published = explicit || publishedSessionId(env);
+  const named = str(about.session) ? `named-${hash(`${cwd}|${str(about.session).toLowerCase()}`)}` : "";
+  const fingerprint = terminalFingerprint(env, cwd);
+  return {
+    id: published || named || fingerprint,
+    source: published ? (explicit ? "explicit" : "agent") : named ? "name" : "terminal",
+    fingerprint,
+    pid: agentPid(env, about),
+    cwd,
+    project: path.basename(cwd) || "",
+    host: os.hostname(),
+    agent: detectAgent(env),
+    attended: isAttended(env),
+    // The Herdr pane this runs in, if any, so the daemon can label it (herdr.mjs).
+    herdr: herdrContext(env),
+  };
+}

package/skills/roger-roger/scripts/audio.mjs

@@ -0,0 +1,392 @@
+// Sound playback, local speech, and synthesized speech. Speech is split into prepare (network)
+// and deliver (playback) so the audio can be ready before the notification sound plays.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { SOUNDS_DIR, duckFactor, rogerRogerHome, stripTags } from "./lib.mjs";
+import { providerOf, synthesize } from "./tts.mjs";
+import { withSpeaker } from "./speaker.mjs";
+
+/** Run a command to completion; resolves true only on a clean exit. Never rejects. */
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: "ignore", windowsHide: true, timeout: 120_000, ...opts });
+    } catch {
+      return resolve(false);
+    }
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+
+/** Try each [cmd, args] in order; true on the first that runs cleanly. */
+async function firstThatWorks(candidates, opts) {
+  for (const [cmd, args] of candidates) if (await run(cmd, args, opts)) return true;
+  return false;
+}
+
+export function soundFile(name) {
+  return path.join(SOUNDS_DIR, `${name}.wav`);
+}
+
+// Other apps' volume, turned down while the voice speaks and put back after. Windows keeps a volume
+// per app ("audio session") on the default output device; each is scaled from where the user had it
+// and restored to exactly that. The player's own session — it is the one speaking — is left alone.
+// Compiled only the first time it is needed, since it adds a moment to the player's start.
+const DUCKER_CS = `
+using System; using System.Collections.Generic; using System.Runtime.InteropServices; using System.Threading;
+[ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")] class RrEnumerator {}
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("A95664D2-9614-4F35-A746-DE8DB63617E6")]
+interface IRrEnumerator { int NotImpl(); [PreserveSig] int GetDefaultAudioEndpoint(int flow, int role, out IRrDevice device); }
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("D666063F-1587-4E43-81F1-B948E807363F")]
+interface IRrDevice { [PreserveSig] int Activate(ref Guid iid, int ctx, IntPtr p, [MarshalAs(UnmanagedType.IUnknown)] out object o); }
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("77AA99A0-1BD6-484F-8BC7-2C654C9A9B6F")]
+interface IRrSessionManager2 { int NotImpl1(); int NotImpl2(); [PreserveSig] int GetSessionEnumerator(out IRrSessionEnum e); }
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("E2F5BB11-0570-40CA-ACDD-3AA01277DEE8")]
+interface IRrSessionEnum { [PreserveSig] int GetCount(out int n); [PreserveSig] int GetSession(int i, out IRrSession s); }
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("bfb7ff88-7239-4fc9-8fa2-07c950be9c6d")]
+interface IRrSession {
+  [PreserveSig] int GetState(out int s); [PreserveSig] int GetDisplayName(out IntPtr p); [PreserveSig] int SetDisplayName(IntPtr v, IntPtr c);
+  [PreserveSig] int GetIconPath(out IntPtr p); [PreserveSig] int SetIconPath(IntPtr v, IntPtr c); [PreserveSig] int GetGroupingParam(out Guid g);
+  [PreserveSig] int SetGroupingParam(IntPtr g, IntPtr c); [PreserveSig] int RegisterAudioSessionNotification(IntPtr n);
+  [PreserveSig] int UnregisterAudioSessionNotification(IntPtr n); [PreserveSig] int GetSessionIdentifier(out IntPtr p);
+  [PreserveSig] int GetSessionInstanceIdentifier([MarshalAs(UnmanagedType.LPWStr)] out string p); [PreserveSig] int GetProcessId(out uint pid);
+}
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("87CE5498-68D6-44E5-9215-6DA47EF883D8")]
+interface IRrVolume { [PreserveSig] int SetMasterVolume(float v, ref Guid ctx); [PreserveSig] int GetMasterVolume(out float v); }
+public static class RrDucker {
+  static Dictionary<string, float> saved = new Dictionary<string, float>();
+  static List<KeyValuePair<string, IRrVolume>> Sessions(uint self) {
+    var list = new List<KeyValuePair<string, IRrVolume>>();
+    var en = (IRrEnumerator)(new RrEnumerator()); IRrDevice dev; en.GetDefaultAudioEndpoint(0, 1, out dev);
+    Guid iid = typeof(IRrSessionManager2).GUID; object o; dev.Activate(ref iid, 23, IntPtr.Zero, out o);
+    IRrSessionEnum e; ((IRrSessionManager2)o).GetSessionEnumerator(out e); int n; e.GetCount(out n);
+    for (int i = 0; i < n; i++) { IRrSession s; e.GetSession(i, out s); uint pid; s.GetProcessId(out pid);
+      if (pid == self) continue; string id; s.GetSessionInstanceIdentifier(out id); list.Add(new KeyValuePair<string, IRrVolume>(id, (IRrVolume)s)); }
+    return list;
+  }
+  // Down to level x their own volume in a few steps, so it sounds like a fade rather than a cut.
+  public static string Duck(float level, uint self) {
+    var all = Sessions(self); Guid g = Guid.Empty;
+    foreach (var kv in all) { float v; kv.Value.GetMasterVolume(out v); if (!saved.ContainsKey(kv.Key)) saved[kv.Key] = v; }
+    for (int step = 1; step <= 4; step++) {
+      foreach (var kv in all) { float from = saved[kv.Key]; kv.Value.SetMasterVolume(from * (1 - (1 - level) * step / 4f), ref g); }
+      Thread.Sleep(40);
+    }
+    var sb = new System.Text.StringBuilder(); foreach (var kv in saved) sb.Append(kv.Key).Append('\\u0001').Append(kv.Value.ToString(System.Globalization.CultureInfo.InvariantCulture)).Append('\\u0002');
+    return sb.ToString();
+  }
+  public static void Restore(uint self) {
+    var all = Sessions(self); Guid g = Guid.Empty;
+    for (int step = 1; step <= 4; step++) {
+      foreach (var kv in all) { float to; if (!saved.TryGetValue(kv.Key, out to)) continue; float now; kv.Value.GetMasterVolume(out now); kv.Value.SetMasterVolume(now + (to - now) * step / 4f, ref g); }
+      Thread.Sleep(40);
+    }
+    foreach (var kv in all) { float to; if (saved.TryGetValue(kv.Key, out to)) kv.Value.SetMasterVolume(to, ref g); }
+    saved.Clear();
+  }
+  // What a previous player saved before it died, so volumes it turned down don't stay down.
+  public static void Remember(string data) {
+    foreach (var pair in data.Split('\\u0002')) { var p = pair.Split('\\u0001'); if (p.Length == 2) saved[p[0]] = float.Parse(p[1], System.Globalization.CultureInfo.InvariantCulture); }
+  }
+}`;
+
+// On Windows every playback goes through one long-lived PowerShell. Starting PowerShell
+// takes 1.5-8 seconds, which is the whole gap between a ding and the speech after it if
+// each gets its own process. Commands are read one per line from stdin. Every argument is
+// base64 of UTF-8: Windows PowerShell reads stdin in the OEM code page, so a raw path or text
+// with anything beyond ASCII in it (a user name with an accent, say) arrived mangled.
+const PS_PLAYER = [
+  "Add-Type -AssemblyName System.Speech; $s = $null;",
+  "function Arg($b) { [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b)) }",
+  "while ($null -ne ($l = [Console]::In.ReadLine())) {",
+  "  try {",
+  "    $p = $l.Split([char]9, 2);",
+  "    if ($p[0] -eq 'PLAY') { (New-Object System.Media.SoundPlayer (Arg $p[1])).PlaySync() }",
+  "    elseif ($p[0] -eq 'DUCKINIT') { if (-not ('RrDucker' -as [type])) { Add-Type -TypeDefinition (Arg $p[1]) } }",
+  "    elseif ($p[0] -eq 'DUCK') { $d = [RrDucker]::Duck([float](Arg $p[1]), [uint32]$PID); [Console]::Out.WriteLine('DATA ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($d))) }",
+  "    elseif ($p[0] -eq 'UNDUCK') { [RrDucker]::Restore([uint32]$PID) }",
+  "    elseif ($p[0] -eq 'REMEMBER') { [RrDucker]::Remember((Arg $p[1])) }",
+  "    elseif ($p[0] -eq 'SAY') {",
+  "      if (-not $s) { $s = New-Object System.Speech.Synthesis.SpeechSynthesizer }",
+  "      $s.Speak((Arg $p[1]))",
+  "    }",
+  "    [Console]::Out.WriteLine('OK')",
+  "  } catch { [Console]::Out.WriteLine('ERR ' + $_.Exception.Message) }",
+  "  [Console]::Out.Flush()",
+  "}",
+].join(" ");
+
+let session = null;
+
+// Longer than any sound or spoken line, so only a player that has wedged ever reaches it.
+const REQUEST_TIMEOUT_MS = 120_000;
+
+const b64 = (text) => Buffer.from(text, "utf8").toString("base64");
+
+function windowsSession() {
+  if (session) return session;
+  const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", PS_PLAYER], {
+    stdio: ["pipe", "pipe", "ignore"],
+    windowsHide: true,
+  });
+  const waiters = [];
+  let buffer = "";
+  let pendingData = null;
+  let dead = null;
+  // A dead player is forgotten, so the next request starts a new one; otherwise every sound after
+  // the first failure failed too, until the daemon was restarted.
+  const fail = (why) => {
+    dead ??= why;
+    if (session === self) session = null;
+    while (waiters.length) waiters.shift()(`ERR ${dead}`);
+  };
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      // DUCK hands back what it saved on a line of its own, before its OK. The two are one answer.
+      if (line.startsWith("DATA ")) {
+        pendingData = line;
+        continue;
+      }
+      const answer = line === "OK" && pendingData ? pendingData : line;
+      pendingData = null;
+      waiters.shift()?.(answer);
+    }
+  });
+  child.stdin.on("error", () => fail("audio player is not running"));
+  child.on("error", (e) => fail(`powershell unavailable: ${e.message}`));
+  child.on("exit", () => fail("audio player exited"));
+
+  let queue = Promise.resolve();
+  const self = {
+    request(command) {
+      const reply = queue.then(() => new Promise((resolve) => {
+        if (dead) return resolve(`ERR ${dead}`);
+        // A player that stops answering would hold up every request queued behind it for good.
+        // It is killed and forgotten instead; the queue moves on, and the next request starts afresh.
+        const timer = setTimeout(() => {
+          fail("audio player stopped responding");
+          child.kill();
+        }, REQUEST_TIMEOUT_MS);
+        waiters.push((line) => {
+          clearTimeout(timer);
+          resolve(line);
+        });
+        child.stdin.write(`${command}\n`);
+      }));
+      queue = reply;
+      return reply.then((line) => {
+        if (line.startsWith("DATA ")) return Buffer.from(line.slice(5), "base64").toString("utf8");
+        if (line !== "OK") throw new Error(line.replace(/^ERR\s*/, "") || "playback failed");
+        return "";
+      });
+    },
+    close() {
+      if (session === self) session = null;
+      child.stdin.end();
+    },
+  };
+  session = self;
+  return self;
+}
+
+/** Start the audio backend ahead of time (Windows only; elsewhere players start fast). */
+export function warmUpAudio() {
+  if (process.platform === "win32") windowsSession();
+}
+
+/** Let the process exit: ends the Windows player once queued playback has finished. */
+export function closeAudio() {
+  session?.close();
+}
+
+export async function playWav(file) {
+  if (!fs.existsSync(file)) throw new Error(`no such sound file: ${file}`);
+  let ok;
+  if (process.platform === "win32") {
+    return windowsSession().request(`PLAY\t${b64(file)}`);
+  } else if (process.platform === "darwin") {
+    ok = await run("afplay", [file]);
+  } else {
+    ok = await firstThatWorks([
+      ["paplay", [file]],
+      ["pw-play", [file]],
+      ["aplay", ["-q", file]],
+      ["ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet", file]],
+    ]);
+  }
+  if (!ok) throw new Error("no working audio player found (tried the platform defaults)");
+}
+
+let tempCounter = 0;
+export async function playWavBuffer(wav) {
+  const file = path.join(os.tmpdir(), `roger-roger-${process.pid}-${Date.now()}-${tempCounter++}.wav`);
+  fs.writeFileSync(file, wav);
+  try {
+    await playWav(file);
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
+export async function speakLocally(text) {
+  const plain = stripTags(text);
+  let ok;
+  if (process.platform === "win32") {
+    return windowsSession().request(`SAY\t${b64(plain)}`);
+  } else if (process.platform === "darwin") {
+    ok = await run("say", [plain]);
+  } else {
+    ok = await firstThatWorks([
+      ["spd-say", ["-w", plain]],
+      ["espeak-ng", [plain]],
+      ["espeak", [plain]],
+    ]);
+  }
+  if (!ok) throw new Error("no local speech synthesiser found");
+}
+
+// ---------------------------------------------------------------- other sounds, turned down
+
+const duckFile = () => path.join(rogerRogerHome(), "ducked.txt");
+
+/** The player's first duck: compile the helper, and put back anything a crashed player left down. */
+async function duckPlayer() {
+  const player = windowsSession();
+  if (player.ducker) return player;
+  await player.request(`DUCKINIT\t${b64(DUCKER_CS)}`);
+  try {
+    const left = fs.readFileSync(duckFile(), "utf8");
+    if (left) {
+      await player.request(`REMEMBER\t${b64(left)}`);
+      await player.request("UNDUCK");
+    }
+    fs.rmSync(duckFile(), { force: true });
+  } catch {
+    // Nothing was left down.
+  }
+  player.ducker = true;
+  return player;
+}
+
+/**
+ * Turn everything else down for the length of `fn`, then back up. Windows only for now; elsewhere
+ * it just runs `fn`. What was turned down is written to a file first, so a player that dies in the
+ * middle doesn't leave the user's music quiet for good — the next one puts it back.
+ */
+export async function withOthersQuieter(config, fn) {
+  const level = config ? duckFactor(config) : 1;
+  if (level >= 1 || process.platform !== "win32") return fn();
+  let player;
+  try {
+    player = await duckPlayer();
+    const saved = await player.request(`DUCK\t${b64(String(level))}`);
+    if (saved) fs.writeFileSync(duckFile(), saved, "utf8");
+  } catch {
+    // Not being able to turn other things down is no reason not to speak.
+    return fn();
+  }
+  try {
+    return await fn();
+  } finally {
+    await player.request("UNDUCK").catch(() => {});
+    fs.rmSync(duckFile(), { force: true });
+  }
+}
+
+/** Synthesize `text` with the configured provider and return it as a WAV buffer (nothing is played). */
+export async function speechAudio(text, config) {
+  return synthesize(text, config);
+}
+
+/** Map with at most `limit` jobs in flight; results keep input order. */
+export async function mapPool(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+/** Fetch the audio for a line up front. Never rejects: failures come back as `{ error }`. */
+export function prepareSpeech(text, config, { local = false } = {}) {
+  if (local) return Promise.resolve({ skipped: true });
+  return synthesize(text, config).then((wav) => ({ wav }), (e) => ({ error: e.message }));
+}
+
+/** Play prepared audio; else the local synthesiser; else (if nothing else made a noise) the ding. */
+export async function deliverSpeech(prepared, text, config, { dingIfSilent = false } = {}) {
+  const engine = providerOf(config).id;
+  const errors = prepared.error ? [`${engine}: ${prepared.error}`] : [];
+  if (prepared.wav) {
+    try {
+      await playWavBuffer(prepared.wav);
+      return { ok: true, engine, voice: config.voice };
+    } catch (e) {
+      errors.push(`playback: ${e.message}`);
+    }
+  }
+  if (config.localFallback || prepared.skipped) {
+    try {
+      await speakLocally(text);
+      return { ok: true, engine: "local", errors };
+    } catch (e) {
+      errors.push(`local: ${e.message}`);
+    }
+  }
+  if (dingIfSilent) {
+    try {
+      await playWav(soundFile(config.sound));
+      return { ok: true, engine: "sound", errors };
+    } catch (e) {
+      errors.push(`sound: ${e.message}`);
+    }
+  }
+  return { ok: false, errors };
+}
+
+/**
+ * The audible part of an alert. Speech is synthesized before the sound starts, so the
+ * voice follows the ding immediately instead of after a network round trip — and before
+ * the speaker is claimed, so a queued agent waits for playback, not for the network.
+ * The ding and the voice after it are one turn: another agent cannot cut between them.
+ */
+export async function playAlert({ methods, config, text, prepared }) {
+  const results = {};
+  const wantsSpeech = methods.includes("speech");
+  if (wantsSpeech || methods.includes("sound")) warmUpAudio();
+  const speech = wantsSpeech ? await (prepared ?? prepareSpeech(text, config)) : null;
+  if (!wantsSpeech && !methods.includes("sound")) return results;
+
+  // The ding and the voice are one announcement, so everything else goes quiet for both of them.
+  return withSpeaker((turn) => withOthersQuieter(wantsSpeech ? config : null, async () => {
+    if (methods.includes("sound")) {
+      try {
+        await playWav(soundFile(config.sound));
+        results.sound = { ok: true, sound: config.sound };
+      } catch (e) {
+        results.sound = { ok: false, error: e.message };
+      }
+    }
+    if (wantsSpeech) {
+      results.speech = await deliverSpeech(speech, text, config, { dingIfSilent: !methods.includes("sound") });
+    }
+    if (turn.waitedMs > 0) results.queued = { waitedMs: turn.waitedMs, ...(turn.tookOver ? { tookOver: true } : {}) };
+    return results;
+  }));
+}

package/skills/roger-roger/scripts/client.mjs

@@ -0,0 +1,121 @@
+// The CLI's side of the socket. One command, one connection: connect, ask, print, exit.
+//
+// If nothing is listening, the daemon is started and we try again. Several agents racing to start it
+// is fine — only one can bind the socket, and the losers connect to the winner.
+
+import net from "node:net";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import { machineEnv } from "./lib.mjs";
+import { lineReader, send, socketPath } from "./protocol.mjs";
+
+const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), "daemon.mjs");
+const START_TIMEOUT_MS = 15_000;
+const RETRY_MS = 120;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function tryConnect(target) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(target);
+    const fail = (e) => {
+      socket.destroy();
+      reject(e);
+    };
+    socket.once("error", fail);
+    socket.once("connect", () => {
+      socket.removeListener("error", fail);
+      resolve(socket);
+    });
+  });
+}
+
+/**
+ * Start the daemon in the background. It detaches, so it outlives this command — which is why it
+ * starts in the user's home directory rather than the caller's project (a process sitting in a
+ * folder stops Windows deleting or renaming it, and the home directory is the one folder nobody
+ * does that to), and without the caller's session variables (it serves every agent, so it must not
+ * look like this one; the tray it starts inherits whatever it has).
+ */
+export function startDaemon(env = process.env) {
+  const child = spawn(process.execPath, [DAEMON], {
+    cwd: os.homedir(),
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: machineEnv(env),
+  });
+  child.unref();
+}
+
+/**
+ * A connection to the daemon, starting it if it isn't running yet. Throws only when it can't be
+ * reached at all, which is the CLI's signal to fall back to doing the work in-process.
+ */
+export async function connect({ start = true, timeoutMs = START_TIMEOUT_MS, env = process.env } = {}) {
+  const target = socketPath(env);
+  try {
+    return await tryConnect(target);
+  } catch (e) {
+    if (!start || env.ROGER_ROGER_NO_DAEMON === "1") throw e;
+  }
+  startDaemon(env);
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    await sleep(RETRY_MS);
+    try {
+      return await tryConnect(target);
+    } catch (e) {
+      last = e;
+    }
+  }
+  throw new Error(`the roger-roger daemon did not start within ${Math.round(timeoutMs / 1000)}s (${last?.code ?? last?.message ?? "no reason given"})`);
+}
+
+/** Send one request on an open socket. Events arrive first; the reply resolves the promise. */
+export function request(socket, { cmd, args = {}, session = null, onEvent }) {
+  return new Promise((resolve, reject) => {
+    const n = 1;
+    let settled = false;
+    // Set once the daemon says it has the command. After that a lost connection is an unknown
+    // outcome, not a failure to deliver, so the caller must not quietly do it a second time.
+    let acknowledged = false;
+    // Set once the command is only waiting, with the time it would have waited until.
+    let parkedUntil = null;
+    const done = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      fn(value);
+    };
+    socket.setEncoding("utf8");
+    socket.on("data", lineReader((message) => {
+      if (message.n !== n) return;
+      if (message.event) {
+        if (message.event === "received") acknowledged = true;
+        if (message.event === "parked") parkedUntil = message.data?.until ?? null;
+        return onEvent?.(message.event, message.data);
+      }
+      if (message.ok) return done(resolve, { data: message.data, code: message.code ?? 0 });
+      const error = new Error(message.error ?? "the daemon refused the request");
+      error.code = message.code ?? 1;
+      error.data = message.data;
+      done(reject, error);
+    }));
+    socket.on("error", (e) => done(reject, Object.assign(e, { acknowledged, parkedUntil })));
+    socket.on("close", () => done(reject, Object.assign(new Error("the daemon closed the connection"), { acknowledged, parkedUntil })));
+    if (!send(socket, { n, cmd, args, session })) done(reject, new Error("could not write to the daemon"));
+  });
+}
+
+/** Connect, ask one thing, disconnect. */
+export async function call(cmd, args = {}, { session = null, onEvent, env = process.env } = {}) {
+  const socket = await connect({ env });
+  try {
+    return await request(socket, { cmd, args, session, onEvent });
+  } finally {
+    socket.end();
+  }
+}