@xsft/panels 0.2.0 → 0.3.1

package/README.md

@@ -27,11 +27,11 @@ npx @xsft/panels run xsft/marketing-site/v6 . at http://localhost:4321 --sources
 
 Run the command in the folder of the product. Each judge starts in that folder, so `.`, a branch, and relative paths resolve there. The CLI does not test, fetch, or change the target. Four judges run at a time. A judge gets 20 minutes.
 
-## tmux mode
+## Terminal mode
 
-On a terminal with `tmux` on PATH, `panels run` opens a tmux session: window 0 shows the scores, and window N runs judge N in the interactive harness. Each judge writes `judges/N/answer.json` and stays open; window 0 writes the report when each judge has an answer or an error, and the command exits from `report.json` when you leave the session. Without a terminal or tmux, the judges run in the background (`claude -p`, `codex exec`).
+On a terminal, `panels run` shows the score table, and each judge runs in its interactive harness in a pseudo-terminal inside the command. Each judge writes `judges/N/answer.json` and stays open. The table writes the report when each judge has an answer or an error, and the command exits from `report.json` when you quit. Without a terminal, the judges run in the background (`claude -p`, `codex exec`).
 
-Keys in window 0: `1` to `9` open the window of that judge (tmux `prefix 0` comes back), `q` ends the session and asks `y` while a judge still runs.
+Keys in the table: `1` to `9` open the screen of that judge, and `q` quits and asks `y` while a judge still runs. In a judge, each key goes to the judge, and `ctrl-]` returns to the table.
 
 ## Run folder
 
@@ -39,8 +39,7 @@ Each run writes to `.panels/<owner>-<name>/<UTC time>/`:
 
 - `panel.json`: the panel as the api gave it.
 - `report.md` and `report.json`: the scores, the evidence, the fixes, and the errors. `schema/report.json` is the schema of `report.json`.
-- `judges/<k>/`: the prompt, the output schema, and the raw answer of judge k. In tmux mode, `start.sh` and `answer.json` take the place of the raw answer.
-- `run.json`, in tmux mode: the session name, the harness, the folder, and the target, for window 0.
+- `judges/<k>/`: the prompt, the output schema, and the raw answer of judge k. In terminal mode, `answer.json` takes the place of the raw answer.
 
 The last line on stdout is the path of `report.json`.
 

package/bin/panels.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
-import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { delimiter, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parse, SYNOPSIS } from '../lib/args.js';
-import { runJudge, writeJudge } from '../lib/judge.js';
+import { runJudge } from '../lib/judge.js';
 import { fetchPanel } from '../lib/panel.js';
 import { buildReport, renderMarkdown } from '../lib/report.js';
+import { runTable } from '../lib/table.js';
 
 // More parallel sessions on one account get 429 answers from the model api.
 const PARALLEL_JUDGES = 4;
