@codyswann/lisa 4.80.2 → 4.81.1

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

@@ -0,0 +1,148 @@
+/**
+ * The `queue` subcommand of the session-manager CLI: the Ready queue, mine
+ * first, paged to completion.
+ *
+ * "Page to completion" is executable here rather than prose. GitHub is
+ * fetched by this module with `gh api --paginate --slurp`, so every page is
+ * read or the command fails. Jira and Linear are fetched by their vendor
+ * skills (a script cannot reach them), which write an envelope
+ * `{complete, pages, items}`; anything but a literal `complete: true` is
+ * refused with exit 2, because ordering a partial queue would dispatch the
+ * wrong item with full confidence.
+ * @module session-manager/cli-queue
+ */
+import { readFileSync } from "node:fs";
+
+import {
+  assertPagedToCompletion,
+  normalizeGithubIssue,
+  normalizeJiraIssue,
+  normalizeLinearIssue,
+  orderReadyQueue,
+} from "../../../scripts/ready-queue-order.mjs";
+import { resolveRole } from "../../../scripts/resolve-lifecycle-role.mjs";
+import {
+  CliError,
+  asSetupError,
+  humanNeededLabel,
+  loadProject,
+  mustRun,
+  validOrAbsent,
+} from "./cli-runtime.mjs";
+import { readLedger } from "./ledger.mjs";
+import { scrubWorkerEnv } from "./workers.mjs";
+
+const NORMALIZERS = { jira: normalizeJiraIssue, linear: normalizeLinearIssue };
+
+const OWNER_REPO = /^[\w.-]+\/[\w.-]+$/;
+
+/**
+ * Parse JSON, or exit 2 naming the source.
+ * @param {string} text - JSON text
+ * @param {string} source - Where it came from
+ * @returns {any} Parsed value
+ */
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new CliError(`${source} is not valid JSON: ${error.message}`, 2);
+  }
+}
+
+/**
+ * Read a JSON file named by a flag, or exit 2.
+ * @param {string} file - Path
+ * @returns {any} Parsed value
+ */
+export function readJsonFile(file) {
+  const text = asSetupError(() => readFileSync(file, "utf8"));
+  return parseJson(text, file);
+}
+
+/**
+ * Fetch every open GitHub issue carrying the ready label, all pages.
+ * @param {object} ctx - CLI context
+ * @param {ReturnType<typeof loadProject>} project - Loaded project
+ * @returns {{ items: object[], pages: number }} Normalized items
+ */
+function fetchGithubQueue(ctx, project) {
+  const merged = { ...project.global?.github, ...project.local?.github };
+  const repo =
+    ctx.values["github-repo"] ??
+    (merged.org && merged.repo ? `${merged.org}/${merged.repo}` : "");
+  if (!OWNER_REPO.test(repo)) {
+    throw new CliError(
+      "No GitHub repo: set github.org and github.repo, or pass --github-repo <owner/repo>.",
+      2
+    );
+  }
+  const role = resolveRole({
+    role: "ready",
+    vendor: "github",
+    intent: "read",
+    local: project.local,
+    global: project.global,
+  });
+  const label = ctx.values.label ?? role.value;
+  if (!label) throw new CliError(role.message, 2);
+  const endpoint =
+    `repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}` +
+    `&per_page=100`;
+  const stdout = mustRun("gh", ["api", "--paginate", "--slurp", endpoint], {
+    env: scrubWorkerEnv(ctx.env),
+  });
+  const pages = parseJson(stdout, "gh api output");
+  const rows = Array.isArray(pages) ? pages.flat() : [];
+  return {
+    items: rows.map(row => normalizeGithubIssue(row, { repo })).filter(Boolean),
+    pages: Array.isArray(pages) ? pages.length : 0,
+  };
+}
+
+/**
+ * Read a vendor-skill envelope and normalize its raw issues.
+ * @param {object} ctx - CLI context
+ * @param {"jira"|"linear"} tracker - Vendor
+ * @returns {{ items: object[], pages: unknown }} Normalized items
+ */
+function readEnvelopeQueue(ctx, tracker) {
+  const file = ctx.values.input;
+  if (!file) {
+    throw new CliError(`queue --tracker ${tracker} needs --input <file>.`, 2);
+  }
+  const envelope = readJsonFile(file);
+  asSetupError(() => assertPagedToCompletion(envelope));
+  if (!Array.isArray(envelope.items)) {
+    throw new CliError(`${file}: items must be an array.`, 2);
+  }
+  return {
+    items: envelope.items.map(NORMALIZERS[tracker]),
+    pages: envelope.pages ?? null,
+  };
+}
+
+/**
+ * `queue --tracker <github|jira|linear>`: the Ready queue, mine first.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{tracker,me,total,pages,ordered,excluded}`
+ */
+export async function queue(ctx) {
+  const tracker = ctx.values.tracker;
+  if (tracker !== "github" && !Object.hasOwn(NORMALIZERS, tracker ?? "")) {
+    throw new CliError("--tracker must be github, jira or linear.", 2);
+  }
+  const project = loadProject(ctx.root);
+  const config = validOrAbsent(project);
+  const { items, pages } =
+    tracker === "github"
+      ? fetchGithubQueue(ctx, project)
+      : readEnvelopeQueue(ctx, tracker);
+  const me = ctx.values.me ?? (await readLedger(ctx.root)).control.me ?? null;
+  const order = orderReadyQueue(items, {
+    me,
+    trustedAuthorIds: config?.trustedAuthorIds ?? undefined,
+    humanNeededLabel: humanNeededLabel(project, tracker),
+  });
+  return { json: { tracker, me, total: items.length, pages, ...order } };
+}

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

