allaboard 0.0.0-stage → 0.5.0

package/dist/cli.js

@@ -0,0 +1,326 @@
+/**
+ * The command line of `allaboard`. With no argument the command runs the daemon, which is what the
+ * service starts; the other forms answer and end without reading `.env` or taking the
+ * single-instance lock. `--instance <name>`, or `ALLABOARD_INSTANCE` when the flag is absent, picks
+ * which of the machine's daemons a command is about (`core/instance.ts`); this file is the only
+ * reader of the variable.
+ */
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { configDirOf, DEFAULT_INSTANCE, INSTANCE_VARIABLE, parseInstanceName, } from "./core/instance.js";
+import { UpdateUnderWay, updateLock } from "./core/lock.js";
+import { installVersion, isNewer, latestVersion, updatableCopy, } from "./host/npm.js";
+import { programOf } from "./host/program.js";
+import { runAsync, runCommand } from "./host/run.js";
+import { Launchd } from "./host/service/launchd.js";
+import { loadedOn } from "./host/service/listing.js";
+import { SERVICE_ACTIONS } from "./host/service/seam.js";
+import { changelogOf, installedVersion } from "./version.js";
+export const USAGE = [
+    "usage: allaboard [--instance <name>]                    run the daemon",
+    `       allaboard service <${SERVICE_ACTIONS.join("|")}> [--instance <name>]`,
+    "       allaboard update [--check] [--yes]",
+    "       allaboard --version | --help",
+    "",
+    `--instance picks one of the machine's daemons; ${INSTANCE_VARIABLE} does the same when the flag`,
+    "is absent. `service list` shows every instance and takes no --instance.",
+    "`update` installs the latest version of the copy that `npm install -g` replaces and restarts",
+    "the services that run it, asking first unless --yes; --check only prints the versions.",
+].join("\n");
+function isAction(text) {
+    return SERVICE_ACTIONS.includes(text);
+}
+const invalid = (reason) => ({ kind: "invalid", reason });
+/** The arguments without `--instance <name>`, and the name when it was given. */
+function takeInstanceFlag(args) {
+    const rest = [];
+    let flag;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument !== "--instance") {
+            rest.push(argument);
+            continue;
+        }
+        if (flag !== undefined)
+            return invalid("--instance is given twice");
+        const value = args[index + 1];
+        if (value === undefined)
+            return invalid("--instance needs a name");
+        flag = value;
+        index += 1;
+    }
+    return { rest, flag };
+}
+/** The instance the flag names, else the variable, else the default; the refusal says which. */
+function instanceOf(flag, env) {
+    const variable = env[INSTANCE_VARIABLE];
+    const named = flag !== undefined
+        ? { source: "--instance", text: flag }
+        : variable !== undefined && variable !== ""
+            ? { source: INSTANCE_VARIABLE, text: variable }
+            : null;
+    if (named === null)
+        return DEFAULT_INSTANCE;
+    const parsed = parseInstanceName(named.text);
+    return "refusal" in parsed
+        ? invalid(`${named.source}: ${parsed.refusal}`)
+        : { name: parsed.name };
+}
+/** `update`'s own flags: `--check` and `--yes`, once each and not together. */
+function parseUpdate(args, flag) {
+    if (flag !== undefined) {
+        return invalid("update takes no instance: it updates the copy that all of them run");
+    }
+    const given = { "--check": false, "--yes": false };
+    for (const argument of args) {
+        if (argument === undefined)
+            continue;
+        if (argument !== "--check" && argument !== "--yes") {
+            return invalid(`unknown argument ${JSON.stringify(argument)}`);
+        }
+        if (given[argument])
+            return invalid(`${argument} is given twice`);
+        given[argument] = true;
+    }
+    if (given["--check"] && given["--yes"]) {
+        return invalid("--check installs nothing, so --yes has no meaning with it");
+    }
+    return { kind: "update", check: given["--check"], yes: given["--yes"] };
+}
+/** What the arguments after the command ask for; anything else is `invalid`, with the reason. */
+export function parseArguments(args, env = {}) {
+    const taken = takeInstanceFlag(args);
+    if ("kind" in taken)
+        return taken;
+    const { rest: positional, flag } = taken;
+    const [first, second, ...rest] = positional;
+    if (first === "update")
+        return parseUpdate([second, ...rest], flag);
+    if (first === undefined) {
+        const instance = instanceOf(flag, env);
+        return "kind" in instance ? instance : { kind: "run", instance };
+    }
+    if (first === "service") {
+        if (!isAction(second)) {
+            return invalid(`service needs one of: ${SERVICE_ACTIONS.join(", ")}`);
+        }
+        if (rest.length > 0)
+            return invalid(`unknown argument ${JSON.stringify(rest[0])}`);
+        if (second === "list") {
+            return flag === undefined
+                ? { kind: "service", action: second, instance: DEFAULT_INSTANCE }
+                : invalid("service list takes no instance: it lists them all");
+        }
+        const instance = instanceOf(flag, env);
+        return "kind" in instance ? instance : { kind: "service", action: second, instance };
+    }
+    if (second !== undefined)
+        return invalid(`unknown argument ${JSON.stringify(second)}`);
+    if (first === "--version" || first === "--help") {
+        if (flag !== undefined)
+            return invalid(`${first} takes no instance`);
+        return { kind: first === "--version" ? "version" : "help" };
+    }
+    return invalid(`unknown argument ${JSON.stringify(first)}`);
+}
+export const machineHost = {
+    service: (instance) => process.platform === "darwin"
+        ? new Launchd({
+            home: homedir(),
+            uid: process.getuid?.() ?? 0,
+            instance: instance.name,
+            configDir: configDirOf(instance, homedir()),
+            run: runCommand,
+        })
+        : null,
+    program: () => programOf(process.argv[1] ?? "", process.env.PATH ?? "", process.execPath),
+};
+/**
+ * Answers an invocation that does not run the daemon, and returns the exit status: 0, 2 for
+ * arguments it does not know (with the usage on stderr), or the service action's own status.
+ */
+export function answer(invocation, output, host = machineHost) {
+    switch (invocation.kind) {
+        case "version":
+            output.out(`${installedVersion()}\n`);
+            return 0;
+        case "help":
+            output.out(`${USAGE}\n`);
+            return 0;
+        case "invalid":
+            output.err(`allaboard: ${invocation.reason}\n${USAGE}\n`);
+            return 2;
+        case "service": {
+            const manager = host.service(invocation.instance);
+            if (manager === null) {
+                output.err("allaboard service: allaboard runs as a service on macOS only, for now.\n");
+                return 1;
+            }
+            const report = invocation.action === "install"
+                ? manager.install(host.program())
+                : manager[invocation.action]();
+            for (const line of report.out)
+                output.out(`${line}\n`);
+            for (const line of report.err)
+                output.err(`${line}\n`);
+            return report.code;
+        }
+    }
+}
+export const machineUpdateHost = {
+    ...machineHost,
+    run: runAsync,
+    home: homedir(),
+    version: installedVersion,
+    // A getter: reading `process.stdin` at import would open it in the daemon too.
+    get interactive() {
+        return process.stdin.isTTY === true && process.stdout.isTTY === true;
+    },
+    ask: async (question) => {
+        const lines = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return await lines.question(question);
+        }
+        finally {
+            lines.close();
+        }
+    },
+};
+const failure = (output, sentence) => {
+    output.err(`allaboard update: ${sentence}\n`);
+    return 1;
+};
+/** Why the latest version is unknown, from what npm failed with. */
+function unknownLatest(why) {
+    const reason = why.kind === "network"
+        ? "npm could not reach the registry"
+        : why.kind === "permission"
+            ? "npm may not read what it needs"
+            : why.status === null
+                ? "npm could not be run"
+                : `npm ended with status ${why.status}`;
+    return `the latest version is unknown: ${reason}.`;
+}
+/** Why the copy is not one `update` replaces. */
+function notUpdated(refusal) {
+    switch (refusal.kind) {
+        case "not-global":
+            return `this copy is not updated by this command: it is not the copy \`npm install -g\` replaces (${refusal.folder}).`;
+        case "link":
+            return "this copy is not updated by this command: it is a link, not an install.";
+        case "unpublished":
+            return `this copy is not updated by this command: its version ${refusal.version} is not published on npm.`;
+        case "npm":
+            return unknownLatest(refusal.failure);
+    }
+}
+/** The sentence for an install that did not leave the version asked, or null when it did. */
+function installFailed(result, running, latest) {
+    switch (result.kind) {
+        case "installed":
+            return null;
+        case "mismatch":
+            return result.found === null
+                ? `npm ended, but the copy's version cannot be read, so nothing was restarted; the services keep running ${running}. \`npm install -g allaboard@${running}\` repairs it.`
+                : `npm ended, but the copy now holds ${result.found} instead of ${latest}, so nothing was restarted; the services keep running ${running}. \`npm install -g allaboard@${running}\` puts back the version that runs.`;
+        case "failed": {
+            const why = result.failure;
+            const reason = why.kind === "network"
+                ? "npm could not reach the registry"
+                : why.kind === "permission"
+                    ? why.path === null
+                        ? "npm may not write where it installs"
+                        : `npm may not write to ${why.path}`
+                    : why.status === null
+                        ? "npm could not be run"
+                        : `npm ended with status ${why.status}`;
+            return `the update failed: ${reason}. Nothing was restarted.`;
+        }
+    }
+}
+const instanceName = (instance) => instance ?? "the default instance";
+/**
+ * Answers `allaboard update`: `--check` prints the installed and the latest version; otherwise
+ * checks that this copy is the one `npm install -g` replaces, asks (unless `--yes`), takes the
+ * machine's update lock, installs the latest version, checks the copy now holds it, and sends the
+ * restart to every service running this copy. Returns the exit status: 0 when it updated or had
+ * nothing to do, 1 when it failed.
+ */
+export async function answerUpdate(invocation, output, host = machineUpdateHost) {
+    // Before anything is awaited: the install replaces the `package.json` this reads.
+    const running = host.version();
+    if (invocation.check) {
+        const latest = await latestVersion(host.run);
+        if ("failure" in latest)
+            return failure(output, unknownLatest(latest.failure));
+        output.out(`allaboard ${running} · latest ${latest.version}\n`);
+        return 0;
+    }
+    const updatable = await updatableCopy(host.run, host.program().main, running);
+    if ("refusal" in updatable)
+        return failure(output, notUpdated(updatable.refusal));
+    const latest = await latestVersion(host.run);
+    if ("failure" in latest)
+        return failure(output, unknownLatest(latest.failure));
+    if (!isNewer(latest.version, running)) {
+        output.out(`allaboard ${running} is already the latest version.\n`);
+        return 0;
+    }
+    const listing = host.service(DEFAULT_INSTANCE)?.instances() ?? { rows: [], refused: [] };
+    if ("failure" in listing)
+        return failure(output, listing.failure);
+    const restarts = loadedOn(listing.rows, updatable.copy).filter((row) => row.pid !== null);
+    output.out(`Update allaboard ${running} → ${latest.version} · What changed: ${changelogOf(latest.version)}\n`);
+    output.out(restarts.length === 0
+        ? "No service runs this copy: it is installed and nothing restarts.\n"
+        : `It restarts: ${restarts.map((row) => instanceName(row.instance)).join(", ")}. Running turns finish first.\n`);
+    if (!invocation.yes) {
+        if (!host.interactive) {
+            return failure(output, "there is no terminal to ask on; --yes updates without asking.");
+        }
+        if (!/^y(es)?$/i.test((await host.ask("Update? [y/N] ")).trim())) {
+            output.out("Not updated.\n");
+            return 0;
+        }
+    }
+    let lock;
+    try {
+        lock = await updateLock(host.home);
+    }
+    catch (error) {
+        if (error instanceof UpdateUnderWay) {
+            return failure(output, "an update of allaboard is already under way on this machine.");
+        }
+        throw error;
+    }
+    try {
+        output.out(`Installing allaboard ${latest.version}…\n`);
+        const installed = await installVersion(host.run, updatable.copy, latest.version);
+        const refusal = installFailed(installed, running, latest.version);
+        if (refusal !== null)
+            return failure(output, refusal);
+    }
+    finally {
+        await lock.release();
+    }
+    const sent = [];
+    let code = 0;
+    for (const row of restarts) {
+        const report = host.service({ name: row.instance })?.restart();
+        if (report === undefined || report.code !== 0) {
+            code = 1;
+            for (const line of report?.err ?? [])
+                output.err(`${line}\n`);
+        }
+        else {
+            sent.push(instanceName(row.instance));
+        }
+    }
+    const named = sent.length < 2 ? sent.join("") : `${sent.slice(0, -1).join(", ")} and ${sent.at(-1)}`;
+    output.out(restarts.length === 0
+        ? `Installed allaboard ${latest.version}. No service runs this copy, so nothing was restarted.\n`
+        : sent.length === 0
+            ? `Installed allaboard ${latest.version}.\n`
+            : `Installed allaboard ${latest.version}. Sent the restart to ${named}: running turns finish first.\n`);
+    return code;
+}

