@codyswann/lisa 4.80.2 → 4.81.0

package/plugins/lisa-cursor/skills/lisa-session-manager/scripts/cli-cycle.mjs

@@ -0,0 +1,262 @@
+/**
+ * Per-cycle subcommands of the session-manager CLI: ledger, route,
+ * blocked-plan and record-cycle (`queue` lives in cli-queue.mjs).
+ *
+ * Every piece of untrusted text these commands take (a worker's question, a
+ * Telegram message, a finish reason, the cycle summary, an item's body and
+ * comments) arrives on stdin or in a file, never in argv.
+ * @module session-manager/cli-cycle
+ */
+import {
+  AUTOMATION_RUN_OUTCOMES,
+  recordAutomationRun,
+} from "../../../scripts/automation-run-record.mjs";
+import {
+  CliError,
+  EXIT,
+  asSetupErrorAsync,
+  humanNeededLabel,
+  intFlag,
+  loadProject,
+  requirePositional,
+  stdinText,
+} from "./cli-runtime.mjs";
+import { parseJson, readJsonFile } from "./cli-queue.mjs";
+import {
+  clearPendingQuestion,
+  readLedger,
+  recordFinish,
+  recordSpawn,
+  setControl,
+  setPendingQuestion,
+} from "./ledger.mjs";
+import { planBlockedRelease } from "./reconcile.mjs";
+import { formatAnswer, routeInbound } from "./telegram-route.mjs";
+
+/** The automation loop id every cycle records under. */
+const LOOP_ID = "session-manager";
+
+/** The runbook the automation-runbook contract requires for this loop. */
+const RUNBOOK = ".lisa/automations/session-manager.runbook.md";
+/**
+ * Parse `--paused true|false`.
+ * @param {string | undefined} value - Flag value
+ * @returns {boolean | undefined} Parsed value
+ */
+function pausedFlag(value) {
+  if (value === undefined) return undefined;
+  if (value !== "true" && value !== "false") {
+    throw new CliError("--paused must be true or false.", 2);
+  }
+  return value === "true";
+}
+
+/**
+ * Parse a flag where `none` clears the value.
+ * @param {string | undefined} value - Flag value
+ * @param {(value: string) => unknown} parse - Parser for a real value
+ * @returns {unknown} Parsed value, null for `none`, undefined when absent
+ */
+function clearable(value, parse) {
+  if (value === undefined) return undefined;
+  return value === "none" ? null : parse(value);
+}
+
+/**
+ * With `--sender <name>`, refuse (exit 2) unless the ledger holds `ref` for
+ * exactly that worker. The manager passes the cross-session sender of a
+ * worker's report, so one worker can never finish or question another
+ * worker's item; the manager's own calls (stall, operator stop, repo-routing
+ * questions) omit the flag.
+ * @param {object} ctx - CLI context
+ * @param {string} ref - Ref the report names
+ * @returns {Promise<void>}
+ */
+async function assertSender(ctx, ref) {
+  const sender = ctx.values.sender;
+  if (sender === undefined) return;
+  const items = (await readLedger(ctx.root)).items;
+  const worker = Object.hasOwn(items, ref) ? items[ref].worker : null;
+  if (worker !== sender) {
+    throw new CliError(
+      `${sender} is not the worker for ${ref} (the ledger has ` +
+        `${worker ?? "no worker"}); ignoring its message.`,
+      2
+    );
+  }
+}
+
+/** One handler per `ledger <action>`. */
+const LEDGER_ACTIONS = {
+  async get(ctx) {
+    const ledger = await readLedger(ctx.root);
+    const [ref] = ctx.positionals;
+    if (!ref) return ledger;
+    if (!Object.hasOwn(ledger.items, ref)) {
+      throw new CliError(`${ref} is not in the ledger.`, 2);
+    }
+    return ledger.items[ref];
+  },
+  "record-spawn": ctx =>
+    recordSpawn(ctx.root, {
+      ref: requirePositional(ctx, "ref"),
+      worker: requireValue(ctx, "worker"),
+      sessionId: ctx.values["session-id"] ?? null,
+      repo: ctx.values.repo ?? ".",
+    }),
+  async "set-question"(ctx) {
+    const ref = requirePositional(ctx, "ref");
+    await assertSender(ctx, ref);
+    return setPendingQuestion(ctx.root, {
+      ref,
+      text: stdinText(ctx, "question"),
+      telegramMessageId:
+        intFlag(ctx.values["telegram-message-id"], "--telegram-message-id") ??
+        null,
+    });
+  },
+  "clear-question": ctx =>
+    clearPendingQuestion(ctx.root, { ref: requirePositional(ctx, "ref") }),
+  async finish(ctx) {
+    const status = ctx.values.status;
+    if (status !== "DONE" && status !== "FAILED") {
+      throw new CliError("--status must be DONE or FAILED.", 2);
+    }
+    const ref = requirePositional(ctx, "ref");
+    await assertSender(ctx, ref);
+    return recordFinish(ctx.root, {
+      ref,
+      status,
+      reason: stdinText(ctx, "reason", { required: false }),
+    });
+  },
+  control: ctx =>
+    setControl(
+      ctx.root,
+      Object.fromEntries(
+        Object.entries({
+          paused: pausedFlag(ctx.values.paused),
+          maxWorkers: clearable(ctx.values["max-workers"], value =>
+            intFlag(value, "--max-workers")
+          ),
+          me: clearable(ctx.values.me, value => value),
+        }).filter(([, value]) => value !== undefined)
+      )
+    ),
+};
+
+/** Ledger actions the CLI accepts, for usage and argv specs. */
+export const LEDGER_ACTION_NAMES = Object.keys(LEDGER_ACTIONS);
+
+/**
+ * A required flag value, or exit 2.
+ * @param {object} ctx - CLI context
+ * @param {string} flag - Flag name without dashes
+ * @returns {string} Value
+ */
+function requireValue(ctx, flag) {
+  const value = ctx.values[flag];
+  if (!value) throw new CliError(`Missing --${flag}.`, 2);
+  return value;
+}
+
+/**
+ * `ledger <action>`: read or update the manager's ledger.
+ * @param {object} ctx - CLI context; `ctx.action` is the ledger action
+ * @returns {Promise<{ json: unknown }>} The item, control or whole ledger
+ */
+export async function ledger(ctx) {
+  const handler = LEDGER_ACTIONS[ctx.action];
+  return { json: await asSetupErrorAsync(() => handler(ctx)) };
+}
+
+/**
+ * `route [--reply-to <id>] [--owner <name>]`: decide what one Telegram message
+ * (on stdin) is: an answer for a worker, an operator command, or ambiguous.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} Route, plus `message` for an answer
+ *   when `--owner` is given
+ */
+export async function route(ctx) {
+  const text = stdinText(ctx, "message", { required: false });
+  const routed = routeInbound({
+    text,
+    replyToMessageId: intFlag(ctx.values["reply-to"], "--reply-to") ?? null,
+    ledger: await readLedger(ctx.root),
+  });
+  const owner = ctx.values.owner;
+  if (routed.kind === "answer" && owner) {
+    return { json: { ...routed, message: formatAnswer(owner, routed.body) } };
+  }
+  return { json: routed };
+}
+
+/**
+ * `blocked-plan [--input <file>] [--ref <ref>]`: plan one Blocked item from
+ * its JSON (stdin, or the file). `--ref` fills in the ledger's pending
+ * question when the input does not carry one.
+ *
+ * Who may release a human hold comes from `sessionManager.trustedAuthorIds`
+ * only. Any `trustedHumanActorIds` in the input is discarded: the input is
+ * assembled from the item's own (untrusted) body and comments, so a list
+ * carried beside them would let the item's text vouch for itself.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{action,reason,edges,gate}`
+ */
+export async function blockedPlan(ctx) {
+  const input = ctx.values.input
+    ? readJsonFile(ctx.values.input)
+    : parseJson(stdinText(ctx, "item JSON"), "stdin");
+  const ref = ctx.values.ref;
+  const pendingQuestion =
+    input.pendingQuestion ??
+    (ref ? (await readLedger(ctx.root)).items[ref]?.pendingQuestion : null);
+  const project = loadProject(ctx.root);
+  const trustedHumanActorIds = project.config?.trustedAuthorIds ?? [];
+  return {
+    json: planBlockedRelease({
+      ...input,
+      // The configured label, so a Jira `Human Needed` hold is still a hold.
+      humanNeededLabel:
+        input.humanNeededLabel ?? humanNeededLabel(project, undefined),
+      pendingQuestion,
+      trustedHumanActorIds,
+    }),
+  };
+}
+
+/**
+ * `record-cycle --outcome <o> [--ref <url>]... [--run-id <id>]`: record this
+ * cycle's run outcome, with the one-line summary on stdin.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} What was recorded
+ */
+export async function recordCycle(ctx) {
+  const outcome = ctx.values.outcome;
+  if (!AUTOMATION_RUN_OUTCOMES.includes(outcome)) {
+    throw new CliError(
+      `--outcome must be one of: ${AUTOMATION_RUN_OUTCOMES.join(", ")}.`,
+      EXIT.SETUP
+    );
+  }
+  const result = await asSetupErrorAsync(() =>
+    recordAutomationRun({
+      projectRoot: ctx.root,
+      loopId: LOOP_ID,
+      runbook: RUNBOOK,
+      outcome,
+      summary: stdinText(ctx, "cycle summary"),
+      refs: ctx.values.ref ?? [],
+      ...(ctx.values["run-id"] ? { runId: ctx.values["run-id"] } : {}),
+    })
+  );
+  return {
+    json: {
+      path: result.path,
+      appended: result.appended,
+      loop_id: result.record.loop_id,
+      outcome: result.record.outcome,
+      run_id: result.record.run_id,
+    },
+  };
+}

