roger-roger 0.1.0

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

@@ -0,0 +1,536 @@
+#!/usr/bin/env node
+// roger-roger: notify the user via Slack, a sound, and/or speech, and ask them to choose
+// between options with Slack buttons. Zero dependencies; Node 18+ (22+ for `ask`).
+//
+// This is the thin end of the skill. The work happens in one long-lived daemon that owns Slack, the
+// speakers and the state; this parses the command, hands it over, and prints the one JSON object it
+// gets back. If the daemon can't be reached the same handlers run here instead, which still works
+// for everything except Slack buttons, since those need a live connection to arrive.
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULTS, DUCK_MODES, KINDS, METHODS, ON_EXPIRE, SPEECH_MODES, WHEN_MODES,
+  applySetup, rogerRogerHome, configPath, listArg, listSounds, loadConfig, migrateLegacyHome, parseArgs,
+  readSlackCredentials, saveConfig, slackAppToken, slackToken,
+} from "./lib.mjs";
+import { NAMES } from "./names.mjs";
+import { PROVIDERS, SPEECH_SETUP, catalog, keyFor, providerOf } from "./tts.mjs";
+import { call, connect, request } from "./client.mjs";
+import { identity } from "./protocol.mjs";
+import { FROM_HOOKS, HANDLERS, owedTo } from "./handlers.mjs";
+import { closeAudio } from "./audio.mjs";
+import { createApp, hooksConfig, loginFinish, loginStart, runHook, setupStatus } from "./slackapp.mjs";
+import { findCli, installCli } from "./slackcli.mjs";
+import { daemonRunning } from "./daemon.mjs";
+import * as sessions from "./sessions.mjs";
+import * as inbox from "./inbox.mjs";
+import { labelPane } from "./herdr.mjs";
+import { fileURLToPath } from "node:url";
+import { claudeHookRequest, claudeSettingsPath, claudeStatus, installClaude, readStdin, uninstallClaude } from "./hooks.mjs";
+import { codexHome, codexHookRequest, codexStatus, installCodex, uninstallCodex } from "./hooks-codex.mjs";
+import { installOpencode, opencodeConfigDir, opencodeHookRequest, opencodeStatus, uninstallOpencode } from "./hooks-opencode.mjs";
+import { runInstall } from "./install.mjs";
+
+function out(obj, code = 0) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+  process.exitCode = code;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------- talking to the daemon
+
+/** Who is asking: the agent session, and what it has told us about itself. */
+function who(args = {}) {
+  // The tray runs commands for the user, not for any agent: nothing it does should land on, or
+  // release, some agent's session.
+  if (process.env.ROGER_ROGER_CALLER === "tray") return { identity: null, about: {} };
+  const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+  // `--session` doubles as identity for agents that publish none of their own, so it is passed to
+  // both: what to call this work, and how to recognise the same session next time.
+  const about = { session: str(args.session), sessionId: str(args["session-id"]), agentPid: args["agent-pid"] };
+  return {
+    identity: identity(process.env, process.cwd(), about),
+    about: { name: about.session, model: str(args["agent-model"]), agent: str(args.agent) },
+  };
+}
+
+/** Everything the daemon can't work out for itself, because it runs in another directory. */
+function normalize(args) {
+  const normalized = { ...args };
+  normalized.project = args.project === undefined ? path.basename(process.cwd()) : String(args.project);
+  const files = listArg(args.attach);
+  if (files.length) {
+    normalized.attach = files.map((f) => {
+      const full = path.resolve(process.cwd(), f);
+      if (!fs.existsSync(full) || !fs.statSync(full).isFile()) throw new Error(`--attach: no such file: ${f}`);
+      return full;
+    });
+  }
+  if (typeof args["draft-file"] === "string") {
+    normalized.draft = fs.readFileSync(path.resolve(process.cwd(), args["draft-file"]), "utf8");
+  }
+  return normalized;
+}
+
+/** Run a command here, when no daemon can be reached. Slack buttons won't arrive; nothing else changes. */
+async function runLocally(cmd, args, session) {
+  const handler = HANDLERS[cmd];
+  if (!handler) throw new Error(`unknown command "${cmd}"`);
+  const config = loadConfig();
+  const record = session.identity ? sessions.register(session.identity, session.about) : null;
+  if (record) labelPane(sessions.decorate(record), { touch: sessions.touch }).catch(() => {});
+  let lastSync = 0;
+  const ctx = {
+    config,
+    session: record ? sessions.decorate(record) : null,
+    identity: session.identity,
+    log: () => {},
+    daemon: false,
+    emit: () => {},
+    idle: sleep,
+    waiting: () => () => {},
+    async catchUp() {
+      if (Date.now() - lastSync < 15_000) return;
+      lastSync = Date.now();
+      await inbox.sync().catch(() => {});
+    },
+  };
+  const result = (await handler(ctx, args)) ?? {};
+  if (FROM_HOOKS.has(cmd)) return result;
+  return { ...result, data: await owedTo(ctx, result.data).catch(() => result.data) };
+}
+
+// Commands with nothing to undo. If the daemon goes away mid-flight these can just be asked
+// again; anything that posts, plays or hands something over must not be.
+const REPEATABLE = new Set(["listen", "wait", "check", "status", "sessions", "decisions", "ping"]);
+
+/** Hand a command to the daemon, or do it here if there isn't one. */
+async function run(cmd, rawArgs) {
+  const args = normalize(rawArgs);
+  const session = who(args);
+  try {
+    const { data, code } = await call(cmd, args, { session });
+    return out(data, code);
+  } catch (e) {
+    // A refusal from the daemon is the answer; only a transport failure means we do it ourselves.
+    if (typeof e.code === "number") return out({ ok: false, error: e.message }, e.code);
+    // It had finished the doing and was only waiting, so the waiting can be picked up again — this
+    // is what keeps a parked `listen` alive when the daemon hands over to a newer one.
+    if (e.parkedUntil) {
+      const left = Math.round((Date.parse(e.parkedUntil) - Date.now()) / 1000);
+      if (left <= 1) return out({ ok: false, woke: "timeout" }, 4);
+      try {
+        const { data, code } = await call("listen", { wait: `${left}s` }, { session });
+        return out(data, code);
+      } catch (retry) {
+        if (typeof retry.code === "number") return out({ ok: false, error: retry.message }, retry.code);
+      }
+    }
+    // The daemon had it and went away mid-command. It may well have done the thing, so doing it
+    // here too would double it — say so instead. Unless there was nothing to do twice: a command
+    // that only waits or reads can simply ask again, which is what a parked `listen` needs when the
+    // daemon hands over to a newer one.
+    if (e.acknowledged && REPEATABLE.has(cmd)) {
+      try {
+        const { data, code } = await call(cmd, args, { session });
+        return out(data, code);
+      } catch (retry) {
+        if (typeof retry.code === "number") return out({ ok: false, error: retry.message }, retry.code);
+      }
+    }
+    if (e.acknowledged) {
+      return out({ ok: false, error: `the daemon took the command and then went away (${e.message}); it was not run again here, in case it already happened` }, 1);
+    }
+    try {
+      const { data, code } = await runLocally(cmd, args, session);
+      return out({ ...data, daemon: `unreachable (${e.message}) - ran in this process, so Slack buttons will not be received` }, code);
+    } catch (local) {
+      return out({ ok: false, error: local.message }, typeof local.code === "number" ? local.code : 1);
+    }
+  }
+}
+
+/** Ask the daemon something without starting one. */
+async function askDaemon(cmd) {
+  const socket = await connect({ start: false });
+  try {
+    return await request(socket, { cmd, session: who() });
+  } finally {
+    socket.end();
+  }
+}
+
+// ---------------------------------------------------------------- local commands
+
+async function status() {
+  const file = configPath();
+  let config = null;
+  let error;
+  try {
+    config = loadConfig(file);
+  } catch (e) {
+    error = `config file is unreadable: ${e.message}`;
+  }
+  const rawAppToken = (process.env.ROGER_ROGER_SLACK_APP_TOKEN || process.env.SLACK_APP_TOKEN || "").trim();
+
+  let daemon;
+  try {
+    daemon = { running: true, ...(await askDaemon("status")).data };
+  } catch (e) {
+    daemon = { running: daemonRunning(), reachable: false, reason: e.message };
+  }
+
+  out({
+    configured: Boolean(config),
+    configPath: file,
+    ...(error ? { error } : {}),
+    config: config ?? undefined,
+    env: {
+      slackToken: Boolean(slackToken()),
+      slackTokenSource: readSlackCredentials() ? "slack-setup" : slackToken() ? "environment" : null,
+      slackAppToken: Boolean(slackAppToken()),
+      ...(rawAppToken && !slackAppToken()
+        ? { slackAppTokenWarning: "the Slack app token is not an app-level xapp- token, so `ask` is unavailable (see SKILL.md, Requirements)" }
+        : {}),
+      // Who speaks, where its key is read from, and whether anything is there. Never the key itself.
+      speechProvider: providerOf(config).id,
+      speechKey: Boolean(keyFor(config).value),
+      speechKeyVar: keyFor(config).name,
+    },
+    daemon,
+    sessions: sessions.live().map((s) => ({ nickname: s.nickname, swatch: s.swatch, project: s.project, state: s.state, queued: s.queue?.length ?? 0 })),
+    platform: process.platform,
+    options: {
+      methods: METHODS,
+      sounds: listSounds(),
+      speechProviders: Object.values(PROVIDERS).map((p) => ({ id: p.id, label: p.label, keyVars: p.keyVars })),
+      // The configured provider's; `voices --refresh` fetches the real list.
+      voices: catalog(providerOf(config).id).voices,
+      models: catalog(providerOf(config).id).models,
+      speech: SPEECH_MODES,
+      duck: DUCK_MODES,
+      when: WHEN_MODES,
+      kinds: KINDS,
+      onExpire: ON_EXPIRE,
+      names: NAMES,
+    },
+    defaults: DEFAULTS,
+  });
+}
+
+function setup(args) {
+  const file = configPath();
+  let base = null;
+  try {
+    base = loadConfig(file);
+  } catch {
+    // An unreadable file is replaced rather than blocking setup.
+  }
+  const config = applySetup(base, args, undefined, SPEECH_SETUP);
+  saveConfig(config, file);
+  out({ ok: true, configPath: file, config });
+}
+
+async function slackSetup(args) {
+  const step = args._[0] ?? "status";
+  if (step === "status") return out(await setupStatus());
+  if (step === "install-cli") return out(await installCli());
+  // slackapp.mjs finds the CLI itself; looking here too only gives the friendlier message first.
+  // findCli runs the binary to read its version, so it has to be awaited: the bare promise is
+  // always truthy and the check never fired.
+  if (step === "login") {
+    if (!(await findCli())) throw new Error("the Slack CLI isn't installed: run `slack-setup install-cli` first");
+    if (args.challenge === undefined) return out(await loginStart());
+    if (!args.ticket) throw new Error("pass the ticket from `slack-setup login` with --ticket, alongside --challenge");
+    return out(await loginFinish({ challenge: String(args.challenge), ticket: String(args.ticket) }));
+  }
+  if (step === "create") {
+    if (!(await findCli())) throw new Error("the Slack CLI isn't installed: run `slack-setup install-cli` first");
+    return out(await createApp({ teamId: args.team ? String(args.team) : undefined }));
+  }
+  throw new Error(`unknown slack-setup step "${step}" (status, install-cli, login, create)`);
+}
+
+async function daemonCommand(args) {
+  const step = args._[0] ?? "status";
+  if (step === "status") {
+    try {
+      return out({ ok: true, running: true, ...(await askDaemon("status")).data });
+    } catch (e) {
+      return out({ ok: false, running: false, reason: e.message, home: rogerRogerHome() });
+    }
+  }
+  if (step === "stop") {
+    try {
+      return out((await askDaemon("stop")).data);
+    } catch {
+      return out({ ok: true, running: false, note: "no daemon was running" });
+    }
+  }
+  if (step === "start") {
+    const { data } = await call("ping", {}, { session: who() });
+    return out({ ok: true, ...data });
+  }
+  throw new Error(`unknown daemon command "${step}" (status, start, stop)`);
+}
+
+// ---------------------------------------------------------------- agent hooks
+
+const SCRIPT = fileURLToPath(import.meta.url);
+
+/** One line per hook run, so "why didn't it ping me?" has an answer. Kept small. */
+function hookLog(line) {
+  try {
+    const file = path.join(rogerRogerHome(), "hooks.log");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (fs.existsSync(file) && fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`);
+    fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // A hook that can't log still must not fail.
+  }
+}
+
+// Each agent's hooks: how to read what it sends, and how to install them. Claude Code and Codex run a
+// command per hook; OpenCode loads a plugin that forwards its events to the same command.
+const AGENTS = {
+  claude: {
+    parse: claudeHookRequest,
+    status: claudeStatus,
+    install: installClaude,
+    uninstall: uninstallClaude,
+    present: () => fs.existsSync(path.dirname(claudeSettingsPath())),
+    describe: (p) => `${p?.hook_event_name ?? "no payload"}${p?.notification_type ? ` (${p.notification_type})` : ""}`,
+  },
+  opencode: {
+    parse: opencodeHookRequest,
+    status: opencodeStatus,
+    install: installOpencode,
+    uninstall: uninstallOpencode,
+    present: () => fs.existsSync(opencodeConfigDir()),
+    describe: (p) => p?.type ?? "no payload",
+  },
+  codex: {
+    parse: codexHookRequest,
+    status: codexStatus,
+    install: installCodex,
+    uninstall: uninstallCodex,
+    present: () => fs.existsSync(codexHome()),
+    describe: (p) => `${p?.hook_event_name ?? "no payload"}${p?.tool_name ? ` (${p.tool_name})` : ""}`,
+  },
+};
+
+/** Ask the daemon, or do it here when the daemon is from a copy of the skill that predates hooks. */
+async function sendPermission(args, session) {
+  try {
+    return await call("permission", args, { session });
+  } catch (e) {
+    // A daemon from an older copy of the skill doesn't know the command yet (exit 2): do it here.
+    // Anything else numeric is a real answer; a lost connection after "received" may have done it.
+    if (e.acknowledged || (typeof e.code === "number" && e.code !== 2)) throw e;
+    return runLocally("permission", args, session);
+  }
+}
+
+/** How long a question waits in the terminal before the ping, for agents that can't tell if anyone is typing. */
+function terminalWait() {
+  try {
+    const seconds = loadConfig()?.terminalWait;
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : DEFAULTS.terminalWait;
+  } catch {
+    return DEFAULTS.terminalWait;
+  }
+}
+
+/**
+ * `hook <agent>`: run by the agent itself (or its plugin), with the event as JSON on stdin. It prints
+ * nothing and always exits 0 — Claude Code reads a hook's output as instructions, and a failing hook
+ * is something the user sees in the middle of their session.
+ */
+async function hook(agentName) {
+  const agent = AGENTS[agentName];
+  if (!agent) return hookLog(`unknown agent "${agentName}"`);
+  const payload = await readStdin();
+  const request = agent.parse(payload);
+  if (!request) return hookLog(`${agentName}: ignored ${agent.describe(payload)}`);
+  const cwd = request.cwd && fs.existsSync(request.cwd) ? request.cwd : process.cwd();
+  const session = {
+    identity: identity(process.env, cwd, { sessionId: request.sessionId }),
+    about: { agent: agentName },
+  };
+  const tag = `${agentName}: ${request.args.event} ${request.sessionId.slice(0, 8)}`;
+  try {
+    const noted = await sendPermission(request.args, session);
+    hookLog(`${tag}: ${describeHookResult(noted.data ?? {})}`);
+    // Nothing noted (say, answered already): nothing to wait for.
+    if (!request.waitFirst || noted.data?.noted === undefined) return;
+    // Give the user the chance to answer at the keyboard first. Answering in the meantime marks the
+    // request, and the ping below then finds nothing to do.
+    const seconds = terminalWait();
+    await sleep(seconds * 1000);
+    const pinged = await sendPermission({ event: "prompt", id: request.args.id, cwd: request.args.cwd }, session);
+    hookLog(`${agentName}: prompt ${request.sessionId.slice(0, 8)} after ${seconds}s: ${describeHookResult(pinged.data ?? {})}`);
+  } catch (e) {
+    hookLog(`${tag}: failed: ${e.message}`);
+  }
+}
+
+/** One line for the log: what the hook did, or why it did nothing. */
+function describeHookResult(d) {
+  if (d.skipped) return `skipped (${d.skipped})`;
+  if (d.noted !== undefined) return `noted ${d.noted}`;
+  if (d.closed !== undefined) return d.closed ? `closed ${d.about}` : `answered ${d.about}${d.error ? ` (message not updated: ${d.error})` : ""}`;
+  return `pinged about ${d.about ?? "an unknown tool"} ${JSON.stringify(d.results ?? {})}`;
+}
+
+/**
+ * `hooks status|install|uninstall [claude|opencode|codex|all]`. Without a name: every agent that is on this
+ * machine for install, and all of them for status and uninstall.
+ */
+function hooksCommand(args) {
+  const step = args._[0] ?? "status";
+  if (!["status", "install", "uninstall"].includes(step)) throw new Error(`unknown hooks command "${step}" (status, install, uninstall)`);
+  const wanted = args._[1] ?? (step === "install" ? "present" : "all");
+  const names = wanted === "all" ? Object.keys(AGENTS)
+    : wanted === "present" ? Object.keys(AGENTS).filter((n) => AGENTS[n].present())
+    : [wanted];
+  for (const n of names) if (!AGENTS[n]) throw new Error(`hooks: unknown agent "${n}" (${Object.keys(AGENTS).join(", ")}, all)`);
+  const results = names.map((n) => {
+    try {
+      if (step === "status") return AGENTS[n].status({ script: SCRIPT });
+      if (step === "install") return { ok: true, ...AGENTS[n].install({ script: SCRIPT }) };
+      return { ok: true, ...AGENTS[n].uninstall() };
+    } catch (e) {
+      return { agent: n, ok: false, error: e.message };
+    }
+  });
+  const failed = results.some((r) => r.ok === false);
+  return out({ ok: !failed, agents: results }, failed ? 1 : 0);
+}
+
+const HELP = `roger-roger - bring the user back to the conversation
+
+  install [--yes]                set everything up in the terminal: link the skill for every agent,
+                                 connect Slack, choose the sound and the voice, hooks, tray.
+                                 --yes (or no terminal) only links the skill and registers with Herdr
+  status                         config, daemon, running sessions, every valid option (JSON)
+  setup [--methods slack,sound,speech] [--sound NAME] [--voice NAME]
+        [--speech auto|same|brief] [--when auto|done-and-blocked|blocked-only|on-request]
+        [--slack-target U0123|C0123|#channel] [--slack-mention U0123]
+        [--local-fallback true|false] [--model ID] [--notes TEXT]
+        [--remind 15m|off] [--on-expire recommended|nothing] [--say-who on|off]
+        [--quiet-hours 22:00-08:00|off] [--quiet-mute speech,sound,slack] [--session-label on|off]
+        [--speech-provider gemini|openai|elevenlabs] [--speech-key-var NAME|auto]
+        [--speech-volume 0-150] [--duck on|off] [--duck-level 0-100] [--tray auto|off]
+        [--permission-pings on|off] [--terminal-wait 20s]
+  slack-setup [status|install-cli|login|create]
+                                 create the roger-roger Slack app with the Slack CLI
+
+  notify --kind done|blocked|input|milestone|error|info --message TEXT
+         [--say TEXT] [--only sound,speech] [--project NAME] [--attach FILE]
+         [--summary] [--field "Label=value"] [--actions "A|B"] [--recommend A]
+         [--reply-to TS] [--then-listen 25m]
+         [--session NAME] [--agent-model MODEL]
+  progress --message TEXT [--key NAME] [--done]
+                                 one Slack message, edited in place as the work moves on
+  control [--key NAME] [--wait DURATION]
+                                 read Pause / Stop and new messages without posting
+  inbox                          messages the user sent this session, and anything unclaimed
+  snooze [1h|off]                mute the sound and the speech for a while; Slack keeps working
+  tray status|start|stop|install an icon showing every agent, and a panel behind it
+  listen [--wait 25m]            park until the user says something; run it in the background as
+                                 the last thing you do, so a message reaches you while you're idle
+
+  ask --question TEXT --choices "A|B" [--recommend A] [--details TEXT] [--multi]
+      [--draft TEXT|--draft-file PATH] [--expires 45m] [--remind 15m]
+      [--on-expire recommended|nothing] [--other true|false] [--wait [DURATION]] [--reply-to TS]
+  wait ID [--timeout DURATION]   block until answered/expired/cancelled (exit 0 / 5, 4 = timed out,
+                                 6 = the user sent a message instead)
+  check ID                       the current state, without waiting
+  cancel ID [--reason TEXT]      withdraw a question
+  decisions [--all]              pending questions (and recent closed ones with --all)
+
+  sessions [--all]               which agents are running, and what each is called
+  sessions rename NAME NEWNAME   give a session a different colour name
+  end [NAME]                     this session (or NAME) is finished; stop routing messages to it
+
+  play [SOUND]                   preview a sound
+  say TEXT [--voice NAME] [--local | --test]
+                                 --test checks the provider and key: its voice or an error, never the local one
+  voices [--refresh]             the speech provider's voices and models (--refresh asks the provider)
+  preview-sounds [SOUND...] [--voice NAME] [--local]
+                                 announce each sound by name, then play it
+  preview-voices [VOICE...] [--all] [--text TEXT]
+
+  daemon status|start|stop       the always-on process behind all of the above
+  hooks status|install|uninstall [claude|opencode|all]
+                                 ping you when an agent asks a question in the terminal
+
+Any command takes --session NAME (what this work is called, and how the session is recognised
+between commands), --agent-model MODEL, --agent NAME, and, if the agent knows better than the
+environment does, --session-id ID and --agent-pid PID.
+`;
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  // Before anything reads the home: the first run after the rename brings ~/.attention across.
+  try {
+    migrateLegacyHome({ hooks: hooksConfig() });
+  } catch (e) {
+    process.stderr.write(`roger-roger: could not copy ~/.attention to the new home: ${e.message}\n`);
+  }
+
+  switch (command) {
+    case "install":
+      process.exitCode = await runInstall(args, { script: SCRIPT, hooks: { agents: AGENTS } });
+      return;
+    case "status": return status();
+    case "setup": return setup(args);
+    case "slack-setup": return slackSetup(args);
+    case "slack-hook":
+      process.exitCode = runHook(args._[0]);
+      return;
+    case "daemon": return daemonCommand(args);
+    case "hooks": return hooksCommand(args);
+    case "hook": return hook(args._[0]);
+
+    // `sessions rename sage plum` is the only sub-command; anything else lists them.
+    case "sessions": return args._[0] === "rename" ? run("rename", { ...args, _: args._.slice(1) }) : run("sessions", args);
+    case "end": return run("end", args);
+    case "inbox":
+    case "messages": return run("messages", args);
+
+    case "notify":
+    case "progress":
+    case "control":
+    case "listen":
+    case "snooze":
+    case "tray":
+    case "ask":
+    case "wait":
+    case "check":
+    case "cancel":
+    case "decisions":
+    case "play":
+    case "say":
+    case "voices":
+    case "preview-sounds":
+    case "preview-voices":
+      return run(command, args);
+
+    default:
+      process.stdout.write(HELP);
+      process.exitCode = command && command !== "help" ? 2 : 0;
+  }
+}
+
+main()
+  .catch((e) => out({ ok: false, error: e.message }, typeof e.code === "number" ? e.code : 1))
+  .finally(() => {
+    closeAudio();
+    // Normally the process exits on its own. If idle sockets hold it open, exit anyway after a
+    // moment (an immediate process.exit can trip a libuv assertion on Windows).
+    setTimeout(() => process.exit(), 3000).unref();
+  });

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

@@ -0,0 +1,86 @@
+// Where an incoming Slack message goes. Pure functions over a snapshot of the world, so the rules
+// can be read and tested without Slack, sockets or processes.
+//
+// In order:
+//   1. a reply in a thread  → whoever owns that thread (a progress message, a question, or a message
+//                             that was routed to a session earlier: threads remember)
+//   2. addressed by name    → "sage, rerun it", "hey sage rerun it", "sage: rerun it"
+//   3. one live session     → that one; there is nothing to be ambiguous about
+//   4. one is listening     → that one; the others are only technically running
+//   5. several live         → ask the user which, with a button per session
+//   6. none live            → the inbox, for the next agent that checks
+
+/** Openers people put in front of a name. Matched only when a real nickname follows. */
+const OPENERS = new Set(["hey", "hi", "hello", "ok", "okay", "yo", "oi", "psst", "to", "for", "re", "attn"]);
+
+const ADDRESS = /^[@!]?([a-z][a-z0-9-]{1,15})(\s*[,:;>–—-]+\s*|\s+|$)([\s\S]*)$/i;
+
+/**
+ * Pull a nickname off the front of a message: `sage, do X` / `sage: do X` / `hey sage do X` /
+ * `@sage do X` / `sage` on its own. Returns `{ nickname, text }`, or null when the message doesn't
+ * start with a name we know. Only known nicknames match, so "note: remember to..." is just a message.
+ */
+export function parseAddress(text, nicknames = []) {
+  const known = new Set(nicknames.map((n) => String(n).toLowerCase()));
+  let rest = String(text ?? "").trim();
+  for (let step = 0; step < 2 && rest; step++) {
+    const m = ADDRESS.exec(rest);
+    if (!m) return null;
+    const word = m[1].toLowerCase();
+    if (known.has(word)) {
+      const body = m[3].trim();
+      // "sage" on its own is still for sage: keep the original text so the agent sees what was said.
+      return { nickname: word, text: body || String(text).trim() };
+    }
+    if (step === 0 && OPENERS.has(word)) {
+      rest = m[3];
+      continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Decide where a message belongs.
+ *
+ * `progress` are the active progress messages, `pending` the open questions, `sessions` the live
+ * agent sessions, and `threads` maps a Slack thread_ts to the session that owns it.
+ *
+ * Returns one of:
+ *   { kind: "progress", key, session }   a note for that work
+ *   { kind: "decision", id, session }    the answer to that question
+ *   { kind: "session", id, text, via }   a message for one agent (via "listening" was a guess)
+ *   { kind: "ask", candidates }          several agents are live: let the user pick
+ *   { kind: "inbox" }                    nobody is running; keep it for the next agent
+ */
+export function routeMessage(message, { progress = [], pending = [], sessions = [], threads = {} } = {}) {
+  const text = String(message?.text ?? "");
+  const thread = message.thread_ts && message.thread_ts !== message.ts ? message.thread_ts : null;
+
+  if (thread) {
+    const p = progress.find((s) => s.ts === thread);
+    if (p) return { kind: "progress", key: p.key, session: p.session ?? null };
+    const d = pending.find((x) => x.ts === thread);
+    if (d) return { kind: "decision", id: d.id, session: d.session ?? null };
+    // A thread that was routed to a session before keeps going there, as long as it is still live.
+    const owner = threads[thread];
+    if (owner && sessions.some((s) => s.id === owner)) return { kind: "session", id: owner, text, via: "thread" };
+    return { kind: "inbox" };
+  }
+
+  const addressed = parseAddress(text, sessions.map((s) => s.nickname));
+  if (addressed) {
+    const target = sessions.find((s) => s.nickname === addressed.nickname);
+    if (target) return { kind: "session", id: target.id, text: addressed.text, via: "name" };
+  }
+
+  if (sessions.length === 1) return { kind: "session", id: sessions[0].id, text, via: "only" };
+  // "Live" only means the agent's process is up; most of those are sitting idle. If exactly one is
+  // parked and waiting to be spoken to, it is the obvious recipient — asking is busywork. The guess
+  // is said out loud in Slack, with the others a tap away, so getting it wrong costs one tap.
+  const listening = sessions.filter((s) => s.state === "listening");
+  if (listening.length === 1) return { kind: "session", id: listening[0].id, text, via: "listening" };
+  if (sessions.length > 1) return { kind: "ask", candidates: sessions.map((s) => s.id), text };
+  return { kind: "inbox" };
+}