package/dist/clock.js

@@ -0,0 +1,21 @@
+/**
+ * The time the daemon waits by: every pause (a reply's debounce and its stream's 280 seconds,
+ * the limiter's pacing, a status refresh, an idle close) goes through a `Clock`, so a test
+ * crosses them without waiting. Any layer may import it.
+ */
+import { setTimeout as pause } from "node:timers/promises";
+async function sleep(seconds, signal) {
+    try {
+        await pause(seconds * 1000, undefined, { signal });
+    }
+    catch (error) {
+        // `node:timers/promises` rejects with its own AbortError, the reason as its cause.
+        if (signal?.aborted)
+            throw signal.reason;
+        throw error;
+    }
+}
+/** Wall-clock seconds, as a Slack ts counts them. */
+export const systemClock = { sleep, time: () => Date.now() / 1000 };
+/** Seconds that only move forward: what a rate is paced by. */
+export const monotonicClock = { sleep, time: () => performance.now() / 1000 };

package/dist/core/cleanup.js

@@ -0,0 +1,145 @@
+import { getLogger } from "../log.js";
+import { errorName } from "../values.js";
+export const logger = getLogger("allaboard.core.cleanup");
+export const CLEAN_EVERY_SECONDS = 6 * 60 * 60;
+/**
+ * Remove from `state` each bound channel the chat answers `gone` about, with its threads. Returns
+ * the ids it forgot and those it `found` (answered `there`): the channels whose threads may be
+ * asked about. A channel with a live session is left for the next pass. When the chat finds
+ * none of the bound channels (a channel it gave no answer about is not one it found), nothing is
+ * removed: that is what the token of another workspace, or an app removed from every channel,
+ * looks like, and forgetting every binding would be the wrong repair. `chat` is the chat's
+ * name, for the log lines.
+ */
+export async function forgetGoneChannels(lookup, state, live, chat, log = logger) {
+    const bound = state.channels();
+    const gone = [];
+    const found = [];
+    for (const channelId of bound) {
+        let answer;
+        try {
+            answer = await lookup(channelId);
+        }
+        catch (error) {
+            log.warning(`could not read channel ${channelId}: ${errorName(error)}`);
+            continue;
+        }
+        if (answer === "there") {
+            found.push(channelId);
+        }
+        else if (answer === "gone") {
+            gone.push(channelId);
+        }
+        else {
+            log.warning(`could not read channel ${channelId}: ${answer}`);
+        }
+    }
+    if (gone.length === 0)
+        return { forgotten: [], found };
+    if (found.length === 0) {
+        log.warning(`${chat} finds none of the ${bound.length} bound channels: nothing is forgotten (check the ` +
+            "workspace of the bot token, and that the bot is still in its channels)");
+        return { forgotten: [], found };
+    }
+    const busy = new Set([...live()].map((ref) => ref.channel));
+    const forgotten = [];
+    for (const channelId of gone) {
+        const record = state.channel(channelId);
+        if (record === null || busy.has(channelId))
+            continue;
+        state.removeChannel(channelId);
+        forgotten.push(channelId);
+        log.info(`forgot channel ${channelId}: ${chat} no longer has it (${record.threads.size} thread(s))`);
+    }
+    return { forgotten, found };
+}
+/**
+ * Remove from `state` each thread, among those of the `channels` the chat found, whose first
+ * message the chat answers `gone` about, and return them. A thread with a live session (read
+ * when it is removed, after the chat was asked) is left for the next pass, as are the threads of
+ * a channel after the first one the chat gave no answer about, and every thread not yet asked
+ * about once `stopping` says a stop has begun.
+ */
+export async function forgetGoneThreads(lookup, state, channels, live, chat, log = logger, stopping = () => false) {
+    const asked = new Set(channels);
+    const gone = [];
+    for (const [channel, thread] of state.threads()) {
+        // One call to the chat per thread: a stop that begins meanwhile waits for one, not for all.
+        if (stopping())
+            break;
+        if (!asked.has(channel))
+            continue;
+        const ref = { channel, thread };
+        let answer;
+        try {
+            answer = await lookup(ref);
+        }
+        catch (error) {
+            answer = errorName(error);
+        }
+        if (answer === "gone") {
+            gone.push(ref);
+        }
+        else if (answer !== "there") {
+            // What kept the chat from answering (a rate limit, a history it may not read) holds for
+            // the channel's other threads too: they wait for the next pass, with one line here.
+            log.warning(`could not read thread ${thread} of ${channel}: ${answer}`);
+            asked.delete(channel);
+        }
+    }
+    const busy = new Set([...live()].map((ref) => `${ref.channel}\u0000${ref.thread}`));
+    const forgotten = [];
+    for (const ref of gone) {
+        if (busy.has(`${ref.channel}\u0000${ref.thread}`) ||
+            state.thread(ref.channel, ref.thread) === null) {
+            continue;
+        }
+        state.removeThread(ref.channel, ref.thread);
+        forgotten.push(ref);
+        log.info(`forgot thread ${ref.thread} of ${ref.channel}: ${chat} no longer has its first message`);
+    }
+    return forgotten;
+}
+/**
+ * One pass: forget the channels that are gone, then the threads of the others whose first message
+ * is gone, then prune the threads whose session is (`alive`
+ * gives a folder's session ids, or null when it cannot tell). Never throws: a pass that fails is
+ * logged and the next one tries again.
+ */
+export async function clean(lookup, state, options) {
+    const { alive, live } = options;
+    const now = options.now ?? (() => Date.now() / 1000);
+    const log = options.logger ?? logger;
+    let found = [];
+    try {
+        found = (await forgetGoneChannels(lookup, state, live, options.chat, log)).found;
+    }
+    catch (error) {
+        log.warning(`could not check the bound channels: ${errorName(error)}`);
+    }
+    try {
+        await forgetGoneThreads(options.threadLookup, state, found, live, options.chat, log, options.stopping);
+    }
+    catch (error) {
+        log.warning(`could not check the threads: ${errorName(error)}`);
+    }
+    try {
+        const folders = new Set(state
+            .threads()
+            .filter(([, , thread]) => thread.sessionId !== null)
+            .map(([, , thread]) => thread.directory));
+        // Reading a folder's sessions is file work that may wait: the state is touched only once all
+        // of it is read, and a folder opened meanwhile has no entry here, so its threads are kept.
+        const known = new Map();
+        for (const folder of folders) {
+            const sessions = await alive(folder);
+            known.set(folder, sessions === null ? null : [...sessions]);
+        }
+        const removed = state.prune((directory) => known.get(directory) ?? null, options.openedAt, now(), live());
+        if (removed > 0)
+            log.info(`pruned ${removed} stale thread(s) from state.json`);
+    }
+    catch (error) {
+        log.warning(`could not prune stale threads: ${errorName(error)}`);
+    }
+}