package/plugins/lisa-cursor/skills/lisa-session-manager/scripts/cli-manager.mjs

@@ -0,0 +1,308 @@
+/**
+ * Manager and setup subcommands of the session-manager CLI: start, stop,
+ * status, repo-dir, validate, init-config and store-token.
+ *
+ * `start` hosts the manager in tmux. It refuses (exit 2) unless the bot
+ * token file exists with owner-only permissions in the project's own state
+ * dir, and it treats an existing tmux session started in this root as
+ * "already running" rather than starting a second poller on the same bot. A
+ * session of that name started in another root is another project's manager,
+ * so both `start` and `stop` refuse it (exit 2). `stop` kills only the
+ * manager's tmux session: workers hold claimed work and keep running.
+ * @module session-manager/cli-manager
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  CliError,
+  EXIT,
+  GLOBAL_CONFIG_FILE,
+  asSetupError,
+  asSetupErrorAsync,
+  intFlag,
+  listAgents,
+  loadProject,
+  mustRun,
+  requireConfig,
+  requireLisaRepo,
+  run,
+} from "./cli-runtime.mjs";
+import { buildDefaultBlock, detectRepos, resolveRepoDir } from "./config.mjs";
+import {
+  defaultProjectSlug,
+  probeOwnSession,
+  sessionSurvives,
+} from "./isolation.mjs";
+import {
+  assertTokenPresent,
+  buildForegroundCommand,
+  buildHasSession,
+  buildManagerLaunch,
+  buildStopManager,
+  resolveStateDir,
+  storeToken as storeTokenFile,
+} from "./launch.mjs";
+import { readLedger } from "./ledger.mjs";
+import { parseWorkerName, scrubWorkerEnv } from "./workers.mjs";
+
+/**
+ * The configured state dir, resolved (exit 2 for the shared default dir).
+ * @param {object} ctx - CLI context
+ * @param {object} config - Resolved block
+ * @returns {string} Absolute state dir
+ */
+function stateDirOf(ctx, config) {
+  return asSetupError(() =>
+    resolveStateDir(config.notify?.stateDir, {
+      env: ctx.env,
+      homedir: ctx.homedir,
+    })
+  );
+}
+
+/** How long a new manager session must survive before `start` says so. */
+const DEFAULT_SETTLE_MS = 3000;
+
+/** Upper bound for `--settle-ms`, so `start` always returns promptly. */
+const MAX_SETTLE_MS = 60_000;
+
+/**
+ * `--settle-ms`, defaulted and bounded, or exit 2.
+ * @param {object} ctx - CLI context
+ * @returns {number} Milliseconds
+ */
+function settleMsOf(ctx) {
+  const value = intFlag(ctx.values["settle-ms"], "--settle-ms");
+  if (value !== undefined && value > MAX_SETTLE_MS) {
+    throw new CliError(
+      `--settle-ms must be at most ${MAX_SETTLE_MS}.`,
+      EXIT.SETUP
+    );
+  }
+  return value ?? DEFAULT_SETTLE_MS;
+}
+
+/**
+ * `start [--settle-ms <n>]`: host the manager in a detached tmux session,
+ * and report `started` only once the session has survived the settle window
+ * (claude can exit at once on a bad argv; tmux then closes the session).
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{status,name,...}`
+ */
+export async function start(ctx) {
+  const settleMs = settleMsOf(ctx);
+  const config = requireConfig(ctx);
+  const stateDir = stateDirOf(ctx, config);
+  // tmux gets the scrubbed env: if this call starts the tmux server, its
+  // global environment must not carry a TELEGRAM_* value into other sessions.
+  const env = scrubWorkerEnv(ctx.env);
+  const session = probeOwnSession(ctx, config.name, env);
+  if (session.missing) throw new CliError("tmux is not on PATH.", EXIT.SETUP);
+  if (session.running) {
+    return { json: { status: "already-running", name: config.name } };
+  }
+  asSetupError(() => assertTokenPresent(stateDir));
+  const argv = asSetupError(() =>
+    buildManagerLaunch({
+      name: config.name,
+      root: ctx.root,
+      stateDir,
+      scriptsDir: ctx.scriptsDir,
+      interval: config.interval,
+    })
+  );
+  mustRun("tmux", argv, { env, cwd: ctx.root });
+  if (!(await sessionSurvives(config.name, env, settleMs))) {
+    const foreground = buildForegroundCommand(argv);
+    throw new CliError(
+      `The manager's tmux session "${config.name}" exited within ` +
+        `${settleMs} ms of starting, so the manager is not running. Run the ` +
+        `launch in the foreground to see claude's error:\n  ${foreground}`,
+      EXIT.SETUP
+    );
+  }
+  return {
+    json: {
+      status: "started",
+      name: config.name,
+      stateDir,
+      attach: `tmux attach -t ${config.name}`,
+    },
+  };
+}
+
+/**
+ * `stop`: kill the manager's tmux session only, and only when it was started
+ * in this root (exit 2 for another project's session of the same name).
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object }} `{status:"stopped"|"not-running",name}`
+ */
+export function stop(ctx) {
+  const config = requireConfig(ctx);
+  const env = scrubWorkerEnv(ctx.env);
+  if (!probeOwnSession(ctx, config.name, env).running) {
+    return { json: { status: "not-running", name: config.name } };
+  }
+  const result = run("tmux", buildStopManager(config.name), { env });
+  const stopped = result.status === 0;
+  return {
+    json: { status: stopped ? "stopped" : "not-running", name: config.name },
+  };
+}
+
+/**
+ * `repo-dir [--repo <key>] [--raw]`: the directory a claim or worker for this
+ * repo key must run in.
+ * @param {object} ctx - CLI context
+ * @returns {{ json?: object, text?: string }} JSON, or the bare path
+ */
+export function repoDir(ctx) {
+  const config = requireConfig(ctx);
+  const key = ctx.values.repo;
+  const dir = requireLisaRepo(
+    asSetupError(() => resolveRepoDir(config, key, ctx.root))
+  );
+  if (ctx.values.raw) return { text: `${dir}\n` };
+  return { json: { repo: key ?? ".", dir } };
+}
+
+/**
+ * Problems `validateSessionManager` cannot see: they need the filesystem.
+ * @param {object} ctx - CLI context
+ * @param {object} config - Resolved block
+ * @returns {string[]} Problems
+ */
+function environmentProblems(ctx, config) {
+  const problems = Object.keys(config.repos?.entries ?? {}).flatMap(key => {
+    try {
+      requireLisaRepo(resolveRepoDir(config, key, ctx.root));
+      return [];
+    } catch (error) {
+      return [`sessionManager.repos.entries.${key}: ${error.message}`];
+    }
+  });
+  if (typeof config.notify?.stateDir === "string") {
+    try {
+      stateDirOf(ctx, config);
+    } catch (error) {
+      problems.push(`sessionManager.notify.stateDir: ${error.message}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * `validate`: every problem with the block, exit 2 when there is any.
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object, exitCode: number }} `{valid,errors}`
+ */
+export function validate(ctx) {
+  const project = loadProject(ctx.root);
+  const errors = project.config
+    ? [...project.errors, ...environmentProblems(ctx, project.config)]
+    : [`No sessionManager block in ${GLOBAL_CONFIG_FILE}.`];
+  return {
+    json: { valid: errors.length === 0, errors },
+    exitCode: errors.length === 0 ? EXIT.OK : EXIT.SETUP,
+  };
+}
+
+/**
+ * `init-config [--slug <slug>] [--write]`: the default block for this
+ * project, written to `.lisa.config.json` only with `--write` and only when
+ * no block exists. Non-secret fields only; the token never goes here.
+ * @param {object} ctx - CLI context
+ * @returns {{ json: object }} `{written,block,...}`
+ */
+export function initConfig(ctx) {
+  const { global } = loadProject(ctx.root);
+  if (global?.sessionManager) {
+    return {
+      json: { written: false, reason: "exists", block: global.sessionManager },
+    };
+  }
+  const slug =
+    ctx.values.slug ?? defaultProjectSlug(ctx.root, global?.github?.repo);
+  const block = asSetupError(() =>
+    buildDefaultBlock({
+      projectSlug: slug,
+      detectedRepos: detectRepos(ctx.root),
+    })
+  );
+  if (!ctx.values.write) return { json: { written: false, block } };
+
+  const file = path.join(ctx.root, GLOBAL_CONFIG_FILE);
+  if (!existsSync(file)) {
+    throw new CliError(
+      `${file} does not exist; set up Lisa in this project first.`,
+      EXIT.SETUP
+    );
+  }
+  const current = JSON.parse(readFileSync(file, "utf8"));
+  writeFileSync(
+    file,
+    `${JSON.stringify({ ...current, sessionManager: block }, null, 2)}\n`
+  );
+  return { json: { written: true, path: file, block } };
+}
+
+/**
+ * `store-token [--replace]`: prompt for the bot token on the operator's
+ * terminal and write `<stateDir>/.env`. An existing token is kept (exit 2)
+ * unless `--replace` is given. With no TTY it prints the command the operator
+ * must run themselves and exits 0 with `stored:false`.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object, exitCode: number }>} Outcome
+ */
+export async function storeToken(ctx) {
+  const config = requireConfig(ctx);
+  const result = await asSetupErrorAsync(() =>
+    storeTokenFile({
+      stateDir: config.notify?.stateDir,
+      scriptsDir: ctx.scriptsDir,
+      projectRoot: ctx.root,
+      replace: ctx.values.replace === true,
+      env: ctx.env,
+      homedir: ctx.homedir,
+    })
+  );
+  const refused = result.stored === false && result.reason !== "no-tty";
+  return { json: result, exitCode: refused ? EXIT.SETUP : EXIT.OK };
+}
+
+/**
+ * `status`: is the manager's tmux session up, and what does the ledger say
+ * about each worker it dispatched.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{manager,control,workers,untracked}`
+ */
+export async function status(ctx) {
+  const config = requireConfig(ctx);
+  const tmux = run("tmux", buildHasSession(config.name), { env: ctx.env });
+  const agents = listAgents(ctx, { all: true });
+  const ledger = await readLedger(ctx.root);
+  const liveNames = new Set(
+    agents.filter(agent => agent.active).map(agent => agent.name)
+  );
+  const tracked = new Set(Object.values(ledger.items).map(i => i.worker));
+  return {
+    json: {
+      manager: { name: config.name, running: tmux.status === 0 },
+      control: ledger.control,
+      workers: Object.entries(ledger.items).map(([ref, item]) => ({
+        ref,
+        worker: item.worker ?? null,
+        sessionId: item.sessionId ?? null,
+        repo: item.repo ?? null,
+        status: item.status ?? null,
+        attempts: item.attempts ?? 0,
+        pendingQuestion: Boolean(item.pendingQuestion),
+        live: liveNames.has(item.worker),
+      })),
+      untracked: [...liveNames]
+        .filter(name => parseWorkerName(name) !== null && !tracked.has(name))
+        .sort(),
+    },
+  };
+}