@codyswann/lisa 4.80.1 → 4.81.0

package/plugins/src/base/skills/lisa-session-manager/scripts/telegram-route.mjs

@@ -0,0 +1,210 @@
+/**
+ * Decide which worker an inbound Telegram message is for, or whether it is an
+ * operator command.
+ *
+ * Several workers can be waiting on the operator at once, and an answer
+ * delivered to the wrong one is acted on with permissions skipped. So routing
+ * only ever uses an explicit signal, in this order:
+ *
+ * 1. a leading `[REF]`, `REF:` or `REF ` naming a ledger ref or its worker
+ *    token (case-insensitive, exact token — `TEAM-1` never matches `TEAM-12`).
+ *    A GitHub ref `owner/repo#12` also answers to `repo#12` and `#12`, which
+ *    is what a phone user types; a short form that names more than one ledger
+ *    item names none;
+ * 2. a Telegram reply to the message that carried a pending question. The
+ *    Telegram channel plugin (0.0.7) does not pass the replied-to message id
+ *    on, so the manager can only supply `--reply-to` from a plugin that does;
+ *    the leading ref is what operators are told to use;
+ * 3. an operator command (`status`, `pause`, `resume`, `cap N`, `stop REF`).
+ *    A recognised command with bad arguments (`cap 40`, `stop A B`) is
+ *    `invalid-command`, never an answer;
+ * 4. the only pending question, when exactly one exists.
+ *
+ * Anything else is `ambiguous`, and the manager asks which item was meant.
+ * Commands sit below an explicit ref or reply, so "pause" sent as a reply to a
+ * question is an answer, but above the single-pending fallback, so a bare
+ * "pause" is never swallowed as an answer.
+ *
+ * The message text is untrusted data. It is sliced and returned, never
+ * evaluated, interpolated into a shell, or used as a pattern.
+ * @module telegram-route
+ */
+
+import { parseWorkerName, sanitizeRefToken } from "./workers.mjs";
+
+/** Upper bound for `cap N`, matching the ledger's `control.maxWorkers`. */
+const MAX_CAP = 32;
+
+/** Commands that take no argument. */
+const BARE_COMMANDS = new Set(["status", "pause", "resume"]);
+
+/**
+ * Leading-ref forms, tried in order. Each captures `[ref, body]`.
+ * @type {RegExp[]}
+ */
+const PREFIX_PATTERNS = [
+  /^\[([^\]\s]+)\]\s*([\s\S]*)$/,
+  /^([^\s:[\]]+)\s*:\s*([\s\S]*)$/,
+  /^(\S+)\s+([\s\S]*)$/,
+];
+
+/**
+ * Every token that names a ledger item: the ref, its name-safe token, and the
+ * token in its worker's name.
+ * @param {string} ref - Ledger key
+ * @param {{worker?: string|null}} entry - Ledger item
+ * @returns {string[]} Lower-cased tokens
+ */
+function namesFor(ref, entry) {
+  const safeToken = (() => {
+    try {
+      return sanitizeRefToken(ref);
+    } catch {
+      return null;
+    }
+  })();
+  return [
+    ref,
+    safeToken,
+    parseWorkerName(entry?.worker)?.token,
+    ...shortForms(ref),
+  ]
+    .filter(name => typeof name === "string")
+    .map(name => name.toLowerCase());
+}
+
+/**
+ * The phone-friendly short forms of a GitHub ref: `owner/repo#12` gives
+ * `repo#12` and `#12`. Jira and Linear keys have none.
+ * @param {string} ref - Ledger key
+ * @returns {string[]} Short forms, possibly empty
+ */
+function shortForms(ref) {
+  const github = /^[^/\s]+\/([^#\s]+)(#\d+)$/.exec(ref);
+  return github ? [`${github[1]}${github[2]}`, github[2]] : [];
+}
+
+/**
+ * Find the ledger ref a token names. A token that names several items (a
+ * `#12` shared by two repos) names none, so it can never pick one at random.
+ * @param {Record<string, object>} items - Ledger items
+ * @param {string} token - Candidate from the message
+ * @returns {string | null} Ledger key, or null
+ */
+function matchRef(items, token) {
+  const wanted = token.toLowerCase();
+  const matches = Object.keys(items).filter(ref =>
+    namesFor(ref, items[ref]).includes(wanted)
+  );
+  return matches.length === 1 ? matches[0] : null;
+}
+
+/**
+ * Read a leading ref and the body after it.
+ * @param {Record<string, object>} items - Ledger items
+ * @param {string} text - Trimmed message
+ * @returns {{ref: string, body: string} | null} Match, or null
+ */
+function matchPrefix(items, text) {
+  return (
+    PREFIX_PATTERNS.map(pattern => pattern.exec(text))
+      .filter(match => match !== null)
+      .map(([, token, body]) => ({
+        ref: matchRef(items, token),
+        body: body.trim(),
+      }))
+      .find(({ ref, body }) => ref !== null && body !== "") ?? null
+  );
+}
+
+/**
+ * Parse an operator command.
+ * @param {string} text - Message text
+ * @returns {{kind: "command", name: "status"|"pause"|"resume"} | {kind: "command", name: "cap", value: number} | {kind: "command", name: "stop", ref: string} | {kind: "not-a-command", reason?: string}} Command, or why not
+ */
+export function parseCommand(text) {
+  const words = (typeof text === "string" ? text : "")
+    .trim()
+    .replace(/^\//, "")
+    .split(/\s+/);
+  const name = words[0].toLowerCase();
+  const args = words.slice(1);
+  if (BARE_COMMANDS.has(name) && args.length === 0)
+    return { kind: "command", name };
+  if (name === "cap") {
+    const value =
+      args.length === 1 && /^\d+$/.test(args[0]) ? Number(args[0]) : Number.NaN;
+    return value <= MAX_CAP
+      ? { kind: "command", name, value }
+      : {
+          kind: "not-a-command",
+          reason: `cap needs one whole number from 0 to ${MAX_CAP}`,
+        };
+  }
+  if (name === "stop") {
+    return args.length === 1
+      ? { kind: "command", name, ref: args[0] }
+      : { kind: "not-a-command", reason: "stop needs exactly one ref" };
+  }
+  return { kind: "not-a-command" };
+}
+
+/**
+ * Route one inbound message.
+ * @param {{text: string, replyToMessageId?: number|null, ledger: {items?: Record<string, {worker?: string|null, pendingQuestion?: {telegramMessageId?: number|null}|null}>}}} input - Message and current ledger
+ * @returns {{kind: "answer", ref: string, body: string} | ReturnType<typeof parseCommand> & {kind: "command"} | {kind: "invalid-command", reason: string} | {kind: "ambiguous", candidates: string[]}} Route
+ */
+export function routeInbound({ text, replyToMessageId, ledger }) {
+  const items = ledger?.items ?? {};
+  const message = typeof text === "string" ? text.trim() : "";
+  const pending = Object.keys(items)
+    .filter(ref => items[ref]?.pendingQuestion)
+    .sort();
+  const ambiguous = { kind: "ambiguous", candidates: pending };
+  if (message === "") return ambiguous;
+
+  const prefixed = matchPrefix(items, message);
+  if (prefixed)
+    return { kind: "answer", ref: prefixed.ref, body: prefixed.body };
+
+  const repliedTo =
+    replyToMessageId === undefined || replyToMessageId === null
+      ? undefined
+      : pending.find(
+          ref =>
+            items[ref].pendingQuestion.telegramMessageId === replyToMessageId
+        );
+  if (repliedTo) return { kind: "answer", ref: repliedTo, body: message };
+
+  const command = parseCommand(message);
+  if (command.kind === "command") {
+    return command.name === "stop"
+      ? { ...command, ref: matchRef(items, command.ref) ?? command.ref }
+      : command;
+  }
+  // A recognised command with bad arguments ("cap 40", "stop A B") is a
+  // mistyped command, not an answer. Falling through to the single-pending
+  // fallback would hand it to a worker that acts on it with permissions
+  // skipped, so the operator is told what was wrong instead.
+  if (command.reason) {
+    return { kind: "invalid-command", reason: command.reason };
+  }
+
+  return pending.length === 1
+    ? { kind: "answer", ref: pending[0], body: message }
+    : ambiguous;
+}
+
+/**
+ * Wrap an operator's answer for delivery to a worker, so the worker can tell
+ * a human answer from the manager's own messages.
+ * @param {string} owner - Display name of the person who answered
+ * @param {string} body - Answer text, passed through as data
+ * @returns {string} Message for the worker
+ */
+export function formatAnswer(owner, body) {
+  if (typeof owner !== "string" || owner.trim() === "") {
+    throw new Error("owner must be a non-empty string");
+  }
+  return `${owner.trim()}'s answer: ${body}`;
+}

package/plugins/src/base/skills/lisa-session-manager/scripts/token.mjs

@@ -0,0 +1,191 @@
+/**
+ * The Telegram bot token the manager needs: validated, stored in
+ * `<stateDir>/.env` (dir 0700, file 0600), read from the operator's terminal
+ * with echo off, and never put in argv, a return value, an error message or a
+ * log line. An existing token is replaced only on request. Split out of
+ * launch.mjs, which re-exports everything here.
+ * @module token
+ */
+import { randomUUID } from "node:crypto";
+import * as nodeFs from "node:fs";
+import path from "node:path";
+
+import { LaunchError, resolveStateDir } from "./state-dir.mjs";
+
+/** The shape of a BotFather token: `<bot id>:<secret>`. */
+const BOT_TOKEN_PATTERN = /^\d+:[A-Za-z0-9_-]{30,}$/;
+
+/** The plugin reads its token from this file in the state dir. */
+const TOKEN_FILE_NAME = ".env";
+
+/**
+ * Whether `token` looks like a BotFather bot token.
+ * @param {unknown} token - Candidate
+ * @returns {boolean} True for `<digits>:<30+ of [A-Za-z0-9_-]>`
+ */
+export function validateBotToken(token) {
+  return typeof token === "string" && BOT_TOKEN_PATTERN.test(token);
+}
+
+/**
+ * Write `<stateDir>/.env` as `TELEGRAM_BOT_TOKEN=<token>`.
+ *
+ * The dir is chmod-ed to 0700 even when it already existed, because `mkdir`'s
+ * mode only applies to dirs it creates. The file is written to a temp name
+ * created 0600 and renamed over the target, so there is never a moment when a
+ * token sits in a file with looser permissions, and a replaced file's old
+ * mode never carries over.
+ * @param {string} stateDir - Absolute state dir (already resolved)
+ * @param {string} token - Bot token; validated, never echoed
+ * @param {{ fs?: Pick<typeof nodeFs, "mkdirSync" | "chmodSync" |
+ *   "writeFileSync" | "renameSync"> }} [seams] - Injected fs
+ * @returns {{ path: string }} Where the token file is
+ */
+export function writeTokenFile(stateDir, token, seams = {}) {
+  const fs = seams.fs ?? nodeFs;
+  if (!validateBotToken(token)) {
+    throw new LaunchError(
+      "That does not look like a Telegram bot token " +
+        "(expected <digits>:<30 or more letters, digits, _ or ->). Nothing was stored."
+    );
+  }
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(stateDir, 0o700);
+  const target = path.join(stateDir, TOKEN_FILE_NAME);
+  const temp = path.join(stateDir, `${TOKEN_FILE_NAME}.${randomUUID()}.tmp`);
+  fs.writeFileSync(temp, `TELEGRAM_BOT_TOKEN=${token}\n`, {
+    mode: 0o600,
+    flag: "wx",
+  });
+  fs.chmodSync(temp, 0o600);
+  fs.renameSync(temp, target);
+  return { path: target };
+}
+
+/**
+ * Load `promptSecret`/`canPrompt` from the secrets-access skill, by path
+ * relative to this file, the same way other skills reach it. Lazy so the
+ * argv builders never pay for it.
+ * @returns {Promise<{ promptSecret: Function, canPrompt: Function }>} Module
+ */
+export function loadPromptSecret() {
+  return import(
+    new URL(
+      "../../lisa-secrets-access/scripts/prompt-secret.mjs",
+      import.meta.url
+    ).href
+  );
+}
+
+/**
+ * Quote one word for a POSIX shell.
+ * @param {string} word - Word to quote
+ * @returns {string} Single-quoted word
+ */
+function shellQuote(word) {
+  const escaped = String(word).replaceAll("'", String.raw`'\''`);
+  return `'${escaped}'`;
+}
+
+/**
+ * The command an operator pastes into their own terminal to store the token,
+ * for when the caller (an agent's Bash) has no TTY to prompt on.
+ * @param {{ scriptsDir: string, projectRoot: string, replace?: boolean }}
+ *   input - Script and project locations, and whether to carry `--replace`
+ * @returns {string} One shell line
+ */
+export function buildStoreTokenCommand({ scriptsDir, projectRoot, replace }) {
+  const script = shellQuote(path.join(scriptsDir, "session-manager.mjs"));
+  const flag = replace ? " --replace" : "";
+  return `node ${script} store-token${flag} --project-root ${shellQuote(projectRoot)}`;
+}
+
+/**
+ * Prompt for the bot token on the operator's terminal and store it.
+ *
+ * An existing token is never overwritten without `replace`: a second project
+ * that shares this state dir by mistake would otherwise silently take over the
+ * first project's bot. With no TTY this does not prompt and does not fail: it
+ * returns the exact command for the operator to run themselves, because an
+ * agent's Bash can never answer a prompt and a hung setup looks like a slow
+ * one.
+ * @param {{ stateDir: string, scriptsDir: string, projectRoot: string,
+ *   replace?: boolean, env?: Record<string, string | undefined>,
+ *   homedir?: string, io?: { canPrompt?: () => boolean,
+ *   promptSecret?: (message: string) => string, fs?: object } }} input -
+ *   Configured state dir, locations, the `--replace` flag and seams
+ * @returns {Promise<{ stored: true, path: string } |
+ *   { stored: false, reason: "no-tty", command: string } |
+ *   { stored: false, reason: "empty" | "invalid", message: string }>} Outcome
+ */
+export async function storeToken(input) {
+  const { scriptsDir, projectRoot, replace = false, io = {} } = input;
+  const stateDir = resolveStateDir(input.stateDir, input);
+  const existing = path.join(stateDir, TOKEN_FILE_NAME);
+  const exists = io.fs?.existsSync ?? nodeFs.existsSync;
+  if (!replace && exists(existing)) {
+    throw new LaunchError(
+      `A bot token already exists at ${existing}. Nothing was changed. ` +
+        `Re-run store-token with --replace to overwrite it.`
+    );
+  }
+  const loaded =
+    io.canPrompt && io.promptSecret ? null : await loadPromptSecret();
+  const canPrompt = io.canPrompt ?? (() => loaded.canPrompt());
+  const promptSecret = io.promptSecret ?? loaded.promptSecret;
+
+  if (!canPrompt()) {
+    return {
+      stored: false,
+      reason: "no-tty",
+      command: buildStoreTokenCommand({ scriptsDir, projectRoot, replace }),
+    };
+  }
+  const typed = promptSecret(
+    `Paste the Telegram bot token for ${stateDir} (input is hidden): `
+  );
+  if (!typed) {
+    return { stored: false, reason: "empty", message: "Nothing entered." };
+  }
+  if (!validateBotToken(typed)) {
+    return {
+      stored: false,
+      reason: "invalid",
+      message:
+        "That does not look like a Telegram bot token " +
+        "(expected <digits>:<30 or more letters, digits, _ or ->).",
+    };
+  }
+  return { stored: true, ...writeTokenFile(stateDir, typed, io) };
+}
+
+/**
+ * Refuse to start unless `<stateDir>/.env` exists and only its owner can read
+ * it. Only the file's metadata is read, never its contents.
+ * @param {string} stateDir - Absolute state dir (already resolved)
+ * @param {{ fs?: Pick<typeof nodeFs, "statSync"> }} [seams] - Injected fs
+ * @returns {{ path: string }} The token file
+ */
+export function assertTokenPresent(stateDir, seams = {}) {
+  const fs = seams.fs ?? nodeFs;
+  const file = path.join(stateDir, TOKEN_FILE_NAME);
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    throw new LaunchError(
+      `No Telegram bot token at ${file}. Run store-token first.`
+    );
+  }
+  if (!stat.isFile()) {
+    throw new LaunchError(`${file} is not a regular file.`);
+  }
+  const bits = stat.mode & 0o777;
+  if ((bits & 0o077) !== 0) {
+    throw new LaunchError(
+      `${file} is readable by other users (mode ${bits.toString(8)}). ` +
+        `Run: chmod 600 ${shellQuote(file)}`
+    );
+  }
+  return { path: file };
+}

package/plugins/src/base/skills/lisa-session-manager/scripts/worker-launch.mjs

@@ -0,0 +1,92 @@
+/**
+ * Running `claude --bg` for `spawn` and `resume`, with the one failure that
+ * is an operator setup step rather than a worker failure called out.
+ *
+ * Claude Code asks once per directory whether to trust the workspace. Until
+ * someone has accepted that prompt in the repo dir, `claude --bg` there exits
+ * 1 with (2.1.296) "Workspace not trusted. Run `claude` in <dir> once and
+ * accept the trust prompt, then retry." A background session cannot show the
+ * prompt, so retrying never helps: that refusal becomes exit 2 (setup) with
+ * the exact step, and the manager skill escalates it instead of counting a
+ * failed attempt. Every other failure keeps the exit-1 message `mustRun`
+ * gives.
+ * @module session-manager/worker-launch
+ */
+import { CliError, EXIT, run } from "./cli-runtime.mjs";
+
+/** How claude words the refusal; matched loosely across versions. */
+const UNTRUSTED_WORKSPACE = /workspace (?:is )?not trusted/i;
+
+/**
+ * Whether a failed `claude --bg` run was refused for workspace trust.
+ * @param {{ stdout: string, stderr: string }} result - Run outcome
+ * @returns {boolean} True for the trust refusal
+ */
+export function isUntrustedWorkspace(result) {
+  return UNTRUSTED_WORKSPACE.test(`${result.stderr}\n${result.stdout}`);
+}
+
+/**
+ * Run a worker spawn or resume spec and return its stdout.
+ *
+ * Runs the command exactly once: a failure is reported, never retried, so a
+ * flaky refusal can never start a second worker.
+ * @param {{ command: string, args: string[], cwd: string,
+ *   env: Record<string, string | undefined> }} spec - From
+ *   `buildWorkerSpawn` or `buildWorkerResume`
+ * @returns {string} stdout
+ */
+export function runWorkerSession(spec) {
+  const result = run(spec.command, spec.args, spec);
+  if (result.missing) {
+    throw new CliError(`${spec.command} is not on PATH.`, EXIT.FAILURE);
+  }
+  if (result.status === 0) return result.stdout;
+  if (isUntrustedWorkspace(result)) {
+    throw new CliError(
+      `Claude Code's workspace trust has not been accepted in ${spec.cwd}, ` +
+        `so claude --bg refused to start a worker there. This is a one-time ` +
+        `step per repo: run \`claude\` once in ${spec.cwd}, accept the trust ` +
+        `prompt, exit, then retry.`,
+      EXIT.SETUP
+    );
+  }
+  const detail = result.stderr.trim() || `exit ${result.status}`;
+  throw new CliError(
+    `${spec.command} ${spec.args[0] ?? ""} failed: ${detail}`,
+    EXIT.FAILURE
+  );
+}
+
+/** A full session UUID; the only id `--resume` continues in place. */
+const FULL_SESSION_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The full session id for a ledger item, for `claude --bg --resume`.
+ *
+ * `claude --bg` prints an 8-character short id, and that is what the ledger
+ * records. Given a short id, `--resume` (2.1.296) does not wake the session:
+ * it starts a copy of the conversation under a new id and names it after the
+ * message, which the manager cannot see. So a short id is mapped to the full
+ * `sessionId` of the matching `claude agents --json --all` row, by worker
+ * name or by short id.
+ * @param {Array<{name: string|null, id: string|null, sessionId: string|null}>}
+ *   agents - Normalized rows from `listAgents(ctx, { all: true })`
+ * @param {{ worker?: string|null, sessionId?: string|null }} item - Ledger item
+ * @returns {string | null} Full lowercase session id, or null when no row
+ *   carries one
+ */
+export function resolveFullSessionId(agents, item) {
+  const recorded = String(item?.sessionId ?? "").toLowerCase();
+  if (FULL_SESSION_ID.test(recorded)) return recorded;
+  const row = agents.find(
+    agent =>
+      FULL_SESSION_ID.test(agent.sessionId ?? "") &&
+      ((item?.worker && agent.name === item.worker) ||
+        (recorded !== "" &&
+          (agent.id === recorded ||
+            agent.sessionId.toLowerCase().startsWith(`${recorded}-`))))
+  );
+  return row ? row.sessionId.toLowerCase() : null;
+}