ucode-agent 1.5.0 → 1.7.0

package/src/tools/symbols.js

@@ -0,0 +1,218 @@
+/**
+ * symbols.js — a map of what this codebase declares, so "where is the tip
+ * calculated" is one lookup rather than five greps.
+ *
+ * grep finds every line that mentions a name; almost all of them are uses,
+ * and the one that matters is the declaration. This reads each source file
+ * once and records only the declarations: functions, classes, components,
+ * types, and the route a Next.js page answers on.
+ *
+ * The scan is by pattern, not by a parser. A parser would be exact but would
+ * mean carrying TypeScript itself and paying its start-up on every lookup;
+ * declarations are one of the few things regular expressions read reliably,
+ * because they sit at the start of a line in formatted code. What this can
+ * miss is a declaration written unusually — and a miss costs a grep, which
+ * is where we started.
+ *
+ * The index is held per directory and rebuilt when a file's modified time
+ * moves, so an edit is picked up without a rescan of everything.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { resolveIn, guard, result, walk } from './shared.js';
+
+/** Files worth reading for declarations. */
+const SOURCE = /\.(?:[cm]?[jt]sx?|py)$/i;
+
+/** How much of a file to read; a declaration past this is a generated file's. */
+const MAX_BYTES = 400_000;
+
+const PATTERNS = [
+  // export function foo(...) / export default function foo(...)
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/ },
+  // class Foo / export class Foo
+  { kind: 'class', re: /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+  // const foo = (...) => / const foo = async (...) => / const foo = function
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=]+)?=>/ },
+  { kind: 'function', re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?function/ },
+  // type Foo = / interface Foo / enum Foo
+  { kind: 'type', re: /^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*[<=]/ },
+  { kind: 'type', re: /^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/ },
+  { kind: 'type', re: /^\s*(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)/ },
+  // Python
+  { kind: 'function', re: /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)/ },
+  { kind: 'class', re: /^\s*class\s+([A-Za-z_][\w]*)/ },
+];
+
+/** A capitalised function in a .tsx file is a component, and worth saying so. */
+const isComponent = (name, rel) => /^[A-Z]/.test(name) && /\.[jt]sx$/i.test(rel);
+
+/**
+ * The URL a Next.js app-router file answers on: src/app/blog/[slug]/page.tsx
+ * is /blog/[slug]. Route groups in brackets-as-parens are not part of the path.
+ */
+export function routeFor(rel) {
+  const m = rel.replace(/\\/g, '/').match(/(?:^|\/)app\/(.*)\/(page|route|layout)\.[jt]sx?$/i);
+  if (!m) {
+    if (/(?:^|\/)app\/(page|route|layout)\.[jt]sx?$/i.test(rel.replace(/\\/g, '/'))) return '/';
+    return null;
+  }
+  const url = m[1].split('/').filter((s) => s && !/^\(.*\)$/.test(s)).join('/');
+  return `/${url}`;
+}
+
+/** Every declaration in one file's text, with the line it sits on. */
+export function declarationsIn(rel, text) {
+  const found = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > 400) continue;
+    for (const { kind, re } of PATTERNS) {
+      const m = line.match(re);
+      if (!m) continue;
+      const name = m[1];
+      found.push({
+        name,
+        kind: isComponent(name, rel) && kind === 'function' ? 'component' : kind,
+        file: rel,
+        line: i + 1,
+        text: line.trim().slice(0, 160),
+      });
+      break; // one declaration to a line
+    }
+  }
+  return found;
+}
+
+const indexes = new Map(); // root -> { files: Map<rel, {at, symbols}> }
+
+/**
+ * Read the declarations of every source file under `root`, reusing what was
+ * read before for files whose modified time has not moved.
+ */
+export async function buildIndex(root) {
+  let index = indexes.get(root);
+  if (!index) { index = { files: new Map() }; indexes.set(root, index); }
+
+  const rels = (await walk(root, {})).filter((rel) => SOURCE.test(rel));
+  const seen = new Set();
+
+  await Promise.all(rels.map(async (rel) => {
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    let stat;
+    try { stat = await fs.stat(abs); } catch { return; }
+    if (stat.size > MAX_BYTES) return;
+    const had = index.files.get(rel);
+    if (had && had.at === stat.mtimeMs) return; // unchanged since last time
+    const text = await fs.readFile(abs, 'utf8').catch(() => null);
+    if (text === null) return;
+    index.files.set(rel, { at: stat.mtimeMs, symbols: declarationsIn(rel, text) });
+  }));
+
+  for (const rel of [...index.files.keys()]) if (!seen.has(rel)) index.files.delete(rel);
+
+  const symbols = [];
+  for (const { symbols: s } of index.files.values()) symbols.push(...s);
+  return { symbols, fileCount: index.files.size };
+}
+
+/** Forget what was read, so the next lookup starts clean. */
+export function clearIndex() { indexes.clear(); }
+
+const KINDS = new Set(['function', 'class', 'type', 'component']);
+
+/**
+ * Where a name is declared. An exact match wins; failing that, anything
+ * containing it, so a half-remembered name still lands.
+ */
+export async function findSymbol({ name, kind, path: p = '.' }) {
+  const wanted = String(name ?? '').trim();
+  if (!wanted) {
+    return result('Pass the name of a function, component, class or type to look for.', 'nothing to look for');
+  }
+
+  const target = resolveIn(p || '.', 'find_symbol', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const { symbols, fileCount } = await buildIndex(target.abs);
+  const pool = kind && KINDS.has(kind) ? symbols.filter((s) => s.kind === kind) : symbols;
+
+  const lower = wanted.toLowerCase();
+  let hits = pool.filter((s) => s.name === wanted);
+  let how = 'exactly';
+  if (!hits.length) {
+    hits = pool.filter((s) => s.name.toLowerCase() === lower);
+    how = 'ignoring case';
+  }
+  if (!hits.length) {
+    hits = pool.filter((s) => s.name.toLowerCase().includes(lower));
+    how = 'containing';
+  }
+
+  if (!hits.length) {
+    return result(
+      `Nothing declared as "${wanted}" in ${target.show} (read ${fileCount} source files).\n` +
+      'It may be imported from a package, spelled differently, or built at runtime — grep will find uses.',
+      'not declared here'
+    );
+  }
+
+  hits.sort((a, b) => a.name.length - b.name.length || a.file.localeCompare(b.file));
+  const shown = hits.slice(0, 25);
+  const lines = shown.map((s) => {
+    const route = routeFor(s.file);
+    return `${s.file}:${s.line}  ${s.kind}  ${s.name}${route ? `  [route ${route}]` : ''}\n    ${s.text}`;
+  });
+
+  const more = hits.length > shown.length ? `\n[${hits.length - shown.length} more]` : '';
+  return result(
+    `Declared ${how} "${wanted}":\n\n${lines.join('\n')}${more}`,
+    `${hits.length} declaration${hits.length === 1 ? '' : 's'}`
+  );
+}
+
+/**
+ * What a file declares, and what a folder's files declare — the shape of the
+ * code without reading all of it.
+ */
+export async function outline({ path: p = '.' }) {
+  const target = resolveIn(p || '.', 'outline', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const stat = await fs.stat(target.abs).catch(() => null);
+  if (stat?.isFile()) {
+    const text = await fs.readFile(target.abs, 'utf8').catch(() => '');
+    const found = declarationsIn(target.show, text);
+    if (!found.length) return result(`${target.show} declares nothing this can see.`, 'nothing declared');
+    return result(
+      `${target.show}\n` + found.map((s) => `  ${s.line}: ${s.kind} ${s.name}`).join('\n'),
+      `${found.length} declaration${found.length === 1 ? '' : 's'}`
+    );
+  }
+
+  const { symbols, fileCount } = await buildIndex(target.abs);
+  if (!symbols.length) return result(`No declarations found under ${target.show}.`, 'nothing declared');
+
+  const byFile = new Map();
+  for (const s of symbols) {
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+  }
+
+  const files = [...byFile.keys()].sort();
+  const shown = files.slice(0, 60);
+  const body = shown.map((f) => {
+    const route = routeFor(f);
+    const names = byFile.get(f).map((s) => s.name).slice(0, 12).join(', ');
+    return `${f}${route ? `  [route ${route}]` : ''}\n  ${names}`;
+  });
+
+  const more = files.length > shown.length ? `\n[${files.length - shown.length} more files]` : '';
+  return result(
+    `${symbols.length} declarations across ${fileCount} files in ${target.show}:\n\n${body.join('\n')}${more}`,
+    `${symbols.length} declarations`
+  );
+}

package/src/tools/types.js

@@ -0,0 +1,179 @@
+/**
+ * types.js — asking the app's own TypeScript what something actually is.
+ *
+ * The model guesses at APIs. It writes `user.fullName` because that is what
+ * the property ought to be called, and finds out from a build forty seconds
+ * later that it is `displayName`. Every editor solves this by asking a
+ * language service, and the answer is already installed: the project's own
+ * TypeScript, the same version and the same tsconfig that its build uses.
+ *
+ * So this loads the project's typescript — never one of ours, which would
+ * answer for a different version of the language — and keeps a language
+ * service open on it. Asking is then a few milliseconds, and the answer is
+ * the one the build will give.
+ *
+ * A project without TypeScript installed gets a plain sentence saying so.
+ * Nothing is installed to make this work.
+ */
+
+import { promises as fs } from 'node:fs';
+import { statSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveIn, guard, result } from './shared.js';
+
+/** The nearest folder above `from` holding both a tsconfig and a typescript. */
+export function projectRootFor(from, root) {
+  let dir = path.resolve(from);
+  const stop = path.resolve(root);
+  for (;;) {
+    if (existsSync(path.join(dir, 'tsconfig.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir || !dir.startsWith(stop)) return null;
+    dir = up;
+  }
+}
+
+/** The project's own typescript, or null if it has none. */
+async function loadTypeScript(projectDir) {
+  let dir = projectDir;
+  for (;;) {
+    const entry = path.join(dir, 'node_modules', 'typescript', 'lib', 'typescript.js');
+    if (existsSync(entry)) {
+      const mod = await import(pathToFileURL(entry).href);
+      return mod.default ?? mod;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+const services = new Map(); // project dir -> { ts, service, versions }
+
+/**
+ * A language service for this project, made once and kept. Files are read
+ * from disk and their version is their modified time, so an edit made by the
+ * model is seen on the next question without rebuilding anything.
+ */
+async function serviceFor(projectDir) {
+  const had = services.get(projectDir);
+  if (had) return had;
+
+  const ts = await loadTypeScript(projectDir);
+  if (!ts) return null;
+
+  const configPath = path.join(projectDir, 'tsconfig.json');
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(read.config ?? {}, ts.sys, projectDir);
+
+  const versions = new Map();
+  const versionOf = (file) => {
+    try { return String(statSync(file).mtimeMs); } catch { return '0'; }
+  };
+
+  const host = {
+    getScriptFileNames: () => parsed.fileNames,
+    getScriptVersion: (file) => {
+      const now = versionOf(file);
+      versions.set(file, now);
+      return now;
+    },
+    getScriptSnapshot: (file) => {
+      try { return ts.ScriptSnapshot.fromString(readFileSync(file, 'utf8')); } catch { return undefined; }
+    },
+    getCurrentDirectory: () => projectDir,
+    getCompilationSettings: () => parsed.options,
+    getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+    fileExists: ts.sys.fileExists,
+    readFile: ts.sys.readFile,
+    readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists,
+    getDirectories: ts.sys.getDirectories,
+  };
+
+  const made = { ts, service: ts.createLanguageService(host, ts.createDocumentRegistry()), versions };
+  services.set(projectDir, made);
+  return made;
+}
+
+/** Forget the open services, so the next question starts fresh. */
+export function clearServices() { services.clear(); }
+
+/** Character offset of `symbol` used as a name, preferring a given line. */
+export function offsetOf(text, symbol, line) {
+  const re = new RegExp(`(?<![\\w$])${symbol.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}(?![\\w$])`, 'g');
+  const hits = [...text.matchAll(re)].map((m) => m.index);
+  if (!hits.length) return -1;
+  if (!line) return hits[0];
+  const lineStart = text.split('\n').slice(0, line - 1).join('\n').length;
+  // The occurrence nearest the line asked about.
+  return hits.reduce((best, at) =>
+    Math.abs(at - lineStart) < Math.abs(best - lineStart) ? at : best, hits[0]);
+}
+
+/**
+ * What TypeScript says a name is: its exact type or signature, the docs
+ * written on it, and where it is defined.
+ */
+export async function typeOf({ path: p, symbol, line }) {
+  const wanted = String(symbol ?? '').trim();
+  if (!wanted) return result('Pass the name of something in the file to ask about.', 'nothing to ask about');
+
+  const target = resolveIn(p, 'type_of', 'path');
+  await guard(target, `read ${target.abs}`);
+
+  const text = await fs.readFile(target.abs, 'utf8').catch(() => null);
+  if (text === null) return result(`Could not read ${target.show}.`, 'unreadable');
+
+  const projectDir = projectRootFor(path.dirname(target.abs), path.parse(target.abs).root);
+  if (!projectDir) {
+    return result(
+      `${target.show} is not inside a TypeScript project (no tsconfig.json above it), so there is ` +
+      'no type information to give. Read the file, or the package it comes from.',
+      'not a typescript project'
+    );
+  }
+
+  const made = await serviceFor(projectDir);
+  if (!made) {
+    return result(
+      `This project has no TypeScript installed, so nothing can answer what ${wanted} is. ` +
+      'Once its packages are installed, ask again.',
+      'typescript not installed'
+    );
+  }
+
+  const { ts, service } = made;
+  const at = offsetOf(text, wanted, line);
+  if (at < 0) {
+    return result(`"${wanted}" does not appear in ${target.show}.`, 'not in this file');
+  }
+
+  const info = service.getQuickInfoAtPosition(target.abs, at);
+  if (!info) {
+    return result(
+      `TypeScript has nothing to say about ${wanted} in ${target.show} — usually that means the file ` +
+      'has an error above this point, or the project has not been installed.',
+      'no type information'
+    );
+  }
+
+  const signature = ts.displayPartsToString(info.displayParts);
+  const docs = ts.displayPartsToString(info.documentation ?? []);
+
+  let where = '';
+  const defs = service.getDefinitionAtPosition(target.abs, at) ?? [];
+  if (defs.length) {
+    const d = defs[0];
+    const rel = path.relative(projectDir, d.fileName).replace(/\\/g, '/');
+    const body = readFileSync(d.fileName, 'utf8').slice(0, d.textSpan.start);
+    where = `\n\nDefined in ${rel}:${body.split('\n').length}`;
+  }
+
+  return result(
+    `${signature}${docs ? `\n\n${docs}` : ''}${where}\n\n` +
+    'This is from the project\'s own TypeScript, so it is what the build will say.',
+    signature.split('\n')[0].slice(0, 80)
+  );
+}

package/src/ui/activity.js

@@ -0,0 +1,203 @@
+/**
+ * activity.js — what the status row shows while ucode is working.
+ *
+ * A long turn is minutes of the agent doing things the user did not type and
+ * cannot see coming. The status row is the one place that says it is still
+ * going, so it has to look alive at a glance without asking to be read: a
+ * spinner that turns, a soft band of light passing across the label, the
+ * step count ticking up, and the time the turn has taken so far.
+ *
+ * Everything here is a pure function of the text and the clock, so it can be
+ * tested without a terminal and painted at any frame rate.
+ */
+
+import chalk, { Chalk } from 'chalk';
+import { dim, sky, theme, clip, SPINNER } from './theme.js';
+
+/** One painter per colour level, so a test can ask for truecolour on a pipe. */
+const painters = new Map();
+const painter = (level) => {
+  if (!painters.has(level)) painters.set(level, new Chalk({ level }));
+  return painters.get(level);
+};
+
+/** One frame every 85ms — just under twelve a second, smooth without being busy. */
+export const FRAME_MS = 85;
+
+/**
+ * A duration as a person says it: 0.4s, 14s, 2m 04s, 1h 07m.
+ *
+ * Seconds are zero-padded once there are minutes, so the text after the timer
+ * does not shift sideways every time the seconds roll from 9 to 10.
+ */
+export function formatDuration(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
+  const total = Math.floor(value / 1000);
+  if (total < 60) return `${total}s`;
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) return `${minutes}m ${String(total % 60).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+// ---------------------------------------------------------------------------
+// The shimmer
+// ---------------------------------------------------------------------------
+
+/**
+ * The two ends of the shimmer, both blue. The resting colour is muted enough
+ * to read as secondary text beside the model name; the peak is almost white,
+ * so the band reads as light passing over the words rather than a second
+ * colour arriving.
+ */
+const REST_RGB = [0x7a, 0x96, 0xc8];
+const PEAK_RGB = [0xe6, 0xf0, 0xff];
+
+/** Half the width of the band of light, in characters. */
+const BAND = 3;
+
+/** How fast the band travels, in characters a second. */
+const SPEED = 24;
+
+/** Characters' worth of dark between one pass and the next. */
+const PAUSE = 18;
+
+/** Brightness steps. Neighbouring letters that land on the same step share one escape code. */
+const STEPS = 8;
+
+const mix = (a, b, k) => a.map((v, i) => Math.round(v + (b[i] - v) * k));
+
+/**
+ * The text with a soft band of light passing across it, left to right, then a
+ * short rest, then again.
+ *
+ * `t` is milliseconds on any clock; the band's position is a function of it,
+ * so a slow frame skips ahead rather than slowing the sweep down.
+ *
+ * Needs 256 colours or more. With 16 there are no in-between blues to fade
+ * through, and a band that jumps between two colours reads as flicker rather
+ * than light — so below that the label is simply dim, and never moves.
+ */
+export function shimmer(text, t, { level = chalk.level } = {}) {
+  const s = String(text ?? '');
+  if (!s || level < 2) return dim(s);
+
+  const cycle = s.length + BAND * 2 + PAUSE;
+  const centre = ((Math.max(0, t) / 1000) * SPEED) % cycle - BAND;
+
+  let out = '';
+  let run = '';
+  let runStep = -1;
+  const flush = () => {
+    if (!run) return;
+    const [r, g, b] = mix(REST_RGB, PEAK_RGB, runStep / STEPS);
+    out += painter(level).rgb(r, g, b)(run);
+    run = '';
+  };
+
+  for (let i = 0; i < s.length; i++) {
+    const distance = Math.abs(i - centre);
+    // A cosine falloff: brightest at the centre, fading smoothly to nothing
+    // at the edge of the band, so the light has no hard edge to it.
+    const k = distance < BAND ? (Math.cos((Math.PI * distance) / BAND) + 1) / 2 : 0;
+    const step = Math.round(k * STEPS);
+    if (step !== runStep) { flush(); runStep = step; }
+    run += s[i];
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The spinner glyph for a frame, breathing slowly between two blues.
+ *
+ * The pulse is slow — a little over a second a breath — so it reads as the
+ * glyph being alive rather than as a blink.
+ */
+export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
+  const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
+  if (level < 2) return theme.blue(glyph);
+  const k = (Math.sin((Math.max(0, t) / 1300) * Math.PI * 2) + 1) / 2;
+  const [r, g, b] = mix([0x4d, 0x8d, 0xff], [0x9f, 0xc6, 0xff], k);
+  return painter(level).rgb(r, g, b)(glyph);
+}
+
+// ---------------------------------------------------------------------------
+// Fitting it into the room there is
+// ---------------------------------------------------------------------------
+
+/** Shorter than this, a label is a stub that says nothing, so it goes entirely. */
+const MIN_LABEL = 10;
+
+/**
+ * The middle of the status row, fitted to `room` columns.
+ *
+ * Parts, in the order they are given up when the terminal is too narrow for
+ * all of them:
+ *
+ *   1. the "esc to stop" hint     — useful once, known after that
+ *   2. the end of the label        — clipped with an ellipsis, down to a stub
+ *   3. the step count
+ *   4. the label itself
+ *   5. the elapsed time
+ *
+ * The spinner is the last thing standing: even with a single column left the
+ * row still shows that something is happening.
+ *
+ * `meta` is a list of { text, paint, keep } — keep marks the one that survives
+ * the longest (the timer). `paint` colours the label, which is where the
+ * shimmer comes in.
+ */
+export function fitActivity({ glyph, label = '', meta = [], hint = '', paint = dim }, room) {
+  if (room < 1) return '';
+  const items = meta.filter((m) => m && m.text);
+  const kept = items.filter((m) => m.keep);
+  const text = String(label ?? '');
+
+  const width = (labelLen, list, withHint) =>
+    1 +
+    (labelLen ? 1 + labelLen : 0) +
+    (list.length ? (labelLen ? 3 : 1) + list.map((m) => m.text).join(' · ').length : 0) +
+    (withHint && hint ? 2 + hint.length : 0);
+
+  const build = (labelText, list, withHint) => {
+    let out = glyph;
+    if (labelText) out += ` ${paint(labelText)}`;
+    if (list.length) {
+      out += labelText ? dim(' · ') : ' ';
+      out += list.map((m) => (m.paint ?? dim)(m.text)).join(dim(' · '));
+    }
+    if (withHint && hint) out += `  ${dim(hint)}`;
+    return out;
+  };
+
+  if (text) {
+    if (width(text.length, items, true) <= room) return build(text, items, true);
+    if (width(text.length, items, false) <= room) return build(text, items, false);
+    for (const list of [items, kept]) {
+      const labelRoom = room - width(0, list, false) - 1 - (list.length ? 2 : 0);
+      if (labelRoom >= MIN_LABEL) return build(clip(text, labelRoom), list, false);
+    }
+  }
+  for (const list of [items, kept, []]) {
+    if (width(0, list, false) <= room) return build('', list, false);
+  }
+  return glyph;
+}
+
+/**
+ * The line a finished turn leaves in the transcript: "✓ Done in 6m 12s · 25 steps".
+ *
+ * Green for the tick, because green means done and nothing else in this
+ * theme; the rest dim, because it is a footnote to the answer above it rather
+ * than something to read first.
+ */
+export function doneLine(ms, steps) {
+  const count = steps > 0 ? ` · ${steps} step${steps === 1 ? '' : 's'}` : '';
+  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}${count}`)}`;
+}
+
+/** The step count, brighter for a moment right after it goes up. */
+export function stepPaint(justMoved) {
+  return justMoved ? sky : dim;
+}

package/src/ui/plain.js

@@ -15,6 +15,7 @@ import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
   BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine,
 } from './theme.js';
+import { formatDuration, doneLine } from './activity.js';
 import { renderer, render } from './markdown.js';
 
 const COMMANDS = [
@@ -227,9 +228,11 @@ export class Plain {
   }
 
   paintSpinner() {
-    const secs = Math.round((Date.now() - this.since) / 1000);
-    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` +
-      (secs >= 2 ? dim(` ${secs}s`) : '');
+    const since = this.turn?.start ?? this.since;
+    const secs = Math.round((Date.now() - since) / 1000);
+    const meta = [this.turn?.steps ? `step ${this.turn.steps}` : '', secs >= 2 ? formatDuration(secs * 1000) : '']
+      .filter(Boolean).join(' · ');
+    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` + (meta ? dim(` · ${meta}`) : '');
     this.output.write(`\r\x1b[K${padVis(line, this.width() - 1)}`);
   }
 
@@ -246,6 +249,22 @@ export class Plain {
     this.output.write('\r\x1b[K');
   }
 
+  // -- the turn in flight ----------------------------------------------------
+
+  turnStart() {
+    this.turn = { start: Date.now(), steps: 0 };
+  }
+
+  step() {
+    if (this.turn) this.turn.steps++;
+  }
+
+  turnEnd({ ok = true } = {}) {
+    const t = this.turn;
+    this.turn = null;
+    if (t && ok && Date.now() - t.start >= 2000) this.write(`  ${doneLine(Date.now() - t.start, t.steps)}`);
+  }
+
   // -- input ---------------------------------------------------------------
 
   nextLine() {