kronk-cli 0.6.1 → 0.7.0

package/README.md

@@ -1238,30 +1238,53 @@ The model can hand one job to a **sub-agent**: a fresh agent with its own contex
 own tool loop, and no memory of your conversation. It runs the task, and the only thing that
 ever comes back is its report.
 
+While it runs, it draws in a box below the prompt that redraws in place:
+
 ```console
 › which tools in this repo need approval, and where is that decided?
 
   1 ⚙ task explore: list every tool definition in src/, say which are gated and where
-   ┌ explore · list every tool definition in src/, say which are gated…
-   │   1/40 ⚙ search /def\(/ in src
-   │   ✓ 9 lines
-   │   2/40 ⚙ read src/tools.js
-   │   ✓ 587 lines
-   │   3/40 ⚙ read src/subagent.js
-   │   ✓ 211 lines
-   │   2104→380 tok · 58.1 tok/s · 1980 cached
+  ┌─ explore ──────────────────────────────────────── 6/40 · 48s ─┐
+  │ 4/40 ⚙ read src/tools.js                                      │
+  │ ✓ 587 lines                                                   │
+  │ 5/40 ⚙ search /NEEDS_APPROVAL/ in src                         │
+  │ ✓ 3 lines                                                     │
+  │ 6/40 ⚙ read src/subagent.js                                   │
+  └─ esc to collapse · ctrl-c to stop ────────────────────────────┘
+```
+
+When it finishes the box is erased, and what is left in the scrollback is the answer and one
+line saying what the run cost:
+
+```console
+  1 ⚙ task explore: list every tool definition in src/, say which are gated and where
    Six built-in tools. write_file and bash are gated, by NEEDS_APPROVAL at
    src/tools.js:261. MCP tools are gated by name, mcpNeedsApproval at :270.
    read_file, list_dir, search, set_plan and task are not gated.
-   └ 3 steps · 11.4s · /tmp/kronk-cli/mfa1k2-8817/task-001.json
+   └ 3 steps · 11.4s · /tasks 1 for the transcript
   ✓ 3 lines
 
   `write_file` and `bash`, from the `NEEDS_APPROVAL` set in src/tools.js:246…
 ```
 
-`│` marks the sub-agent's own loop; the unprefixed lines are its report, which is what the main
-agent receives as the tool result. `┌` and `└` fence one run, so two in a row are told apart in
-scrollback, and the closing line says what it cost and where the rest of it went.
+The box is the run's only appearance on screen, and that is deliberate. A nine-step survey
+printed into the conversation leaves forty lines of someone else's work between the question
+you asked and the answer you got; scroll back ten minutes later and the conversation is mostly
+sub-agent. While the run is going a live view is the only sign the thing is alive, and it is
+where you notice one thrashing — but once it has ended, almost none of it is worth keeping.
+
+Nothing is lost by erasing it. Everything the box shows is written to the run's transcript as
+it happens, so the box is a view of a file that outlives it, and `/tasks 1` below is how you
+read it back. Three keys and one fallback are worth knowing:
+
+- **`esc` collapses the box immediately** and the run carries on. For when you have seen enough
+  and want your screen back.
+- **`ctrl-c`** stops the run, as it stops anything else.
+- **An approval prompt wipes the box first.** A `code` sub-agent's `write_file` and `bash` stop
+  for the same question the main agent's do, and that question gets the terminal to itself.
+- **On a pipe or a dumb terminal there is no box at all.** `kronk-cli "…" | grep`, a CI job and
+  an `--auto` run nobody is watching each get the plain nested lines instead, in order, with no
+  cursor control in them.
 
 Three files were read. None of them is in your conversation: the 800-odd lines they cost were
 spent in a context that no longer exists, and all that is left in your window is the four-line
@@ -1273,10 +1296,10 @@ already leaving it.
 
 ### Reading a run back
 
-The report on screen is dimmed and capped at fourteen lines. That used to be the end of it: what
-the sub-agent read, what it ran, and any line fifteen of its report went out of scope with its
-context. Delegating is supposed to cost the *conversation* nothing — it was never supposed to
-cost you the ability to check.
+The report on screen is dimmed and capped at fourteen lines, and the box it ran in is gone. That
+used to be the end of it: what the sub-agent read, what it ran, and any line fifteen of its
+report went out of scope with its context. Delegating is supposed to cost the *conversation*
+nothing — it was never supposed to cost you the ability to check.
 
 So each run is written to a file as it goes, and `/tasks` reads them back.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kronk-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A Claude-Code-style terminal agent for local models served by Kronk.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent.js