package/dist/core/commands.js

@@ -0,0 +1,172 @@
+import { compareCodePoints, PY_SPACE, strip } from "../text.js";
+import * as texts from "./texts.js";
+/** The word each of the daemon's own commands is typed as; a new kind of `Word` fails to compile here. */
+export const WORD = {
+    help: "help",
+    guide: "guide",
+    bind: "bind",
+    bypass: "bypass",
+    status: "status",
+    stop: "stop",
+    resume: "resume",
+    open: "open",
+    allaboard: "allaboard",
+};
+export const DESCRIPTION_LIMIT = 100;
+// Python's whitespace, which `strip` and `split` follow, is not JavaScript's `\s` (`text.ts`).
+const TRAILING = new RegExp(`[${PY_SPACE}]+$`);
+const STARTS_WITH_SPACE = new RegExp(`^[${PY_SPACE}]`);
+const WORD_AND_REST = new RegExp(`^([^${PY_SPACE}]+)(?:[${PY_SPACE}]+([\\s\\S]*))?$`);
+const RUNS_OF_SPACE = new RegExp(`[${PY_SPACE}]+`);
+/**
+ * Map a `!word` message to the daemon's own command or a Claude Code passthrough; null when the
+ * message is not a command at all.
+ */
+export function parseBang(text) {
+    const stripped = strip(text);
+    if (!stripped.startsWith("!"))
+        return null;
+    const body = stripped.slice(1);
+    if (body === "" || STARTS_WITH_SPACE.test(body))
+        return null;
+    // The word ends at any whitespace: a line break after it (a code block that follows the
+    // word, a second line) separates it from its arguments as a space does.
+    const split = WORD_AND_REST.exec(body);
+    const word = split?.[1] ?? "";
+    const rest = strip(split?.[2] ?? "");
+    switch (word.toLowerCase()) {
+        case "help":
+            return { kind: "help", query: rest.toLowerCase() };
+        case "guide":
+            if (rest === "")
+                return { kind: "guide" };
+            break;
+        case "bind":
+            return { kind: "bind", path: rest }; // alone, it lists the folders a session can start in
+        case "bypass":
+            switch (rest.toLowerCase()) {
+                case "on":
+                    return { kind: "bypass", on: true };
+                case "off":
+                    return { kind: "bypass", on: false };
+                default:
+                    return { kind: "invalid" };
+            }
+        case "status":
+            if (rest === "")
+                return { kind: "status" };
+            break;
+        case "stop":
+            if (rest === "")
+                return { kind: "stop" };
+            break;
+        case "resume":
+            return { kind: "resume", target: rest };
+        case "open":
+            return { kind: "open", target: rest };
+        case "allaboard":
+            switch (rest.toLowerCase()) {
+                case "":
+                    return { kind: "allaboard", action: "show" };
+                case "update":
+                    return { kind: "allaboard", action: "update" };
+                case "restart":
+                    return { kind: "allaboard", action: "restart" };
+                default:
+                    return { kind: "invalid" };
+            }
+    }
+    return { kind: "passthrough", text: strip(`${word} ${rest}`) };
+}
+/**
+ * The daemon's words, then every command the session offers now (null: not bound yet) except
+ * those its thread refuses (`refusedInThread`), keeping only the lines whose name or description
+ * contains `query`, ignoring case. With no query, the rule that tells a command from a text comes
+ * first. `escapeMarkdown` is the chat provider's escape for a markdown block; `names` fill the
+ * texts that name the agent and the chat. An agent with no commands of its own
+ * (`agentCommands` false) has none listed, and no line about where they are listed. An agent that
+ * keeps no record of trust (`folderTrust` false) has a `!bind` line that speaks of none.
+ */
+export function helpText(commands, query, escapeMarkdown, names, agentCommands = true, unserved = new Set(), folderTrust = true) {
+    const keep = (line) => line.toLowerCase().includes(query.toLowerCase());
+    // A word the agent or the chat cannot serve is not offered: its line is left out.
+    const served = (line) => ![...unserved].some((word) => line.startsWith(`\`!${word} `) || line.startsWith(`\`!${word}\``));
+    const own = (folderTrust ? texts.HELP_WORDS : texts.HELP_WORDS_ANY)
+        .map((word) => texts.named(word, names))
+        .filter(served)
+        .filter(keep);
+    const refused = refusedInThread(commands, names.newSession, agentCommands);
+    const offered = (commands ?? []).filter((c) => !refused.has(c.name.toLowerCase()));
+    const session = offered
+        .toSorted((a, b) => compareCodePoints(a.name, b.name))
+        .map((command) => commandParts(command, escapeMarkdown))
+        .filter(([usage, description]) => keep(`${usage} ${description}`))
+        .map(([usage, description]) => `${usage} ${escapeMarkdown(description)}`.replace(TRAILING, ""));
+    // The rule heads the whole list; a search shows its matches alone.
+    const lines = [texts.HELP_OWN, ...(query ? [] : [texts.HELP_RULE]), ...own];
+    if (agentCommands && commands === null) {
+        lines.push(texts.named(texts.HELP_UNBOUND, names));
+    }
+    else if (agentCommands) {
+        lines.push(texts.named(texts.HELP_AGENT, names), ...session);
+    }
+    if (query && own.length === 0 && session.length === 0) {
+        lines.push(texts.fill(texts.HELP_NO_MATCH, { query }));
+    }
+    return lines.join("\n");
+}
+/**
+ * The answer to a command that is only ever run on the host (the agent's `login` and `logout`
+ * names, in `names`), or null for any other, for a name the agent does not have, and for every one
+ * when the agent has no commands of its own (`agentCommands` false): the caller sends that answer
+ * and nothing to the agent. These commands act on the host's own login, which the daemon and
+ * every session run on.
+ */
+export function hostOnly(command, names, agentCommands = true) {
+    if (!agentCommands)
+        return null; // no command is the agent's, so none is run on the host
+    const word = command.text.split(" ", 1)[0].toLowerCase();
+    if (names.login !== null && word === names.login.toLowerCase()) {
+        return texts.named(texts.LOGIN_ON_HOST, names);
+    }
+    if (names.logout !== null && word === names.logout.toLowerCase()) {
+        return texts.named(texts.LOGOUT_ON_HOST, names);
+    }
+    return null;
+}
+/**
+ * The command names a thread refuses, lowercase: the agent's `newSession` names (one thread is
+ * one session, and a thread is also the only place a session's commands are listed; they are
+ * known before a session rebuilt after a restart connects), with every alias the session's own
+ * list (`commands`, null or empty before it connects) gives one of them. None for an agent with
+ * no commands of its own (`agentCommands` false).
+ */
+export function refusedInThread(commands, newSession, agentCommands = true) {
+    if (!agentCommands)
+        return new Set(); // an agent with no commands of its own has none to refuse
+    const own = new Set(newSession.map((name) => name.toLowerCase()));
+    const aliases = (commands ?? [])
+        .filter((command) => own.has(command.name.toLowerCase()))
+        .flatMap((command) => command.aliases.map((alias) => alias.toLowerCase()));
+    return new Set([...own, ...aliases]);
+}
+/**
+ * `!name hint` and the description as written, cut to one short line; not escaped. The
+ * description is third-party text, and a cut can fall inside its own code span: the caller
+ * escapes it before showing it (`helpText`).
+ */
+export function commandParts(command, escapeMarkdown) {
+    const plain = `!${command.name} ${command.argumentHint}`.replace(TRAILING, "");
+    // A code span cannot hold a backtick: such a usage is plain text, escaped.
+    const usage = plain.includes("`") ? escapeMarkdown(plain) : `\`${plain}\``;
+    let description = command.description
+        .split(RUNS_OF_SPACE)
+        .filter((word) => word !== "")
+        .join(" ");
+    // The cut counts code points: a unit-wise cut could split an emoji.
+    const points = Array.from(description);
+    if (points.length > DESCRIPTION_LIMIT) {
+        description = `${points.slice(0, DESCRIPTION_LIMIT - 1).join("")}…`;
+    }
+    return [usage, description];
+}