@@ -0,0 +1,326 @@
+/**
+ * Shared plumbing for the session-manager CLI subcommands: exit codes, the
+ * error type that carries one, config loading, child-process execution and
+ * stdin.
+ *
+ * Every subcommand module receives a `ctx` built once by `session-manager.mjs`
+ * (the only file that reads the real environment), so nothing here reaches for
+ * globals. Child processes are always started with `spawnSync(command, argv)`:
+ * there is no shell anywhere on this path, so ticket text, Telegram text and
+ * worker names can never be re-parsed as shell syntax.
+ * @module session-manager/cli-runtime
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  resolveSessionManagerConfig,
+  validateSessionManager,
+} from "./config.mjs";
+import {
+  HUMAN_GATE_SIGNAL,
+  resolveSignalLabel,
+} from "../../../scripts/qa-signal-lifecycle.mjs";
+import { normalizeAgents, scrubWorkerEnv } from "./workers.mjs";
+
+/** Exit codes the manager skill branches on. */
+export const EXIT = Object.freeze({
+  OK: 0,
+  FAILURE: 1,
+  SETUP: 2,
+  NO_CAPACITY: 3,
+  LIVE_WORKER: 4,
+});
+
+/** The config files Lisa reads, local over global per key. */
+export const GLOBAL_CONFIG_FILE = ".lisa.config.json";
+const LOCAL_CONFIG_FILE = ".lisa.config.local.json";
+
+/** Child output can be a whole paginated queue; allow far more than 1 MiB. */
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/**
+ * A refusal or failure with the exit code the CLI should end with, and
+ * optionally a JSON body to print on stdout (e.g. the capacity report for
+ * exit 3, so the manager can say why it did not spawn).
+ */
+export class CliError extends Error {
+  /**
+   * @param {string} message - Operator-readable reason, printed on stderr
+   * @param {number} [exitCode] - Process exit code
+   * @param {unknown} [json] - Optional stdout body
+   */
+  constructor(message, exitCode = EXIT.FAILURE, json = undefined) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.json = json;
+  }
+}
+
+/**
+ * Run `fn`, turning any plain error it throws (a validation refusal from a
+ * pure module) into a setup error, exit 2. System errors (they carry a
+ * `code` such as EACCES) and CliErrors pass through unchanged.
+ * @template T
+ * @param {() => T} fn - Work that may refuse its input
+ * @returns {T} Its result
+ */
+export function asSetupError(fn) {
+  try {
+    return fn();
+  } catch (error) {
+    throw toSetupError(error);
+  }
+}
+
+/**
+ * Async form of {@link asSetupError}.
+ * @template T
+ * @param {() => Promise<T>} fn - Work that may refuse its input
+ * @returns {Promise<T>} Its result
+ */
+export async function asSetupErrorAsync(fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw toSetupError(error);
+  }
+}
+
+/**
+ * Map one thrown value to a CliError, keeping system errors as they are.
+ * @param {unknown} error - Thrown value
+ * @returns {unknown} Value to rethrow
+ */
+function toSetupError(error) {
+  if (error instanceof CliError || typeof error?.code === "string") {
+    return error;
+  }
+  return new CliError(error?.message ?? String(error), error?.exitCode ?? 2);
+}
+
+/**
+ * Read and parse one JSON config file; absent is `undefined`.
+ * @param {string} file - Absolute path
+ * @returns {object | undefined} Parsed config
+ */
+function readConfigFile(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new CliError(`${file} is not valid JSON: ${error.message}`, 2);
+  }
+}
+
+/**
+ * The view of a resolved block the validator expects: keys the resolver
+ * fills with `null` for "absent" are passed as absent.
+ * @param {object} config - Resolved block
+ * @returns {object} Block to validate
+ */
+function validationView(config) {
+  return {
+    ...config,
+    repos: config.repos ?? undefined,
+    trustedAuthorIds: config.trustedAuthorIds ?? undefined,
+  };
+}
+
+/**
+ * Read both config files and resolve the `sessionManager` block.
+ * @param {string} root - Absolute project root
+ * @returns {{ global: object | undefined, local: object | undefined,
+ *   config: object | null, errors: string[] }} Raw files, resolved block
+ *   (null when absent) and validation errors
+ */
+export function loadProject(root) {
+  const global = readConfigFile(path.join(root, GLOBAL_CONFIG_FILE));
+  const local = readConfigFile(path.join(root, LOCAL_CONFIG_FILE));
+  const config = resolveSessionManagerConfig(global, local);
+  const errors = config ? validateSessionManager(validationView(config)) : [];
+  return { global, local, config, errors };
+}
+
+/**
+ * The label that marks an item as waiting on a person, for this tracker.
+ *
+ * Each tracker keeps it somewhere different and Jira's default is spelled
+ * differently (`Human Needed`), so a hardcoded `human-needed` would let a held
+ * Jira item through to a worker. Local config wins over global, then the
+ * tracker's own default.
+ * @param {ReturnType<typeof loadProject>} project - Loaded project
+ * @param {string | undefined} tracker - `github`, `jira` or `linear`; the
+ *   project's configured tracker when omitted
+ * @returns {string | undefined} The label, or undefined for an unknown tracker
+ */
+export function humanNeededLabel(project, tracker) {
+  const vendor = tracker ?? project.local?.tracker ?? project.global?.tracker;
+  for (const config of [project.local, project.global]) {
+    const resolved = resolveSignalLabel({
+      signal: HUMAN_GATE_SIGNAL,
+      config,
+      vendor,
+    });
+    if (resolved.source === "config") return resolved.value;
+  }
+  const fallback = resolveSignalLabel({
+    signal: HUMAN_GATE_SIGNAL,
+    config: {},
+    vendor,
+  });
+  return fallback.value || undefined;
+}
+
+/**
+ * Throw exit 2 unless the block is valid; return it only when present.
+ * @param {ReturnType<typeof loadProject>} project - Loaded project
+ * @returns {object | null} Resolved block, or null when absent
+ */
+export function validOrAbsent(project) {
+  if (project.errors.length > 0) {
+    throw new CliError(
+      `sessionManager config is invalid:\n- ${project.errors.join("\n- ")}`,
+      2
+    );
+  }
+  return project.config;
+}
+
+/**
+ * The resolved block, or exit 2 when it is absent or invalid.
+ * @param {{ root: string }} ctx - CLI context
+ * @returns {object} Resolved `sessionManager` block
+ */
+export function requireConfig(ctx) {
+  const config = validOrAbsent(loadProject(ctx.root));
+  if (!config) {
+    throw new CliError(
+      `No sessionManager block in ${path.join(ctx.root, GLOBAL_CONFIG_FILE)}. ` +
+        `Run /lisa:setup:session-manager first.`,
+      2
+    );
+  }
+  return config;
+}
+
+/**
+ * Throw exit 2 unless `dir` carries a `.lisa.config.json`: a worker running
+ * `/lisa:implement` there would have no tracker or gates.
+ * @param {string} dir - Absolute repo dir
+ * @returns {string} The same dir
+ */
+export function requireLisaRepo(dir) {
+  if (!existsSync(path.join(dir, GLOBAL_CONFIG_FILE))) {
+    throw new CliError(
+      `${dir} has no ${GLOBAL_CONFIG_FILE}; a worker cannot run /lisa:implement there.`,
+      2
+    );
+  }
+  return dir;
+}
+
+/**
+ * Run a command with an argv array and no shell.
+ * @param {string} command - Executable, looked up on PATH
+ * @param {readonly string[]} args - argv
+ * @param {{ env: Record<string, string | undefined>, cwd?: string }} options
+ *   - Environment and working directory
+ * @returns {{ status: number | null, stdout: string, stderr: string,
+ *   missing: boolean }} Outcome; `missing` when the command is not on PATH
+ */
+export function run(command, args, { env, cwd }) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    maxBuffer: MAX_BUFFER,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    missing: result.error?.code === "ENOENT",
+  };
+}
+
+/**
+ * Run a command and return its stdout, or throw exit 1 naming what failed.
+ * @param {string} command - Executable
+ * @param {readonly string[]} args - argv
+ * @param {{ env: Record<string, string | undefined>, cwd?: string }} options
+ *   - Environment and working directory
+ * @returns {string} stdout
+ */
+export function mustRun(command, args, options) {
+  const result = run(command, args, options);
+  if (result.missing) {
+    throw new CliError(`${command} is not on PATH.`, 1);
+  }
+  if (result.status !== 0) {
+    const detail = result.stderr.trim() || `exit ${result.status}`;
+    throw new CliError(`${command} ${args[0] ?? ""} failed: ${detail}`, 1);
+  }
+  return result.stdout;
+}
+
+/**
+ * Normalized `claude agents --json` rows. `all` adds finished sessions,
+ * which matter for naming (never reuse a name) but never for liveness.
+ * @param {{ env: Record<string, string | undefined> }} ctx - CLI context
+ * @param {{ all?: boolean }} [options] - Include finished sessions
+ * @returns {ReturnType<typeof normalizeAgents>} Rows
+ */
+export function listAgents(ctx, { all = false } = {}) {
+  const args = all ? ["agents", "--json", "--all"] : ["agents", "--json"];
+  const stdout = mustRun("claude", args, { env: scrubWorkerEnv(ctx.env) });
+  try {
+    return normalizeAgents(JSON.parse(stdout));
+  } catch (error) {
+    throw new CliError(`claude agents --json: ${error.message}`, 1);
+  }
+}
+
+/**
+ * Text piped on stdin, trimmed. Untrusted text (answers, questions, reasons,
+ * summaries) always arrives here, never in argv.
+ * @param {{ readStdin: () => string }} ctx - CLI context
+ * @param {string} what - What the text is, for the error message
+ * @param {{ required?: boolean }} [options] - Refuse empty input
+ * @returns {string} Text
+ */
+export function stdinText(ctx, what, { required = true } = {}) {
+  const text = ctx.readStdin().trim();
+  if (required && text === "") {
+    throw new CliError(`Pipe the ${what} on stdin; it was empty.`, 2);
+  }
+  return text;
+}
+
+/**
+ * Parse a non-negative integer flag, or exit 2.
+ * @param {string | undefined} value - Flag value
+ * @param {string} flag - Flag name for the message
+ * @returns {number | undefined} Integer, or undefined when absent
+ */
+export function intFlag(value, flag) {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/.test(value)) {
+    throw new CliError(`${flag} must be a non-negative integer.`, 2);
+  }
+  return Number(value);
+}
+
+/**
+ * The first positional, or exit 2.
+ * @param {{ positionals: string[] }} ctx - CLI context
+ * @param {string} what - Name for the message
+ * @returns {string} Value
+ */
+export function requirePositional(ctx, what) {
+  const [value] = ctx.positionals;
+  if (!value) throw new CliError(`Missing <${what}>.`, 2);
+  return value;
+}

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

