roger-roger 0.1.3 → 0.1.8

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

@@ -110,17 +110,62 @@ function errorText(text) {
   }
 }
 
+/**
+ * What the pane's agent is working on, from its terminal title: Claude Code, Codex and others set it
+ * to the conversation's topic ("Home Assistant MCP setup"). Empty when the title is only the shell
+ * or the program's own name, which says nothing about the work.
+ */
+export function workFromTitle(title, agent = "") {
+  const t = str(title).replace(/^[^\p{L}\p{N}]+/u, "").trim();
+  if (!t) return "";
+  if (/[\\/]|\.exe$|^(powershell|pwsh|cmd|bash|zsh|fish|sh|node)$/i.test(t)) return "";
+  if (agent && t.toLowerCase() === String(agent).toLowerCase()) return "";
+  if (/^(claude( code)?|codex|opencode|gemini|cursor|copilot)$/i.test(t)) return "";
+  return t;
+}
+
+// Herdr is asked for the title at most this often per session; a label follows the topic, not keystrokes.
+const TITLE_EVERY_MS = 60_000;
+const titleAsked = new Map();
+
+/** The work to label with: the `--session` name if the agent gave one, else the pane's title. */
+async function workFor(session, run, now = Date.now()) {
+  if (str(session.name)) return str(session.name);
+  const last = titleAsked.get(session.id);
+  if (last && now - last.at < TITLE_EVERY_MS) return last.work;
+  let work = "";
+  try {
+    const out = await run(["agent", "get", session.herdr.pane], { bin: session.herdr.bin, socket: session.herdr.socket });
+    const agent = JSON.parse(out)?.result?.agent ?? {};
+    work = workFromTitle(agent.terminal_title_stripped ?? agent.terminal_title, agent.agent ?? session.agent);
+  } catch {
+    // No title is no label, not an error: the tab still gets the badge.
+  }
+  titleAsked.set(session.id, { at: now, work });
+  return work;
+}
+
 const inFlight = new Set();
 
 /**
  * Put the session's labels on its Herdr pane, if it has one and they are not there yet. Never
  * throws: a pane that can't be labelled is a line in the log, not a failed command. `touch` records
  * what was put on, so it isn't done again; `run` is the herdr invocation (replaced in tests).
+ * Without a `--session` name, the work is taken from the pane's terminal title.
  */
 export async function labelPane(session, { log = () => {}, touch = () => {}, run = runHerdr } = {}) {
-  const commands = labelCommands(session);
-  if (!commands.length || inFlight.has(session.id)) return { labelled: false };
+  if (!session?.herdr?.tab || !session?.herdr?.pane || inFlight.has(session.id)) return { labelled: false };
   inFlight.add(session.id);
+  let commands;
+  try {
+    commands = labelCommands({ ...session, name: await workFor(session, run) });
+  } catch {
+    commands = [];
+  }
+  if (!commands.length) {
+    inFlight.delete(session.id);
+    return { labelled: false };
+  }
   const done = { ...(session.herdrLabel ?? {}) };
   try {
     for (const args of commands) {

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

@@ -18,6 +18,7 @@ import { routeMessage } from "./router.mjs";
 import * as progressStore from "./progress.mjs";
 import * as sessions from "./sessions.mjs";
 import * as decisions from "./decisions.mjs";
+import * as activity from "./activity.mjs";
 
 const KEEP = 200;
 
@@ -166,6 +167,20 @@ export async function ingest(message, { log = () => {}, live = false, waiting =
   const route = entry.route;
   const files = entry.files ?? [];
   log(`message ${message.ts} → ${route.kind}${route.key ? ` ${route.key}` : route.id ? ` ${route.id}` : ""}`);
+  // An answer in a question's thread is logged when the question settles, as the answer it is.
+  if (route.kind !== "decision") {
+    const to = route.kind === "session" ? sessions.get(route.id) : route.kind === "progress" && route.session ? sessions.get(route.session) : null;
+    const where = { progress: "a note on the progress message", ask: "asked which agent", inbox: "saved for the next agent" }[route.kind] ?? "";
+    activity.record({
+      from: "user",
+      kind: "message",
+      agent: to ? activity.agentOf(sessions.decorate(to)) : null,
+      text: text || (files.length ? files.map((f) => f.name).join(", ") : ""),
+      detail: where,
+      at: tsIso(message.ts),
+      ref: message.ts,
+    });
+  }
 
   await addReaction(channel, message.ts, reactionFor(route)).catch((e) => log(`reaction failed: ${e.message}`));
 
@@ -268,6 +283,7 @@ export async function resolvePick(messageTs, sessionId, log = () => {}) {
   const chosen = sessionId === NOBODY ? null : sessions.get(sessionId);
   const route = chosen ? { kind: "session", id: chosen.id, via: "picked" } : { kind: "inbox" };
   writeState({ ...state, messages: state.messages.map((m) => (m.ts === messageTs ? { ...m, route } : m)) });
+  activity.retarget(messageTs, chosen ? activity.agentOf(sessions.decorate(chosen)) : null, chosen ? "" : "saved for the next agent");
 
   if (chosen) {
     deliver(chosen.id, { text: entry.text, by: entry.user, at: tsIso(entry.ts), ts: entry.ts, channel: entry.channel, via: "picked" });

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

@@ -95,6 +95,81 @@ export function applyLink(link, target, plan, fsx = fs, now = new Date()) {
   return { ...plan, done: true };
 }
 
+// ---------------------------------------------------------------- the agents' standing instructions
+
+/** Each agent's global instructions file: what it reads at the start of every session, everywhere. */
+export const INSTRUCTION_FILES = [
+  { id: "claude", label: "Claude Code", dir: [".claude"], file: "CLAUDE.md" },
+  { id: "codex", label: "Codex", dir: [".codex"], file: "AGENTS.md" },
+  { id: "opencode", label: "OpenCode", dir: [".config", "opencode"], file: "AGENTS.md" },
+  { id: "gemini", label: "Gemini CLI", dir: [".gemini"], file: "GEMINI.md" },
+];
+
+const MARK_START = "<!-- roger-roger:start -->";
+const MARK_END = "<!-- roger-roger:end -->";
+
+/** The standing instruction, between marks so it can be replaced or removed without touching anything else. */
+export const INSTRUCTIONS = [
+  MARK_START,
+  "- Always use the `roger-roger` skill (the `roger-roger` command, or `node <skill-dir>/scripts/roger-roger.mjs`): at the end of every turn, whatever its size, send a notification as the last action before the final reply, and use `ask` when blocked on a decision. Don't skip it because the task seemed quick or the user seems to be at the keyboard. On every call pass `--session` with what the work is, in three to six words (`--session \"billing refactor tests\"`), and `--agent-model`: the work names your Slack messages and your Herdr pane. Never put code, commands, paths or URLs in the spoken line (`--say`): say what the thing is and why, and leave the command itself to the written message. If the skill isn't available, say so once.",
+  MARK_END,
+].join("\n");
+
+/** Where each agent's file is, whether that agent is here, and whether the block is already in it. */
+export function instructionFiles(home = os.homedir(), fsx = fs) {
+  return INSTRUCTION_FILES.map((a) => {
+    const root = path.join(home, ...a.dir);
+    const file = path.join(root, a.file);
+    let text = "";
+    try {
+      text = fsx.readFileSync(file, "utf8");
+    } catch {}
+    return { ...a, root, path: file, present: fsx.existsSync(root), has: text.includes(MARK_START) };
+  });
+}
+
+const BLOCK = new RegExp(`\\n?${MARK_START}[\\s\\S]*?${MARK_END}\\n?`);
+
+/** The text with the block in it, replacing an older one or added at the end. */
+export function withInstructions(text) {
+  const body = String(text ?? "");
+  if (body.includes(MARK_START) && body.includes(MARK_END)) return body.replace(BLOCK, `\n${INSTRUCTIONS}\n`).replace(/^\n/, "");
+  if (!body.trim()) return `${INSTRUCTIONS}\n`;
+  return `${body.replace(/\s*$/, "")}\n\n${INSTRUCTIONS}\n`;
+}
+
+/** The text without the block; anything else in it is left exactly as it was. */
+export function withoutInstructions(text) {
+  const body = String(text ?? "");
+  if (!body.includes(MARK_START)) return body;
+  return body.replace(BLOCK, "\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").replace(/\n+$/, "\n");
+}
+
+export function addInstructions(file, fsx = fs) {
+  let text = "";
+  try {
+    text = fsx.readFileSync(file, "utf8");
+  } catch {}
+  const had = text.includes(MARK_START);
+  fsx.mkdirSync(path.dirname(file), { recursive: true });
+  fsx.writeFileSync(file, withInstructions(text), "utf8");
+  return { file, updated: had, added: !had };
+}
+
+export function removeInstructions(file, fsx = fs) {
+  let text;
+  try {
+    text = fsx.readFileSync(file, "utf8");
+  } catch {
+    return { file, removed: false };
+  }
+  if (!text.includes(MARK_START)) return { file, removed: false };
+  const rest = withoutInstructions(text);
+  if (rest.trim()) fsx.writeFileSync(file, rest, "utf8");
+  else fsx.rmSync(file, { force: true }); // ours was all there was
+  return { file, removed: true };
+}
+
 // ---------------------------------------------------------------- the global copy
 
 /**
@@ -478,6 +553,38 @@ export async function runInstall(args, { script, hooks, input = process.stdin, o
       }
     }
 
+    // ---- the standing instruction, so agents use it without being told each time
+    const instructionTargets = instructionFiles(home).filter((f) => f.present);
+    if (instructionTargets.length) {
+      const already = instructionTargets.filter((f) => f.has);
+      const yes = await ui.confirm({
+        message: already.length === instructionTargets.length ? "Keep telling your agents to always use roger-roger?" : "Tell your agents to always use roger-roger?",
+        yes: "Yes (recommended)",
+        hint: `a marked block in ${instructionTargets.map((f) => `~/${[...f.dir, f.file].join("/")}`).join(", ")}`,
+        initial: true,
+      });
+      if (yes) {
+        for (const f of instructionTargets) {
+          try {
+            const r = addInstructions(f.path);
+            ui.done(`${f.label}: ${r.added ? "instructions added" : "instructions refreshed"}`, f.path);
+            summary.push(`instructions: ${f.label}`);
+          } catch (e) {
+            ui.failed(`${f.label}: could not write ${f.path}`, e.message);
+          }
+        }
+      } else if (already.length) {
+        for (const f of already) {
+          try {
+            removeInstructions(f.path);
+            ui.done(`${f.label}: instructions removed`, f.path);
+          } catch (e) {
+            ui.failed(`${f.label}: could not change ${f.path}`, e.message);
+          }
+        }
+      }
+    }
+
     // ---- herdr
     let herdrDone = false;
     if (herdr) {
@@ -748,6 +855,7 @@ export async function uninstallFindings({ home = os.homedir(), env = process.env
   const global = globalCopy(env);
   return {
     links: skillFootprint(home),
+    instructions: instructionFiles(home).filter((f) => f.has),
     herdr: herdr && herdrHasPlugin(herdr) ? herdr : null,
     hookAgents,
     home: [rogerRogerHome(env), path.join(home, ".attention")].filter((d) => fs.existsSync(d)),
@@ -759,7 +867,15 @@ export async function uninstallFindings({ home = os.homedir(), env = process.env
 /** Everything but the Slack CLI, with no questions. Returns what was done. */
 export async function quietUninstall({ home = os.homedir(), env = process.env, hooks = null, script = "", slackCli = false } = {}) {
   const found = await uninstallFindings({ home, env, hooks, script });
-  const done = { daemonStopped: await stopDaemon(env), hooks: [], links: [], herdr: null, home: [], slackCli: false, global: null };
+  const done = { daemonStopped: await stopDaemon(env), hooks: [], links: [], instructions: [], herdr: null, home: [], slackCli: false, global: null };
+  for (const f of found.instructions) {
+    try {
+      removeInstructions(f.path);
+      done.instructions.push(f.path);
+    } catch (e) {
+      done.instructions.push({ file: f.path, error: e.message });
+    }
+  }
   for (const name of found.hookAgents) {
     try {
       hooks.agents[name].uninstall();
@@ -813,6 +929,7 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
     const labels = { claude: "Claude Code", opencode: "OpenCode", codex: "Codex" };
     const choices = [];
     if (found.links.length) choices.push({ value: "links", label: "The skill, for agents", hint: found.links.map((a) => a.label).join(", "), checked: true });
+    if (found.instructions.length) choices.push({ value: "instructions", label: "The standing instruction", hint: found.instructions.map((f) => `~/${[...f.dir, f.file].join("/")}`).join(", "), checked: true });
     if (found.hookAgents.length) choices.push({ value: "hooks", label: "Terminal-question hooks", hint: found.hookAgents.map((n) => labels[n] ?? n).join(", "), checked: true });
     if (found.herdr) choices.push({ value: "herdr", label: "The Herdr plugin", hint: "herdr plugin unlink", checked: true });
     if (found.home.length) choices.push({ value: "home", label: "Settings, Slack tokens, state", hint: found.home.join(", "), checked: true });
@@ -846,6 +963,17 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
         }
       }
     }
+    if (what.includes("instructions")) {
+      for (const f of found.instructions) {
+        try {
+          removeInstructions(f.path);
+          ui.done(`${f.label}: instruction removed`, f.path);
+          removed.push(`instructions: ${f.label}`);
+        } catch (e) {
+          ui.failed(`${f.label}: could not change ${f.path}`, e.message);
+        }
+      }
+    }
     if (what.includes("herdr")) {
       const r = herdrUnlink(found.herdr);
       if (r.ok) {
@@ -889,7 +1017,7 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
       "",
       ...removed.map((s) => `${c.green("•")} ${s}`),
       "",
-      c.dim("Lines about roger-roger in your own CLAUDE.md or AGENTS.md are yours, so they were left alone."),
+      c.dim("Only the marked roger-roger block was taken out of your CLAUDE.md or AGENTS.md; anything you wrote yourself is still there."),
       `Back any time: ${c.cyan("npx roger-roger@latest install")}`,
     ]);
     return 0;

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

@@ -535,8 +535,63 @@ export function slackText({ kind = "info", message, project, mention }) {
 
 /** What gets spoken: the agent's `--say` line, unless the user wants the message read verbatim. */
 export function speechText({ mode = "auto", message, say }) {
-  if (mode === "same") return message;
-  return say || message;
+  return speakable(mode === "same" ? message : say || message);
+}
+
+// A word that only makes sense on a screen: shell punctuation, a flag, a path, a quote, a template.
+const CODEISH = /[{}$|;<>=\\`"']|^--?[a-z]|[\w.~-]\/[\w.-]|^https?:|^[\w-]+\.[a-z]{2,4}[,.]?$|^\w+\(|\)$/i;
+
+/**
+ * Does this stretch read as code rather than as a sentence? `quoted` is for text already marked as
+ * code (in backticks): there one flag or path is enough. Loose text needs two, and a fair share.
+ */
+export function looksLikeCode(text, { quoted = false } = {}) {
+  const words = String(text).trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return false;
+  const codeish = words.filter((w) => CODEISH.test(w)).length;
+  if (words.length === 1) return words[0].length > 24 || /[{}$|;<>=\\/]/.test(words[0]);
+  if (quoted) return codeish >= 1;
+  return codeish >= 2 && codeish / words.length >= 0.3;
+}
+
+/** What a piece of code is, in words: "an ssh command", "a file", or just "a command". */
+function nameCode(code) {
+  const s = String(code).trim();
+  if (!/\s/.test(s) && /[\/\\]/.test(s) && !/^https?:/i.test(s)) return "a file";
+  const first = s.split(/\s+/)[0].replace(/^[^\w]+/, "");
+  // "an ssh", "an npm", "a git": a word with no vowel is spelt out, and f, h, l, m, n, r, s, x start with a vowel sound.
+  const an = /^[aeiou]/i.test(first) || (!/[aeiouy]/i.test(first) && /^[fhlmnrsx]/i.test(first));
+  if (/^[a-z][\w-]{1,15}$/i.test(first) && !/^(the|a|an|and|or|to|then)$/i.test(first)) return `${an ? "an" : "a"} ${first} command`;
+  return "a command";
+}
+
+/**
+ * The line as it should be heard. Nobody wants a voice reading out `ssh -o BatchMode=yes …` or a
+ * URL, so code is said as what it is: a fenced block becomes "the details are in Slack", inline
+ * code that is really code becomes "an lsblk command" or "a file", a link becomes "a link", and a
+ * stretch of bare command line becomes what it is too. Markdown emphasis goes; tone tags stay.
+ */
+export function speakable(text) {
+  let s = String(text ?? "");
+  s = s.replace(/```[\s\S]*?(```|$)/g, " (the details are in Slack) ");
+  s = s.replace(/`([^`\n]+)`/g, (_, code) => (looksLikeCode(code, { quoted: true }) ? nameCode(code) : code));
+  s = s.replace(/<?https?:\/\/[^\s>|]+(\|[^>]*)?>?/gi, "a link");
+  s = s
+    .split(/\n+|(?<=[.!?])\s+(?=[A-Z[])/)
+    .map((part) => {
+      // A sentence that ends in a command ("Can I run ssh -o … 'df -h'") keeps its words and names the command.
+      const words = part.trim().split(/\s+/);
+      const start = words.findIndex((w, i) => looksLikeCode(words.slice(i).join(" ")) && CODEISH.test(words[Math.min(i + 1, words.length - 1)]));
+      if (start < 0) return part;
+      return [...words.slice(0, start), nameCode(words.slice(start).join(" "))].join(" ");
+    })
+    .join(" ");
+  return s
+    .replace(/(^|\s)[*_~]+(?=\S)|(?<=\S)[*_~]+(?=\s|[,.!?;:]|$)/g, "$1")
+    .replace(/^\s*[>•-]\s+/gm, "")
+    .replace(/\s+([,.!?;:])/g, "$1")
+    .replace(/\s{2,}/g, " ")
+    .trim();
 }
 
 // Several agents share one pair of speakers, and a voice from the next room with no name on it is

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

@@ -465,6 +465,7 @@ async function main() {
     case "control":
     case "listen":
     case "snooze":
+    case "hush":
     case "tray":
     case "ask":
     case "wait":

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

@@ -11,6 +11,7 @@ import {
   rogerRogerHome, inQuietHours, listSounds, snoozeUntil,
 } from "./lib.mjs";
 import * as decisions from "./decisions.mjs";
+import * as activity from "./activity.mjs";
 import * as progressStore from "./progress.mjs";
 import * as sessions from "./sessions.mjs";
 import { PROVIDERS, catalog, keyFor, providerOf } from "./tts.mjs";
@@ -46,6 +47,8 @@ export function snapshot({ config = null, daemon = null, now = Date.now() } = {}
   return {
     updatedAt: new Date(now).toISOString(),
     daemon: daemon ? { pid: daemon.pid, slackConnected: Boolean(daemon.slackConnected) } : null,
+    // Who is speaking right now ({ who, since }), so the panel can offer to stop it.
+    speaking: daemon?.speaking ?? null,
     muted: {
       snoozeUntil: snoozeUntil(config, new Date(now)),
       quietHours: config?.quietHours ?? null,
@@ -61,6 +64,8 @@ export function snapshot({ config = null, daemon = null, now = Date.now() } = {}
       expiresAt: d.expiresAt,
     })),
     working: progressStore.active(now).map((p) => ({ key: p.key, headline: p.headline, nickname: p.nickname ?? null })),
+    // Who said what lately, newest first: the Log view.
+    log: activity.recent(60),
     // Everything `setup` can change, so the panel can offer it without asking anyone. Tokens live
     // in slack.json and the environment and are deliberately not here.
     settings: config

package/skills/roger-roger/tray/main.mjs

@@ -191,6 +191,8 @@ function tooltip(state, stale) {
  */
 function menu(state, spot) {
   const items = [];
+  // While a voice plays, the first thing on the menu stops it.
+  if (state.speaking) items.push({ id: "hush", label: state.speaking.who ? `Stop ${state.speaking.who} speaking` : "Stop the voice" }, { id: "sep0", label: "-" });
   if (state.muted?.snoozeUntil) {
     items.push({ id: "snooze:off", label: "Stop snoozing" });
   } else {
@@ -203,9 +205,10 @@ function menu(state, spot) {
   return { items };
 }
 
-const menuKey = (state, spot) => `${state.muted?.snoozeUntil ? "snoozed" : "awake"}:${spot ? "spot" : "free"}`;
+const menuKey = (state, spot) => `${state.muted?.snoozeUntil ? "snoozed" : "awake"}:${spot ? "spot" : "free"}:${state.speaking ? `speaking-${state.speaking.who ?? ""}` : "silent"}`;
 
 function onMenu(id) {
+  if (id === "hush") return run("hush");
   if (id === "snooze:off") return run("snooze", "off");
   if (id?.startsWith("snooze:")) return run("snooze", id.slice("snooze:".length));
   return null;
@@ -463,6 +466,7 @@ async function main() {
         return log(`the panel said something I could not read: ${message?.body ?? message}`);
       }
       if (ask.do === "snooze") return run("snooze", ask.value || "1h");
+      if (ask.do === "hush") return run("hush");
       if (ask.do === "hide") return hidePanel();
       if (ask.do === "keep-open") {
         keepOpen = Boolean(ask.value);