@@ -75,6 +75,9 @@ function endTurn(messages, { out = console.log, plan = true } = {}) {
   return messages;
 }
 
+/** Stands in for `liveLine()` under a pane, which is drawing the same seconds itself. */
+const QUIET_LIVE = { update() {}, done() {} };
+
 /**
  * Run one user turn to completion, looping while the model requests tools.
  *
@@ -89,6 +92,10 @@ function endTurn(messages, { out = console.log, plan = true } = {}) {
 export async function runTurn({
   messages, model, signal, approve, grant, mcp, auto = false, maxSteps = config.maxSteps,
   tools: toolset = TOOLS, plan: usePlan = true, out = console.log, stream = true, depth = 0,
+  // Print nothing that redraws the current line — the spinner and the live
+  // command line. Set by src/subagent.js when a pane is drawing the run, and
+  // the pane owns the bottom of the screen for as long as it is up.
+  quiet = false,
   // Called with the transcript so far after every round. Only src/subagent.js
   // passes one: a delegated run is the transcript nobody would otherwise keep,
   // and the round that ends it may be a throw or a step cap rather than a
@@ -125,7 +132,7 @@ export async function runTurn({
           : '(stopped: step cap reached)' });
       return endTurn(messages, { out, plan: usePlan });
     }
-    let sp = spinner(depth ? 'sub-agent' : 'thinking');
+    let sp = quiet ? null : spinner(depth ? 'sub-agent' : 'thinking');
     let text = '';
     let reasoning = '';
     let calls = [];
@@ -342,7 +349,7 @@ export async function runTurn({
           result = `error: the sub-agent failed — ${e.message}`;
         }
       } else {
-        const live = liveLine();
+        const live = quiet ? QUIET_LIVE : liveLine();
         try {
           result = isMcp
             ? await mcp.call(call.name, args)

package/src/pane.js

@@ -0,0 +1,268 @@
+import readline from 'node:readline';
+import { c, elapsed } from './ui.js';
+
+/**
+ * The transient pane a delegated run draws in while it is running.
+ *
+ * A sub-agent's tool calls used to go straight into the conversation, nested
+ * under `   │`, and stayed there. That is the wrong trade in both directions.
+ * While the run is going a live view is the only sign the thing is alive, and
+ * it is where you notice a sub-agent thrashing; once it has finished, almost
+ * none of it is worth keeping, because the question you asked and the report
+ * you got are now forty lines apart. The window never paid for any of it —
+ * that is the point of delegating — but the screen paid for all of it.
+ *
+ * So: draw it in a box that redraws in place, and erase the box when the run
+ * ends. Nothing is lost by erasing it. Every line the pane shows was already
+ * written to the run's transcript as it happened (src/tasklog.js), so the pane
+ * is a view of a file that outlives it, and `/tasks <n>` is how you get it
+ * back. That is what makes discarding the pane safe.
+ *
+ * Scrollback, not the alternate screen. A full takeover would be easier to
+ * draw and worse to live with, because it hides the conversation you are in
+ * the middle of. A fixed block redrawn in place keeps the history above it.
+ */
+
+/** Rows of sub-agent activity kept on screen. The box is bounded; the file is not. */
+const BODY_ROWS = 6;
+
+const MIN_WIDTH = 40;
+const MAX_WIDTH = 100;
+
+// eslint-disable-next-line no-control-regex -- matching the escapes is the point
+const SGR = /\x1b\[[0-9;]*m/g;
+
+/** How wide a string prints, once its colour escapes are discounted. */
+export const visibleWidth = (s) => String(s).replace(SGR, '').length;
+
+/** The box's outer width for a terminal this wide, clamped both ways. */
+export const paneWidth = (columns) => Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, (columns || 80) - 2));
+
+/**
+ * Cut a coloured string to `width` printed characters.
+ *
+ * Escapes are copied through without being counted — cutting in the middle of
+ * one would leave the rest of the terminal painted in whatever colour the
+ * fragment happened to open. The trailing reset is only added when something
+ * was actually opened, so a no-colour terminal still gets no escapes at all.
+ */
+export function clip(line, width) {
+  const s = String(line);
+  if (visibleWidth(s) <= width) return s;
+  if (width <= 0) return '';
+  let out = '';
+  let seen = 0;
+  let i = 0;
+  while (i < s.length && seen < width - 1) {
+    if (s[i] === '\x1b') {
+      SGR.lastIndex = i;
+      const m = SGR.exec(s);
+      if (m && m.index === i) { out += m[0]; i += m[0].length; continue; }
+    }
+    out += s[i];
+    i += 1;
+    seen += 1;
+  }
+  return `${out}…${out.includes('\x1b') ? '\x1b[0m' : ''}`;
+}
+
+/** Right-pad to `width` printed characters, so every row ends on the same column. */
+export const pad = (line, width) => `${line}${' '.repeat(Math.max(0, width - visibleWidth(line)))}`;
+
+const rule = (n) => '─'.repeat(Math.max(1, n));
+
+/**
+ * One frame of the box, as lines — pure, so the geometry is testable without a
+ * terminal. Every line it returns is exactly `width` printed characters wide;
+ * `test/pane.test.js` asserts that, because an off-by-one in the arithmetic
+ * below is invisible in a diff and unmissable on screen.
+ */
+export function renderPane({ agent, rows = [], status = '', hint = '', width = 60 }) {
+  const inner = Math.max(4, width - 4);
+  // Printed width, not string length: the status and the hint arrive coloured,
+  // and counting their escapes would pull the right-hand corner off the edge.
+  const w = (s) => (s ? visibleWidth(s) + 1 : 0);
+
+  // `┌─ agent ──…── 6/40 · 48s ─┐`
+  const headFixed = 3 + w(agent) + 1 + w(status) + 2;
+  const top = c.grey('┌─ ') + c.bold(agent) + c.grey(` ${rule(width - headFixed)} ${status ? `${status} ` : ''}─┐`);
+
+  // `└─ esc to collapse · ctrl-c to stop ───┘`
+  const footFixed = 3 + w(hint) + 2;
+  const bottom = c.grey(`└─ ${hint ? `${hint} ` : ''}${rule(width - footFixed)}─┘`);
+
+  const body = rows.map((r) => `${c.grey('│')} ${pad(clip(r, inner), inner)} ${c.grey('│')}`);
+  return [top, ...body, bottom];
+}
+
+/**
+ * Watch for a bare `esc` while the pane is up.
+ *
+ * Deliberately not `setRawMode`. The REPL's readline already owns stdin and
+ * already holds it in raw mode, and it is still reading during a turn — that
+ * is how typing ahead survives (see src/prompt.js). Taking the mode away from
+ * it and handing back what we swallowed is the kind of thing that eats a
+ * user's typing when it goes wrong, and there is no need: readline has already
+ * made stdin emit `keypress`, so a listener is purely additive. Ctrl-C keeps
+ * working because we never intercepted it.
+ *
+ * Armed only when stdin is *already* raw, which is exactly "a readline is
+ * open and reading". In one-shot and `--auto` runs it is not, nobody is
+ * watching, and the footer does not offer a key that would do nothing.
+ */
+export function watchEsc({ input = process.stdin, onEsc } = {}) {
+  if (!onEsc || !input?.isTTY || !input.isRaw) return null;
+  // Idempotent in Node: it returns early if the stream already has a decoder.
+  readline.emitKeypressEvents(input);
+  // `meta` is true on a bare esc and false on `esc [ A`, because node cannot
+  // know which it has until the next byte arrives or `escapeCodeTimeout`
+  // (500 ms) expires — so this is the key, and an arrow key is not. That half
+  // second of lag is invisible next to a run that takes tens of seconds.
+  const onKey = (_s, key) => { if (key?.name === 'escape' && !key.ctrl) onEsc(); };
+  input.on('keypress', onKey);
+  return () => input.off('keypress', onKey);
+}
+
+/**
+ * Whether to draw at all.
+ *
+ * `node src/index.js "hello" | grep` and every CI run land here with a pipe,
+ * and a pipe must get exactly what it got before the pane existed: the nested
+ * lines, in order, with no cursor control in them. A dumb terminal cannot move
+ * a cursor either, so it takes the same path.
+ */
+export const paneUsable = (stream = process.stdout, env = process.env) =>
+  Boolean(stream?.isTTY) && env.TERM !== 'dumb';
+
+/** The inert pane: every call a no-op, so the caller needs no branch of its own. */
+const OFF = {
+  enabled: false,
+  open() {}, line() {}, step() {}, close() {}, collapse() {},
+  shield: (fn) => fn,
+};
+
+/**
+ * The live pane. `open` draws it, `line` feeds it, `close` erases it.
+ *
+ * `shield(fn)` is how the approval prompt stays readable: it wipes the box
+ * before `fn` runs and redraws it after. An approval prompt has to be exactly
+ * as visible and as blocking as it is without a pane, so it gets the terminal
+ * to itself rather than competing with a redraw every 250 ms.
+ */
+export function livePane({
+  agent = 'agent', maxSteps, rows: keep = BODY_ROWS, signal,
+  stream = process.stdout, input = process.stdin, env = process.env,
+  now = Date.now, tickMs = 250,
+} = {}) {
+  if (!paneUsable(stream, env)) return OFF;
+
+  const started = now();
+  const fed = [];
+  let steps = 0;
+  let height = 0;            // rows the box currently occupies on screen
+  let collapsed = false;
+  let timer = null;
+  let unwatch = null;
+  let unabort = null;
+
+  const status = () => {
+    const at = Number.isFinite(maxSteps) ? `${steps}/${maxSteps}` : String(steps);
+    return c.grey(`${at} · ${elapsed(now() - started)}`);
+  };
+
+  const paint = () => {
+    if (collapsed) return;
+    const width = paneWidth(stream.columns);
+    const hint = c.grey(unwatch ? 'esc to collapse · ctrl-c to stop' : 'ctrl-c to stop');
+    const frame = renderPane({ agent, rows: fed, status: status(), hint, width });
+    // Up to the top of the old box, then repaint row by row. `\x1b[K` on each
+    // row so a shorter line does not leave the tail of a longer one behind.
+    let buf = height ? `\r\x1b[${height}A` : '';
+    for (const l of frame) buf += `${l}\x1b[K\n`;
+    // The box only ever grows, but a narrower terminal can shorten it; clear
+    // whatever the previous frame left below this one.
+    if (height > frame.length) buf += '\x1b[J';
+    stream.write(buf);
+    height = frame.length;
+  };
+
+  const erase = () => {
+    if (!height) return;
+    stream.write(`\r\x1b[${height}A\x1b[J`);
+    height = 0;
+  };
+
+  const tick = () => {
+    if (timer) return;
+    timer = setInterval(paint, tickMs);
+    // Never a reason to keep the process alive: the run is what we are waiting on.
+    timer.unref?.();
+  };
+  const untick = () => { clearInterval(timer); timer = null; };
+
+  const stop = () => {
+    untick();
+    unwatch?.();
+    unwatch = null;
+    unabort?.();
+    unabort = null;
+  };
+
+  return {
+    enabled: true,
+
+    open() {
+      unwatch = watchEsc({ input, onEsc: () => this.collapse() });
+      // Ctrl-C aborts the run and then prints `interrupted` — which would land
+      // on top of the box, leaving the next repaint counting rows from the
+      // wrong place and erasing lines of the conversation above. Abort fires
+      // this listener synchronously, so the box is gone before that line
+      // prints. Nothing is lost: the transcript has everything it showed.
+      const onAbort = () => this.collapse();
+      signal?.addEventListener('abort', onAbort, { once: true });
+      // Released with everything else: one turn can delegate several times, and
+      // a listener left on that turn's signal each time is a leak node warns about.
+      unabort = () => signal?.removeEventListener('abort', onAbort);
+      paint();
+      tick();
+    },
+
+    /** One line of sub-agent activity. Only the last `keep` survive. */
+    line(text) {
+      if (collapsed) return;
+      for (const l of String(text).split('\n')) fed.push(l);
+      if (fed.length > keep) fed.splice(0, fed.length - keep);
+      paint();
+    },
+
+    step(n) { steps = n; },
+
+    /** `esc`: give the screen back now. The run carries on into the transcript. */
+    collapse() {
+      if (collapsed) return;
+      erase();
+      collapsed = true;
+      stop();
+    },
+
+    close() {
+      erase();
+      collapsed = true;
+      stop();
+    },
+
+    shield(fn) {
+      if (!fn) return fn;
+      return async (...args) => {
+        const wasUp = !collapsed && height > 0;
+        erase();
+        untick();
+        try {
+          return await fn(...args);
+        } finally {
+          if (wasUp && !collapsed) { paint(); tick(); }
+        }
+      };
+    },
+  };
+}