@@ -0,0 +1,114 @@
+/**
+ * The session-manager CLI's `--help` text: the single reference for every
+ * subcommand, flag, stdin input and exit code. The manager and setup skills
+ * use exactly what is written here, so a flag that is not listed does not
+ * exist.
+ * @module session-manager/cli-usage
+ */
+
+export const USAGE = `Usage: node session-manager.mjs <subcommand> [args] [--project-root <abs>]
+
+Every subcommand accepts --project-root <absolute dir> (default: the current
+directory) and -h/--help. Output is one line of JSON on stdout (repo-dir --raw
+prints a bare path); errors go to stderr. Untrusted text (answers, questions,
+reasons, Telegram messages, summaries) is read from STDIN, never from argv.
+
+Exit codes: 0 ok; 1 a command failed (claude, tmux or gh error); 2 bad repo,
+bad config or bad usage; 3 no capacity; 4 a live worker already holds the ref.
+
+Workers and capacity
+  capacity [--max-workers <n>]
+      {running,cap,free_slots,avail_gb,load1,cores,overloaded,can_spawn,
+       mem_source,paused}. Works without a sessionManager block (defaults).
+      Cap precedence: ledger control.maxWorkers, then --max-workers, then config.
+      (capacity and spawn also take --meminfo <file>, a TEST-ONLY flag that
+      reads memory from a Linux meminfo file instead of this host. Skills
+      never pass it.)
+  spawn <ref> [--repo <key>] [--max-workers <n>]
+      Checks, in order: repo dir resolves and has .lisa.config.json (exit 2);
+      capacity (exit 3, stdout = capacity report); no live wk- worker for the
+      ref (exit 4, stdout = {ref,worker,sessionId}). Then runs, with cwd = repo
+      dir and every TELEGRAM_* variable removed:
+        claude --bg -n wk-<token>-<MMDD-HHMM> --dangerously-skip-permissions
+          --settings {"crossSessionInbound":"accept"}
+          "/lisa:implement <ref> managedBy=<sessionManager.name>"
+      Records the ledger and sessions.jsonl. stdout {ref,name,sessionId,repo,cwd}.
+  resume <ref>                         STDIN: the message for the worker
+      claude --bg --resume <full session id> -- "<stdin>" in the worker's repo
+      dir, TELEGRAM_* removed; the full id comes from claude agents --json --all
+      (exit 2 when none does). stdout {ref,worker,sessionId,resumed:true}.
+  classify [<ref>]
+      Classifies one ledger item (or all) from claude agents --json --all and
+      a hash of claude logs <worker>; records the hash as progress. stdout
+      [{ref,worker,sessionId,repo,classification,attempts,agentStatus,
+        pendingQuestion}], classification one of finished|waiting|requestion|
+      working|stalled|dead|exhausted.
+  status
+      stdout {manager:{name,running},control,workers:[{ref,worker,sessionId,
+      repo,status,attempts,pendingQuestion,live}],untracked:[wk- names]}.
+
+Manager
+  start [--settle-ms <n>]
+             Refuses (exit 2) without <notify.stateDir>/.env (mode 0600) or for
+             the shared default state dir. "already-running" when the tmux
+             session =<name> exists and was started in this project root;
+             exit 2 naming the conflict when it was started anywhere else.
+             Otherwise starts tmux new-session for the manager, then checks
+             has-session -t =<name> every 250 ms for --settle-ms (default
+             3000, at most 60000): exit 2, with the foreground command to run
+             to see claude's error, when the session is gone.
+             stdout {status:"started"|"already-running",name,...}.
+  stop       tmux kill-session -t =<name> only, and only for a session started
+             in this root (exit 2 otherwise); workers keep running.
+             stdout {status:"stopped"|"not-running",name}.
+  store-token [--replace]
+             Prompts for the bot token on the terminal (echo off) and writes
+             <stateDir>/.env. Exit 2 when a token is already there, unless
+             --replace. With no TTY: exit 0, stdout {stored:false,
+             reason:"no-tty",command} where command is the line the operator
+             runs in their own terminal. Bad input: exit 2.
+
+Config and routing
+  repo-dir [--repo <key>] [--raw]
+             stdout {repo,dir}; --raw prints the bare dir. Exit 2 for an
+             unknown key or a dir without .lisa.config.json.
+  validate   stdout {valid,errors}; exit 2 when invalid or absent.
+  init-config [--slug <slug>] [--write]
+             stdout {written,block[,reason:"exists"][,path]}. Detects
+             projects/*/.lisa.config.json. Default slug: <github.repo or
+             folder name>-<first 6 hex of sha256(realpath(root))>; --slug is
+             used as given. --write adds the block to .lisa.config.json,
+             never overwriting an existing one.
+
+Per cycle
+  queue --tracker github [--me <id>] [--label <name>] [--github-repo <o/r>]
+      gh api --paginate --slurp repos/<o>/<r>/issues?state=open&labels=<ready>
+      Label default: the configured ready role; repo default: github.org/repo.
+  queue --tracker jira|linear --input <file> [--me <id>]
+      <file> = {complete:true,pages,items:[raw vendor issues]}; exit 2 unless
+      complete is exactly true.
+      Both print {tracker,me,total,pages,ordered,excluded:[{ref,reason}]}.
+      --me defaults to the ledger's control.me.
+  ledger get [<ref>]
+  ledger record-spawn <ref> --worker <name> [--session-id <id>] [--repo <key>]
+  ledger set-question <ref> [--telegram-message-id <n>] [--sender <name>]
+                                                           STDIN: question
+  ledger clear-question <ref>
+  ledger finish <ref> --status DONE|FAILED [--sender <name>]  STDIN: reason
+      --sender: exit 2 unless the ledger's worker for <ref> is exactly <name>.
+  ledger control [--paused true|false] [--max-workers <n>|none] [--me <id>|none]
+  route [--reply-to <telegram message id>] [--owner <name>] STDIN: message
+      stdout {kind:"answer",ref,body[,message]} | {kind:"command",name,...}
+      | {kind:"invalid-command",reason} | {kind:"ambiguous",candidates}.
+      --owner adds message "<owner>'s answer: ...".
+  blocked-plan [--input <file>] [--ref <ref>]  STDIN (without --input): JSON
+      {labels,body,comments,humanNeededLabel?,edges,pendingQuestion?}.
+      Trusted hold releasers are sessionManager.trustedAuthorIds (none when
+      unset); trustedHumanActorIds in the input is ignored. stdout
+      {action:release|keep|escalate|skip-human-gate,reason,edges,gate}.
+      --ref fills pendingQuestion from the ledger.
+  record-cycle --outcome <outcome> [--ref <url>]... [--run-id <id>]
+      STDIN: one-line summary. Records loop session-manager with runbook
+      .lisa/automations/session-manager.runbook.md. stdout {path,appended,
+      loop_id,outcome,run_id}.
+`;