@@ -28,17 +27,9 @@ async function pool(items, size, fn) {
 
 const EXIT = { pass: 0, fail: 1, error: 2 };
 
-/** Starts the scores window in a new tmux session, attaches to it, and exits from report.json when the attach returns. */
-function runInTmux({ panel, runDir, time, harness, cwd, args }) {
-  const session = `panels-${time.slice(11, 16)}`;
-  writeFileSync(join(runDir, 'run.json'), JSON.stringify({ session, harness, cwd, target: args.target }, null, 2));
-  panel.criteria.forEach((c, i) => writeJudge({ dir: join(runDir, 'judges', String(i + 1)), criteria: [{ rank: i + 1, ...c }], harness, cwd, target: args.target, brief: args.brief, sources: args.sources }));
-  execFileSync('tmux', ['new-session', '-d', '-s', session, '-n', 'scores', process.execPath, fileURLToPath(new URL('../lib/table.js', import.meta.url)), runDir]);
-  if (process.env.TMUX) {
-    execFileSync('tmux', ['switch-client', '-t', session]);
-    return 0;
-  }
-  spawnSync('tmux', ['attach-session', '-t', session], { stdio: 'inherit' });
+/** Runs the judges in the score table, and exits from report.json when the engineer quits. */
+async function runOnTerminal({ panel, runDir, harness, cwd, args }) {
+  await runTable({ panel, runDir, harness, cwd, target: args.target, brief: args.brief, sources: args.sources });
   const reportPath = join(runDir, 'report.json');
   if (!existsSync(reportPath)) return 2;
   console.log(reportPath);
@@ -76,7 +67,7 @@ async function main() {
   const runDir = join(cwd, '.panels', `${panel.owner}-${panel.name}`, time);
   mkdirSync(runDir, { recursive: true });
   writeFileSync(join(runDir, 'panel.json'), JSON.stringify(panel, null, 2));
-  if (process.stdout.isTTY && process.stdin.isTTY && onPath('tmux')) return runInTmux({ panel, runDir, time, harness, cwd, args });
+  if (process.stdout.isTTY && process.stdin.isTTY) return runOnTerminal({ panel, runDir, harness, cwd, args });
   const outcomes = await pool(judges, PARALLEL_JUDGES, (indexes, j) => runJudge({
     dir: join(runDir, 'judges', String(j + 1)),
     criteria: indexes.map((i) => ({ rank: i + 1, ...panel.criteria[i] })),

package/lib/judge.js

@@ -1,11 +1,9 @@
 import { spawn } from 'node:child_process';
 import { closeSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 const { judgeResult } = JSON.parse(readFileSync(new URL('../schema/report.json', import.meta.url), 'utf8')).$defs;
-const SYSTEM_PROMPT_FILE = fileURLToPath(new URL('../prompts/judge-system-prompt.txt', import.meta.url));
-const SYSTEM_PROMPT = readFileSync(SYSTEM_PROMPT_FILE, 'utf8');
+const SYSTEM_PROMPT = readFileSync(new URL('../prompts/judge-system-prompt.txt', import.meta.url), 'utf8');
 export const MINUTES_PER_CRITERION = 20;
 const TOOLS = 'Read,Glob,Grep,Bash,WebFetch,WebSearch';
 // With --permission-mode dontAsk, Claude refuses every tool call that this list does not allow, so Bash runs git reads only.
@@ -146,31 +144,28 @@ export async function runJudge({ dir, criteria, harness, cwd, target, brief, sou
   return errors.length ? { error: `invalid answer after one re-ask: ${errors.join(' ')}` } : { results: reply.answer.results };
 }
 
-/** Quotes a string for sh. */
-export const sq = (s) => `'${s.replaceAll("'", "'\\''")}'`;
-
 const TOML_ESCAPES = { '"': '\\"', '\\': '\\\\', '\n': '\\n' };
 
 /** A TOML basic string, for the value of a codex -c flag. */
 export const tomlString = (s) => `"${s.replace(/["\\\x00-\x1f\x7f]/g, (c) => TOML_ESCAPES[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)}"`;
 
-/** The shell command that starts one judge of the tmux mode in its interactive harness. */
-export function startScript({ dir, harness, cwd, brief, sources }) {
-  const prompt = `"$(cat ${sq(join(dir, 'prompt.md'))})"`;
+/**
+ * Writes prompt.md and schema.json of one judge of the terminal mode, and returns the command and the
+ * arguments that start the judge in its interactive harness.
+ */
+export function writeJudge({ dir, criteria, harness, cwd, target, brief, sources }) {
+  mkdirSync(dir, { recursive: true });
+  const closing = `The engineer ran the command in ${cwd}. As your last step, write your answer JSON, which matches the schema in ${join(dir, 'schema.json')}, to ${join(dir, 'answer.json')}. Write that file yourself with a tool, and do not start sub-agents: the JSON in your reply does not count. Then stop. These two files are the only exceptions to the rules on writing files and on the .panels folder.\n`;
+  const prompt = `${userMessage(criteria, { target, brief, sources })}\n${closing}`;
+  writeFileSync(join(dir, 'prompt.md'), prompt);
+  writeFileSync(join(dir, 'schema.json'), JSON.stringify(judgeSchema(criteria), null, 2));
   if (harness === 'codex') {
-    return `codex -C ${sq(dir)} -s workspace-write --disable multi_agent --disable apps -c ${sq(`developer_instructions=${tomlString(SYSTEM_PROMPT)}`)} ${prompt}\n`;
+    // Codex ranks the developer instructions above the prompt, and the system prompt says to return the JSON and to
+    // write no files. Without the closing in the developer instructions, the judge prints the JSON and writes no answer.json.
+    return ['codex', '-C', dir, '-s', 'workspace-write', '--disable', 'multi_agent', '--disable', 'apps', '-c', `developer_instructions=${tomlString(`${SYSTEM_PROMPT}\n${closing}`)}`, prompt];
   }
-  const add = addDirs(cwd, brief, sources).map((d) => ` --add-dir ${sq(d)}`).join('');
   // Claude matches file paths only in Edit rules, which cover Write too; // starts an absolute path.
   const allowed = `${ALLOWED_TOOLS},Edit(/${join(dir, 'answer.json')})`;
-  return `claude --safe-mode --system-prompt "$(cat ${sq(SYSTEM_PROMPT_FILE)})" --tools ${TOOLS},Write${add} --allowedTools ${sq(allowed)} --permission-mode dontAsk ${prompt}\n`;
-}
-
-/** Writes prompt.md, schema.json, and start.sh of one judge of the tmux mode. */
-export function writeJudge({ dir, criteria, harness, cwd, target, brief, sources }) {
-  mkdirSync(dir, { recursive: true });
-  const closing = `The engineer ran the command in ${cwd}. As your last step, write your answer JSON, which matches the schema in ${join(dir, 'schema.json')}, to ${join(dir, 'answer.json')}. Then stop. These two files are the only exceptions to the rules on writing files and on the .panels folder.\n`;
-  writeFileSync(join(dir, 'prompt.md'), `${userMessage(criteria, { target, brief, sources })}\n${closing}`);
-  writeFileSync(join(dir, 'schema.json'), JSON.stringify(judgeSchema(criteria), null, 2));
-  writeFileSync(join(dir, 'start.sh'), startScript({ dir, harness, cwd, brief, sources }));
+  const add = addDirs(cwd, brief, sources).flatMap((d) => ['--add-dir', d]);
+  return ['claude', '--safe-mode', '--system-prompt', SYSTEM_PROMPT, '--tools', `${TOOLS},Write`, ...add, '--allowedTools', allowed, '--permission-mode', 'dontAsk', prompt];
 }

package/lib/table.js

@@ -1,9 +1,11 @@
-// Window 0 of the tmux mode: `node table.js <run folder>`. It starts the judge windows, shows the scores, and writes the report.
-import { execFileSync, spawnSync } from 'node:child_process';
+// The terminal mode of `panels run`: the score table, and a view of each judge. Each judge runs its interactive
+// harness in a pseudo-terminal, and a headless terminal keeps its screen for the switch to its view.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { check, MINUTES_PER_CRITERION, parseAnswer } from './judge.js';
+import pty from '@homebridge/node-pty-prebuilt-multiarch';
+import { SerializeAddon } from '@xterm/addon-serialize';
+import xterm from '@xterm/headless';
+import { check, MINUTES_PER_CRITERION, parseAnswer, writeJudge } from './judge.js';
 import { buildReport, renderMarkdown } from './report.js';
 
 // More parallel sessions on one account get 429 answers from the model api.
@@ -12,9 +14,13 @@ const ORANGE = '\x1b[38;2;255;106;61m';
 const GREY = '\x1b[90m';
 const BOLD = '\x1b[1m';
 const RESET = '\x1b[0m';
+// ctrl-] returns from a judge to the table. A terminal in the kitty keyboard mode sends it as CSI 93;5u.
+const BACK = ['\x1d', '\x1b[93;5u'];
+// Turns off each mode that the screen of a judge can turn on, so the table gets the keys and the screen as before.
+const TABLE_MODES = '\x1b[?1049h\x1b[r\x1b[0m\x1b[4l\x1b[?6l\x1b[?7h\x1b[?1l\x1b>\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1004l\x1b[?2004l\x1b[<u\x1b[?25l\x1b[2J';
 
 /**
- * The lines of window 0. rows hold { rank, name, state, result }, and state is queued, running, done, or error.
+ * The lines of the table. rows hold { rank, name, state, result }, and state is queued, running, done, or error.
  * final is null until the report exists, then { status, path }. confirm is true while q waits for y.
  */
 export function render({ title, rows, final, confirm, width }) {
@@ -37,17 +43,31 @@ export function render({ title, rows, final, confirm, width }) {
   return lines;
 }
 
-function main(runDir) {
-  const read = (file) => JSON.parse(readFileSync(join(runDir, file), 'utf8'));
-  const panel = read('panel.json');
-  const { session, harness, cwd, target } = read('run.json');
+/**
+ * The next { view, confirm } after one key, plus send: true when the key goes to the judge, or quit: true.
+ * view is 0 for the table, or N for judge N. open holds the ranks of the judges that have started.
+ */
+export function press({ view, confirm }, key, { open, running }) {
+  if (view) return BACK.includes(key) ? { view: 0, confirm: false } : { view, confirm, send: true };
+  if (confirm) return { view: 0, confirm: false, quit: key === 'y' };
+  if (key === 'q') return running ? { view: 0, confirm: true } : { view: 0, confirm: false, quit: true };
+  if (/^[1-9]$/.test(key) && open.includes(Number(key))) return { view: Number(key), confirm: false };
+  return { view: 0, confirm: false };
+}
+
+/** Runs the judges, shows the table, and writes the report. Resolves when the engineer quits. */
+export function runTable({ panel, runDir, harness, cwd, target, brief, sources }) {
+  const out = process.stdout;
   const criteria = panel.criteria.map((c, i) => ({ rank: i + 1, ...c }));
-  const started = [];
+  const judges = [];
   let rows = [];
   let final = null;
-  let confirm = false;
+  let ui = { view: 0, confirm: false };
+  let footerTimer;
 
   const judgeDir = (rank) => join(runDir, 'judges', String(rank));
+  // A judge gets one line less than the terminal. The last line holds the footer.
+  const size = () => ({ cols: out.columns, rows: out.rows - 1 });
 
   function state(c, i) {
     const file = join(judgeDir(c.rank), 'answer.json');
@@ -56,14 +76,60 @@ function main(runDir) {
       const errors = check(answer, [c]);
       return errors.length ? { state: 'error', error: `invalid answer: ${errors.join(' ')}` } : { state: 'done', result: answer.results[0] };
     }
-    if (started[i] === undefined) return { state: 'queued' };
-    if (Date.now() - started[i] > MINUTES_PER_CRITERION * 60_000) return { state: 'error', error: `no answer.json after ${MINUTES_PER_CRITERION} minutes` };
+    if (judges[i] === undefined) return { state: 'queued' };
+    if (Date.now() - judges[i].started > MINUTES_PER_CRITERION * 60_000) return { state: 'error', error: `no answer.json after ${MINUTES_PER_CRITERION} minutes` };
     return { state: 'running' };
   }
 
   function start(rank) {
-    started[rank - 1] = Date.now();
-    execFileSync('tmux', ['new-window', '-d', '-t', `${session}:${rank}`, '-n', `judge-${rank}`, '-c', cwd, 'sh', join(judgeDir(rank), 'start.sh')]);
+    const [command, ...argv] = writeJudge({ dir: judgeDir(rank), criteria: [criteria[rank - 1]], harness, cwd, target, brief, sources });
+    const { cols, rows: lines } = size();
+    const term = new xterm.Terminal({ cols, rows: lines, allowProposedApi: true });
+    const serializer = new SerializeAddon();
+    term.loadAddon(serializer);
+    const proc = pty.spawn(command, argv, { name: 'xterm-256color', cols, rows: lines, cwd, env: process.env });
+    const j = { started: Date.now(), term, serializer, proc, modes: { 25: 'h', 1006: 'l' }, exited: false };
+    // The write callback keeps the order of the live output and of the screen that showJudge writes.
+    proc.onData((data) => term.write(data, () => {
+      if (ui.view !== rank) return;
+      out.write(data);
+      footer();
+    }));
+    proc.onExit(() => { j.exited = true; });
+    // The headless terminal answers the queries of the harness, such as the cursor position.
+    term.onData((data) => proc.write(data));
+    // The serializer does not keep the cursor visibility (25) or the mouse encoding (1006), so each judge keeps them here.
+    for (const final of ['h', 'l']) {
+      term.parser.registerCsiHandler({ prefix: '?', final }, (params) => {
+        for (const p of params) if (p in j.modes) j.modes[p] = final;
+        return false;
+      });
+    }
+    judges[rank - 1] = j;
+  }
+
+  function drawFooter() {
+    if (!ui.view) return;
+    const { cursorX, cursorY } = judges[ui.view - 1].term.buffer.active;
+    out.write(`\x1b[${out.rows};1H${RESET}${GREY} judge ${ui.view}   ctrl-] scores${RESET}\x1b[K\x1b[${cursorY + 1};${cursorX + 1}H`);
+  }
+
+  // Waits for a pause in the output, so the footer does not land inside an escape sequence that a chunk split.
+  function footer() {
+    clearTimeout(footerTimer);
+    footerTimer = setTimeout(drawFooter, 50);
+  }
+
+  function showJudge(rank) {
+    const j = judges[rank - 1];
+    j.term.write('', () => {
+      if (ui.view !== rank) return;
+      // The table already holds the alternate screen, so a judge on its alternate screen gets a clear after
+      // the normal screen, which the serializer writes first. The scroll region keeps the judge off the footer line.
+      const screen = j.serializer.serialize({ scrollback: 0 }).replace('\x1b[?1049h\x1b[H', '$&\x1b[2J');
+      out.write(`${RESET}\x1b[H\x1b[2J\x1b[1;${out.rows - 1}r${screen}${Object.entries(j.modes).map(([mode, final]) => `\x1b[?${mode}${final}`).join('')}`);
+      drawFooter();
+    });
   }
 
   function finish() {
@@ -76,8 +142,8 @@ function main(runDir) {
   }
 
   function draw() {
-    const lines = render({ title: `${panel.owner}/${panel.name} v${panel.version}`, rows, final, confirm, width: Math.min(process.stdout.columns, 100) });
-    process.stdout.write(`\x1b[H${lines.map((l) => `${l}\x1b[K`).join('\n')}\x1b[J`);
+    const lines = render({ title: `${panel.owner}/${panel.name} v${panel.version}`, rows, final, confirm: ui.confirm, width: Math.min(out.columns, 100) });
+    out.write(`\x1b[H${lines.map((l) => `${l}\x1b[K`).join('\n')}\x1b[J`);
   }
 
   function tick() {
@@ -90,30 +156,45 @@ function main(runDir) {
       }
       if (rows.every((r) => r.state === 'done' || r.state === 'error')) finish();
     }
-    draw();
+    if (!ui.view) draw();
   }
 
-  const quit = () => execFileSync('tmux', ['kill-session', '-t', session]);
-
-  process.stdout.write('\x1b[?1049h\x1b[?25l');
-  process.stdin.setRawMode(true);
-  process.stdin.on('data', (data) => {
-    const key = data.toString();
-    if (confirm) {
-      confirm = false;
-      if (key === 'y') quit();
-    } else if (key === 'q') {
-      if (rows.some((r) => r.state === 'running')) confirm = true;
-      else quit();
-    } else if (/^[1-9]$/.test(key) && Number(key) <= rows.length) {
-      // A queued judge has no window yet, so tmux fails, and its message goes to the ignored pipe.
-      spawnSync('tmux', ['select-window', '-t', `${session}:${key}`]);
-    }
-    draw();
+  return new Promise((done) => {
+    const timer = setInterval(tick, 1000);
+    out.write('\x1b[?1049h\x1b[?25l');
+    process.stdin.setRawMode(true);
+    process.stdin.on('data', (data) => {
+      const key = data.toString();
+      const from = ui.view;
+      const next = press(ui, key, { open: judges.flatMap((j, i) => (j ? [i + 1] : [])), running: rows.some((r) => r.state === 'running') });
+      ui = { view: next.view, confirm: next.confirm };
+      if (next.send) {
+        judges[from - 1].proc.write(key);
+      } else if (next.quit) {
+        clearInterval(timer);
+        // The harness on PATH can be a shell script that runs the real binary as a child and waits for it, so
+        // SIGHUP goes to the process group of the judge. The pty makes each judge the leader of its own group.
+        for (const j of judges) if (j && !j.exited) process.kill(-j.proc.pid, 'SIGHUP');
+        out.write(`${TABLE_MODES}\x1b[?25h\x1b[?1049l`);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        done();
+      } else if (ui.view) {
+        showJudge(ui.view);
+      } else {
+        if (from) out.write(TABLE_MODES);
+        draw();
+      }
+    });
+    out.on('resize', () => {
+      const { cols, rows: lines } = size();
+      for (const j of judges) {
+        if (j && !j.exited) j.proc.resize(cols, lines);
+        j?.term.resize(cols, lines);
+      }
+      if (ui.view) showJudge(ui.view);
+      else draw();
+    });
+    tick();
   });
-  process.stdout.on('resize', draw);
-  tick();
-  setInterval(tick, 1000);
 }
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv[2]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsft/panels",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Run a panel of AI judges from cross.software/panels against a target.",
   "type": "module",
@@ -8,5 +8,10 @@
   "files": ["bin", "lib", "prompts", "schema", "README.md"],
   "license": "UNLICENSED",
   "engines": { "node": ">=20" },
-  "scripts": { "test": "node --test test/*.test.js" }
+  "scripts": { "test": "node --test test/*.test.js" },
+  "dependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "0.14.1",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0"
+  }
 }