package/src/subagent.js

@@ -2,6 +2,7 @@ import { def, TOOLS } from './tools.js';
 import { config } from './config.js';
 import { c, elapsed } from './ui.js';
 import { startRun } from './tasklog.js';
+import { livePane } from './pane.js';
 
 /**
  * Sub-agents: one delegated task, one throwaway context.
@@ -152,13 +153,17 @@ export function openLine(agent, prompt) {
  *
  * This is what makes `reportLines`' "…N more lines" actionable: the report on
  * screen is bounded, and now there is somewhere to go for the rest of it and
- * for everything the sub-agent read on the way.
+ * for everything the sub-agent read on the way. Once the pane erases itself it
+ * carries more than that — it is all that is left of the run on screen.
  */
-export function closeLine({ ms, steps, path, ok }) {
+export function closeLine({ ms, steps, n, ok }) {
   // A run that threw or was interrupted is the one worth reading, so the line
   // that points at its transcript must not read like a clean finish.
   const bits = [`${steps} step${steps === 1 ? '' : 's'}`, elapsed(ms), ...(ok ? [] : ['stopped'])];
-  if (path) bits.push(path);
+  // The command that reads the transcript, not the file it reads. The absolute
+  // path under the temp dir is long, mostly noise, and not a thing anyone would
+  // type; `/tasks 3` is both shorter and the answer to "how do I see it".
+  if (n) bits.push(`/tasks ${n} for the transcript`);
   const line = `   └ ${bits.join(' · ')}`;
   return ok ? c.grey(line) : c.yellow(line);
 }
@@ -201,6 +206,9 @@ function reportFrom(messages) {
  */
 export async function runTask(args, {
   run, model, signal, approve, grant, out = console.log, maxSteps = config.subagentSteps,
+  // Injected the same way `run` and `out` are, and for the same reason: the
+  // pane's behaviour is a screen behaviour, and a test has no screen.
+  pane: makePane = livePane,
 }) {
   const agent = args?.agent ?? 'explore';
   const prompt = String(args?.prompt ?? '').trim();
@@ -223,7 +231,15 @@ export async function runTask(args, {
   // model call still leaves a file saying which task was asked for.
   const log = startRun({ agent, prompt, model: config.subagentModel ?? model });
   const started = Date.now();
-  out(openLine(agent, prompt));
+
+  // On a terminal the run is drawn in a box that erases itself; on a pipe, a
+  // dumb terminal or an `--auto` run nobody is watching, `livePane` hands back
+  // an inert one and everything below takes exactly the path it took before
+  // the pane existed. The transcript is written either way, which is what
+  // makes erasing the box safe — see src/pane.js.
+  const pane = makePane({ agent, maxSteps, signal });
+  if (pane.enabled) pane.open();
+  else out(openLine(agent, prompt));
 
   let steps = 0;
   let report;
@@ -236,8 +252,11 @@ export async function runTask(args, {
       window: own ? own.contextWindow : config.contextWindow,
       maxTokens: own?.maxTokens ?? config.maxTokens,
       signal,
-      approve,
-      grant,
+      // Wrapped, not replaced: delegation is still not a way to get a command
+      // past the user. The wrapper only wipes the box first, so the question is
+      // asked on a clear screen and nothing redraws over it while it waits.
+      approve: pane.shield(approve),
+      grant: pane.shield(grant),
       // No MCP: a local model already struggles past ~25 tools, and the
       // sub-agent's list is meant to be the short one.
       mcp: null,
@@ -250,23 +269,33 @@ export async function runTask(args, {
       // second stream interleaved with the caller's is unreadable. Tool calls
       // still show, indented, so the run is not a black box.
       stream: false,
-      out: (line) => out(nest(line)),
+      out: pane.enabled ? (line) => pane.line(line) : (line) => out(nest(line)),
+      // The pane is already the live view, and the spinner and the per-command
+      // live line both rewrite the current line with `\r` — which is the last
+      // row of the box. Two things redrawing the same row is the one way this
+      // can look broken, so below a pane there is only one of them.
+      quiet: pane.enabled,
       maxSteps,
       depth: 1,
       // Written as it goes rather than at the end. The runs worth reading are
       // the ones that were interrupted, threw, or ran out of steps, and none
       // of those reach the line below.
-      onStep: (msgs, n) => { steps = n; log?.step(msgs, n); },
+      onStep: (msgs, n) => { steps = n; pane.step(n); log?.step(msgs, n); },
     });
 
     report = reportFrom(done);
+    // Before the report, so the box is gone by the time the answer lands in
+    // the scrollback it is keeping clean.
+    pane.close();
     reportLines(report).forEach((l) => out(l));
     return report;
   } finally {
     // In `finally` so an abort or a throw still closes the record and still
     // tells the user where the partial transcript is — that is the case the
-    // transcript exists for.
-    const path = log?.finish({ report, steps });
-    out(closeLine({ ms: Date.now() - started, steps, path, ok: report !== undefined }));
+    // transcript exists for. `close` is idempotent; the success path already
+    // called it above.
+    pane.close();
+    log?.finish({ report, steps });
+    out(closeLine({ ms: Date.now() - started, steps, n: log?.n, ok: report !== undefined }));
   }
 }