@semalt-ai/code 1.8.5 → 1.20.0

package/lib/ui/create-ui.js

@@ -5,8 +5,15 @@ const readline = require('readline');
 const { RST, FG_YELLOW, FG_CYAN, FG_GRAY } = require('./ansi');
 const { ChatHistory } = require('./chat-history');
 const writer = require('./writer');
+const { getCols } = require('./utils');
+const { wrapPromptLines } = require('./format');
 const { registerTerminalCleanup } = require('./terminal');
 
+// Cap a long ask_user question to this many wrapped lines in the modal header
+// (mirrors the permission picker's MAX_DESC_LINES in permissions.js) so it can
+// never overflow the live modal band; the rest collapses to "… N more lines".
+const MAX_PROMPT_LINES = 12;
+
 function _createNoOpUI() {
   const chatHistory = {
     addMessage: (msg) => {
@@ -19,6 +26,10 @@ function _createNoOpUI() {
     clearStreamingContent: () => {},
     finalizeLastMessage: () => {},
     clearMessages: () => {},
+    // Phase 7b — no live region in the non-TTY no-op UI, so the deferred detail
+    // band is inert; the output preview just never displays. Present so the
+    // chat-turn boundary calls are safe in a non-TTY interactive run.
+    deferToolOutput: () => {}, commitDeferredDetail: () => {},
     scrollUp: () => {}, scrollDown: () => {},
     rerenderById: () => {},
     removeById: () => {},
@@ -62,7 +73,6 @@ function createUI(opts) {
   const { LayoutManager } = require('./layout');
   const { FullStatusBar } = require('./status-bar');
   const { InputField } = require('./input-field');
-  const { interactiveSelect } = require('./select');
 
   const layout = new LayoutManager();
   const chatHistory = new ChatHistory();
@@ -153,34 +163,67 @@ function createUI(opts) {
 
   // ── captureSelect (modal menu) ───────────────────────────────────────────────
   //
-  // Numbered-options picker for tools like ask_user. interactiveSelect
-  // renders each frame into the writer's modal region (above status,
-  // below scrollback) and routes keys through the input field's
-  // captureNavigation API — so the menu cohabits with the live region
-  // instead of taking over the screen, and Enter/Esc resolve in place.
+  // ask_user-PRIVATE numbered-options picker (the model/rewind/permission
+  // pickers call interactiveSelect directly — this wrapper is NOT on that path).
+  // It manages its OWN modal frame (mirroring permissions.js requestPermission)
+  // rather than going through interactiveSelect, because it prepends the QUESTION
+  // as NON-SELECTABLE header rows above the options: navigation only ever cycles
+  // the options, so the prompt rows can never be landed on or returned. The frame
+  // redraws in place in the writer's modal region (above status, below
+  // scrollback) and keys route through the input field's captureNavigation API,
+  // so the menu cohabits with the live region instead of taking over the screen.
+  //
+  // `menu` = { prompt, options }. `prompt` (the question prose, already stripped
+  // of the numbered options by the executor) is word-wrapped to terminal width
+  // and clamped to MAX_PROMPT_LINES so a long question can't overflow the band.
   inputField.captureSelect = (menu) => new Promise((resolve) => {
+    const options = (menu && Array.isArray(menu.options)) ? menu.options : [];
     if (!process.stdin.isTTY) {
-      resolve(menu.options[0]);
+      resolve(options[0]);
       return;
     }
-    interactiveSelect(
-      menu.options,
-      (opt, isSelected) => isSelected
-        ? `  ${FG_YELLOW}❯${RST} ${FG_CYAN}${opt}${RST}`
-        : `   ${FG_GRAY}${opt}${RST}`,
-      {
-        initialIndex: 0,
-        onExpand: () => chatHistory.toggleLastExpand(),
-        captureNavigation: (handler) => {
-          inputField.captureNavigation(handler);
-          return () => inputField.releaseNavigation();
-        },
+    if (options.length === 0) {
+      resolve(null);
+      return;
+    }
+
+    // Wrap + clamp the question into non-selectable header rows.
+    const promptLines = wrapPromptLines(menu && menu.prompt, {
+      cols: Math.max(20, getCols() - 4),
+      maxLines: MAX_PROMPT_LINES,
+    });
+
+    let idx = 0;
+    const buildLines = () => {
+      const lines = [];
+      for (const p of promptLines) lines.push(`  ${FG_GRAY}${p}${RST}`);
+      if (promptLines.length) lines.push('');
+      for (let i = 0; i < options.length; i++) {
+        lines.push(i === idx
+          ? `  ${FG_YELLOW}❯${RST} ${FG_CYAN}${options[i]}${RST}`
+          : `   ${FG_GRAY}${options[i]}${RST}`);
+      }
+      return lines;
+    };
+
+    writer.setModal(buildLines());
+    inputField.captureNavigation((action) => {
+      if (action === 'prev') {
+        idx = (idx - 1 + options.length) % options.length;
+        writer.setModal(buildLines());
+      } else if (action === 'next') {
+        idx = (idx + 1) % options.length;
+        writer.setModal(buildLines());
+      } else if (action === 'select' || action === 'cancel') {
+        // Order matters (mirrors interactiveSelect): clearModal first while the
+        // caret is still suppressed, then releaseNavigation so the host's render
+        // hooks restore the input caret on the next setLive frame.
+        writer.clearModal();
+        inputField.releaseNavigation();
+        // Cancel → last option (typically "No"/decline) so callers don't need to
+        // special-case cancellation — matches the prior contract.
+        resolve(action === 'select' ? options[idx] : options[options.length - 1]);
       }
-    ).then((idx) => {
-      // Cancel returns null. Match the prior contract: pick the last
-      // option (typically "No"/decline) so callers don't need to
-      // special-case cancellation.
-      resolve(idx === null ? menu.options[menu.options.length - 1] : menu.options[idx]);
     });
   });
 

package/lib/ui/diff.js

@@ -1,8 +1,8 @@
 'use strict';
 
-const { FG_DARK, FG_RED, FG_GREEN, FG_GRAY, FG_YELLOW, FG_TEAL, RST, THEME, EL, hasTruecolor } = require('./ansi');
+const { RST, EL, hasTruecolor } = require('./ansi');
 const { getCols, stripAnsi, termWidth } = require('./utils');
-const { DIFF_THEME, UI_THEME } = require('./theme');
+const { DIFF_THEME, UI_THEME, THEME, FG_CODE_LANG, colorEnabled } = require('./theme');
 const writer = require('./writer');
 
 function diffLines(oldLines, newLines) {
@@ -67,7 +67,9 @@ function renderDiff(oldText, newText, filePath, opts) {
   // Resolve the palette once per render. Truecolor is used when the terminal
   // advertises it via COLORTERM; otherwise fall back to 256-color.
   const useTC = hasTruecolor();
-  const a   = (code) => isTTY ? code : '';
+  // Strip colour for non-TTY AND NO_COLOR (colorEnabled folds in both); the
+  // diff body then renders as plain text with no ANSI leaking into piped output.
+  const a   = (code) => colorEnabled() ? code : '';
   const R   = a(RST);
   const EL_ = a(EL);
   const pickBg = (t) => useTC && t.bgTC ? t.bgTC : t.bg256;
@@ -77,7 +79,7 @@ function renderDiff(oldText, newText, filePath, opts) {
     context: { bg: '',                             signFg: '',                            sign: DIFF_THEME.context.sign },
     ln:      a(DIFF_THEME.lineNumber),
     code:    a(DIFF_THEME.code),
-    hdr:     a(DIFF_THEME.header),
+    // (P.hdr removed in Phase 2 D3 — the diff no longer emits a path header.)
     frame:   a(DIFF_THEME.frame),
   };
 
@@ -85,7 +87,7 @@ function renderDiff(oldText, newText, filePath, opts) {
   const newLines  = newText.split('\n');
   const isNewFile = oldText === '';
 
-  let diff;
+  let diff = null;
   if (!isNewFile) {
     diff = (oldLines.length > 200 || newLines.length > 200)
       ? diffLinesHashed(oldLines, newLines) : diffLines(oldLines, newLines);
@@ -129,27 +131,67 @@ function renderDiff(oldText, newText, filePath, opts) {
     return `${GUTTER}${P.frame}${label}${R}`;
   }
 
-  const out = [];
-  // Minimal file header — bold blue path, no box. The surrounding UI owns
-  // any tool-label framing; this line is the only header the diff emits.
-  out.push(`${GUTTER}${P.hdr}${filePath}${R}`);
-
+  // Flatten the change into per-line entries with line numbers resolved. Both
+  // the full hunk renderer and the capped head+tail renderer consume this. A
+  // new file is every-line-added; an existing file annotates the LCS diff.
+  let annotated;
   if (isNewFile) {
-    // Meta-label "(new file)" rendered in the shared subtle palette so it
-    // recedes relative to the hunk marker itself.
-    const subtle = a(UI_THEME.subtle);
-    out.push(`${GUTTER}${P.frame}@@ -0,0 +1,${newLines.length} @@ ${R}${subtle}(new file)${R}`);
-    let ln = 1;
-    for (const line of newLines) out.push(makeLine(String(ln++), 'added', line));
+    annotated = newLines.map((text, i) => ({ type: 'add', text, oldLine: null, newLine: i + 1 }));
   } else {
     let oldLn = 1, newLn = 1;
-    const annotated = diff.map((d) => {
+    annotated = diff.map((d) => {
       const e = { type: d.type, text: d.text, oldLine: null, newLine: null };
       if (d.type !== 'add') e.oldLine = oldLn++;
       if (d.type !== 'del') e.newLine = newLn++;
       return e;
     });
+  }
+
+  const renderEntry = (e) => {
+    if (e.type === 'del') return makeLine(String(e.oldLine), 'removed', e.text);
+    if (e.type === 'add') return makeLine(String(e.newLine), 'added',   e.text);
+    return makeLine(String(e.newLine), 'context', e.text);
+  };
+
+  // Capped path (execution-time diffs). When the caller passes a positive
+  // `maxLines` and the edit touches MORE changed (+/-) lines than that, show the
+  // first DIFF_HEAD_RATIO of the budget and the last (1-ratio), eliding the
+  // middle with a `… K more changed lines (N total)` notice — mirroring the W.6
+  // shell head+tail discipline. A small edit (or a series of small edits, each
+  // short) never trips this: it renders in full via the hunk path below.
+  const DIFF_HEAD_RATIO = 0.6;
+  const maxLines = (opts && Number.isInteger(opts.maxLines) && opts.maxLines > 0) ? opts.maxLines : 0;
+  if (maxLines) {
+    const changed = annotated.filter((e) => e.type !== 'same');
+    if (changed.length > maxLines) {
+      const head   = Math.max(1, Math.round(maxLines * DIFF_HEAD_RATIO));
+      const tail   = Math.max(1, maxLines - head);
+      const elided = changed.length - head - tail;
+      // D3 (Phase 2): no path header — the result line above already states the
+      // path. The body opens directly with the first changed line.
+      const capped = [];
+      for (let k = 0; k < head; k++) capped.push(renderEntry(changed[k]));
+      capped.push(isTTY
+        ? `${GUTTER}${P.frame}… ${elided} more changed lines (${changed.length} total)${R}`
+        : `… ${elided} more changed lines (${changed.length} total)`);
+      for (let k = changed.length - tail; k < changed.length; k++) capped.push(renderEntry(changed[k]));
+      return capped.join('\n');
+    }
+  }
 
+  const out = [];
+  // D3 (Phase 2): the diff no longer emits a path header — the result line
+  // above already states the path (the descriptor's `target`), so restating it
+  // here was pure duplication. The body opens with the @@ hunk ranges (and the
+  // "(new file)" marker for a new file), which carry information the path does not.
+
+  if (isNewFile) {
+    // Meta-label "(new file)" rendered in the shared subtle palette so it
+    // recedes relative to the hunk marker itself.
+    const subtle = a(UI_THEME.subtle);
+    out.push(`${GUTTER}${P.frame}@@ -0,0 +1,${newLines.length} @@ ${R}${subtle}(new file)${R}`);
+    for (const e of annotated) out.push(makeLine(String(e.newLine), 'added', e.text));
+  } else {
     const changedIdx = [];
     annotated.forEach((d, i) => { if (d.type !== 'same') changedIdx.push(i); });
 
@@ -172,11 +214,7 @@ function renderDiff(oldText, newText, filePath, opts) {
       const newCnt   = hunk.filter((e) => e.newLine !== null).length;
       out.push(hunkSep(`@@ -${oldStart},${oldCnt} +${newStart},${newCnt} @@`));
 
-      for (const e of hunk) {
-        if (e.type === 'del')      out.push(makeLine(String(e.oldLine), 'removed', e.text));
-        else if (e.type === 'add') out.push(makeLine(String(e.newLine), 'added',   e.text));
-        else                       out.push(makeLine(String(e.newLine), 'context', e.text));
-      }
+      for (const e of hunk) out.push(renderEntry(e));
     }
   }
 
@@ -192,11 +230,38 @@ function renderDiff(oldText, newText, filePath, opts) {
   return out.join('\n');
 }
 
+// Execution-time file-edit diff. This is the SINGLE rendering site for the full
+// diff of a mutating edit (write/append/edit_file/replace_in_file): the agent
+// loop calls it from onToolEnd after the edit executes, so the diff renders for
+// EVERY edit regardless of approval state (manual-approved, auto-approved) or
+// entry mode (fresh / --resume / /history / /chats). The permission modal no
+// longer carries the full diff, so the user sees it exactly once, here.
+//
+// `payload` carries { before, after, path } captured by the executor; `maxLines`
+// is config.diff_max_lines (the changed-line cap). Returns the rendered diff
+// string, or null when there is nothing to show — a failed edit (`error`), a
+// missing/ malformed payload (e.g. a loaded-history turn, which never carries
+// one, so past turns are NOT replayed), or a no-op edit.
+function buildExecutionDiff(opts) {
+  const o = opts || {};
+  if (o.error) return null;
+  const p = o.diff;
+  if (!p || typeof p.before !== 'string' || typeof p.after !== 'string') return null;
+  if (p.before === p.after) return null;
+  const renderOpts = {
+    maxLines: (Number.isInteger(o.maxLines) && o.maxLines > 0) ? o.maxLines : 50,
+  };
+  if (Number.isInteger(o.inset) && o.inset >= 0) renderOpts.inset = o.inset;
+  const rendered = renderDiff(p.before, p.after, p.path || '', renderOpts);
+  if (!rendered || rendered === '   No changes detected') return null;
+  return rendered;
+}
+
 function _mdInline(text) {
   let out = '', i = 0;
   while (i < text.length) {
     const c = text[i], c1 = i + 1 < text.length ? text[i+1] : '';
-    if (c === '`') { const end = text.indexOf('`', i+1); if (end !== -1) { out += '\x1b[7m' + text.slice(i+1, end) + '\x1b[27m'; i = end+1; continue; } }
+    if (c === '`') { const end = text.indexOf('`', i+1); if (end !== -1) { out += FG_CODE_LANG + text.slice(i+1, end) + '\x1b[39m'; i = end+1; continue; } }
     if (c === '*' && c1 === '*') { const end = text.indexOf('**', i+2); if (end !== -1) { out += '\x1b[1m' + text.slice(i+2, end) + '\x1b[22m'; i = end+2; continue; } }
     if (c === '_' && c1 === '_') { const end = text.indexOf('__', i+2); if (end !== -1) { out += '\x1b[1m' + text.slice(i+2, end) + '\x1b[22m'; i = end+2; continue; } }
     if (c === '*' && c1 !== '*') { let end = -1; for (let j = i+1; j < text.length; j++) { if (text[j] === '*' && (j+1 >= text.length || text[j+1] !== '*')) { end = j; break; } } if (end !== -1) { out += '\x1b[3m' + text.slice(i+1, end) + '\x1b[23m'; i = end+1; continue; } }
@@ -225,7 +290,7 @@ function renderMarkdown(text) {
     if (inCode) {
       const t = line.trim();
       if (t.length === 3 && t[0] === '`' && t[1] === '`' && t[2] === '`') { output.push('└' + '─'.repeat(Math.max(1, cols - 2))); inCode = false; }
-      else { output.push('│  ' + THEME.dim + line + THEME.reset); }
+      else { output.push('│  ' + line); }
       continue;
     }
     const trimmed = line.trim();
@@ -253,4 +318,4 @@ function renderMarkdown(text) {
   if (overflow > 0) writer.scrollback(THEME.dim + '[... ' + overflow + ' more lines]' + THEME.reset);
 }
 
-module.exports = { renderDiff, renderMarkdown, _mdInline };
+module.exports = { renderDiff, buildExecutionDiff, renderMarkdown, _mdInline, _truncateByWidth };

package/lib/ui/file-activity.js

@@ -0,0 +1,236 @@
+'use strict';
+
+// File-activity process summary (a SECOND INSTANCE of the web-activity pattern).
+//
+// A warm-up phase of an agent turn often fires a long run of pure file reads
+// (read_file) or directory listings (list_dir) back-to-back. By default each
+// committed its own tool line ("✓ file · read index.html", "✓ file · read
+// battlecity.js", …), flooding scrollback with one row per op. This module
+// collapses a run of CONSECUTIVE same-type file ops into a SINGLE compact
+// process-summary line —
+//
+//     ✓ file · read ×10 (index.html, battlecity.js, …)
+//
+// — exactly the way `web-activity.js` collapses web_search/http_get. It is a
+// parallel, independent instance of `createWebActivityTracker`; the web tracker
+// is untouched.
+//
+// Scope (deliberately narrow — DECISION 3): ONLY `read_file` + `list_dir`. Both
+// are pure reads with no diff and no output preview (their descriptors carry
+// `detail: null`), so grouping them sidesteps the deferred-detail-band ordering.
+// Other file tools keep their own per-op line.
+//
+// Two DIVERGENCES from the web tracker, both required by the append-only
+// scrollback model:
+//   • GROUP KEY = a single shared key for BOTH read_file and list_dir, so a
+//     mixed read/list exploration phase collapses into ONE summary instead of
+//     fragmenting on every read↔list switch. A homogeneous run keeps its specific
+//     verb ("read ×N" / "list ×N"); a genuinely mixed run uses the neutral "file
+//     ×N". Any OTHER tool still breaks the run. The web tracker has a single key.
+//   • THRESHOLD decided at flush time. A group of 1–2 ops commits each op as its
+//     own normal result line (byte-identical to today); a group of 3+ commits ONE
+//     summary line. The web tracker always collapses. We can't retroactively pull
+//     already-committed lines into a group, so ALL commits defer to flush() where
+//     the final count is known.
+
+const { UI_ICONS, resolveLineColors } = require('./theme');
+const { RST, DIM } = require('./ansi');
+const { getCols, termWidth, stripAnsi } = require('./utils');
+const { truncateLine } = require('./format');
+const { renderOperation } = require('./render-operation');
+const { isWebCore } = require('./web-activity');
+
+// Below this many ops in a group, commit individual per-op lines (today's
+// output); at or above it, commit ONE collapsed summary line.
+const GROUP_THRESHOLD = 3;
+
+// Native and XML rails BOTH emit `read` as the action for a read_file call
+// (tool_registry: read_file fromParams/_parseReadTag → ['read', …]); list_dir
+// stays `list_dir`. Normalize so the action tag and the registry tag name agree
+// — mirrors format.js / theme.js ACTION_TO_TAG, scoped to the groupable set.
+const ACTION_TO_TAG = { read: 'read_file' };
+
+function normalizeFileTag(tag) {
+  return ACTION_TO_TAG[tag] || tag || '';
+}
+
+// The tools collapsed into the file-activity summary (DECISION 3).
+const FILE_GROUP_TAGS = new Set(['read_file', 'list_dir']);
+
+function isGroupableFileTag(tag) {
+  return FILE_GROUP_TAGS.has(normalizeFileTag(tag));
+}
+
+// Group key. read_file and list_dir share ONE key (`file:access`) so consecutive
+// reads and lists accumulate into a SINGLE group regardless of order — they no
+// longer flush each other on a read↔list switch. (Any non-groupable tag keeps a
+// per-tag key, but in practice only groupable tags ever reach this — the caller
+// gates on isGroupable.)
+function fileGroupKey(tag) {
+  return isGroupableFileTag(tag) ? 'file:access' : `file:${normalizeFileTag(tag)}`;
+}
+
+// Final path segment, for the compact basename list. Trailing slashes (a dir
+// path) are stripped first so `/a/b/` → `b`; `.` and bare names pass through.
+function _basename(p) {
+  const s = String(p == null ? '' : p).replace(/[/\\]+$/, '');
+  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
+  const base = i >= 0 ? s.slice(i + 1) : s;
+  return base || s || '.';
+}
+
+// Pure: fold a list of file ops (ToolOperation descriptors OR persisted cores —
+// both expose `tag`/`target`) into the fields the summary needs. read_file and
+// list_dir now share one group, so a group may be MIXED. The verb reflects the
+// group's composition: homogeneous reads → "read"/"reading…", homogeneous lists
+// → "list"/"listing…", a genuinely mixed group → the neutral "file"/"accessing…".
+function fileSummaryState(ops) {
+  const list = (ops || []).filter(Boolean);
+  let hasRead = false, hasList = false;
+  for (const o of list) {
+    if (normalizeFileTag(o.tag) === 'list_dir') hasList = true;
+    else hasRead = true;
+  }
+  const mixed = hasRead && hasList;
+  const isList = hasList && !hasRead;
+  return {
+    verb: mixed ? 'file' : (isList ? 'list' : 'read'),
+    gerund: mixed ? 'accessing…' : (isList ? 'listing…' : 'reading…'),
+    count: list.length,
+    basenames: list.map((o) => _basename(o.target)),
+  };
+}
+
+// Styled, chrome-consistent summary line. Mirrors `formatWebSummaryLine`'s
+// "<glyph> <category> · <operation>" layout so the file summary reads as a peer
+// of the other tool lines. The ×N count sits in the FIXED prefix BEFORE the
+// truncatable basename list, so it ALWAYS shows even when the basenames are cut
+// to fit. One physical row (the Phase-4 single-row invariant): the basename list
+// is truncated to the remaining columns at the CURRENT terminal width.
+function formatFileSummaryLine(state, opts) {
+  const { pending = false } = opts || {};
+  const colors = resolveLineColors('file', pending ? 'pending' : 'success');
+  const glyph = pending ? UI_ICONS.pending : UI_ICONS.success;
+  const cat = 'file'.padEnd(5);
+  const sep = ` ${DIM}·${RST} `;
+
+  const head = `  ${colors.glyph}${glyph}${RST} ${colors.label}${cat}${RST}`;
+  const verb = pending ? state.gerund : state.verb;
+  const fixed = `${verb} ×${state.count} (`;
+
+  // Width budget for the basename list: total columns minus the styled prefix
+  // (measured plain), the fixed "verb ×N (" lead, and the trailing ")".
+  const cols = getCols();
+  const used = termWidth(stripAnsi(head)) + termWidth(stripAnsi(sep)) + termWidth(fixed) + 1;
+  const budget = cols - used;
+  const joined = state.basenames.join(', ');
+  const list = budget > 0 ? truncateLine(joined, budget) : '…';
+
+  const opSeg = `${colors.op}${fixed}${list})${RST}`;
+  return [head, opSeg].join(sep);
+}
+
+// Predicate: a persisted display core is a GROUPABLE file-op core (a normal
+// descriptor core for a successful read_file/list_dir). Replay buffers these and
+// re-groups them at the same boundaries the live path flushes. A web core or a
+// non-file / errored / unknown core fails the gate. Tolerant of any input.
+function isGroupableFileCore(core) {
+  if (!core || typeof core !== 'object' || core.v !== 1) return false;
+  if (isWebCore(core)) return false;
+  if (core.status && core.status !== 'ok') return false;
+  return isGroupableFileTag(core.tag);
+}
+
+// Stateful runtime collapser. Owns one writer "activity" entry per group of
+// consecutive same-key file ops, updating it in place as ops complete and
+// committing on flush(): a single summary line (≥3 ops) or the individual per-op
+// lines (1–2 ops). Tools run sequentially in the agent loop, so at most one group
+// is ever open and there is no concurrency. A SECOND INSTANCE of the web tracker.
+function createFileActivityTracker(deps) {
+  const { writerModule } = deps || {};
+  let groupId = null;
+  let seq = 0;
+  let currentKey = null;
+  let ended = [];      // successful op descriptors committed into this group
+  let current = null;  // the in-flight op, shown in the live aggregate line
+
+  function _render() {
+    const ops = current ? ended.concat([current]) : ended;
+    return formatFileSummaryLine(fileSummaryState(ops), { pending: true });
+  }
+
+  function _refresh() {
+    if (groupId === null) return;
+    writerModule.updateActivity(groupId, () => _render());
+  }
+
+  const api = {
+    isGroupable: isGroupableFileTag,
+    isOpen() { return groupId !== null; },
+
+    // Open or extend the live group for a starting op. read_file and list_dir
+    // share one key, so a read↔list switch does NOT flush — both accumulate into
+    // the same group (the key only changes for a different category, which never
+    // reaches here). The live row is a growing web-style aggregate: "● file ·
+    // reading… ×N (a, b, …)" (or "accessing… ×N" once mixed). `input` is the op's
+    // path (used for the live basename).
+    start(tag, input) {
+      const key = fileGroupKey(tag);
+      if (groupId !== null && key !== currentKey) api.flush();
+      current = { tag, target: input };
+      if (groupId === null) {
+        currentKey = key;
+        groupId = `file-${seq++}`;
+        writerModule.startActivity(groupId, () => _render());
+      } else {
+        _refresh();
+      }
+    },
+
+    // Record a SUCCESSFUL op (a prebuilt ToolOperation descriptor) into the group
+    // and re-render the live aggregate. Errored ops are NOT routed here (the
+    // caller flushes the group and renders the error standalone).
+    end(operation) {
+      ended.push(operation);
+      current = null;
+      _refresh();
+    },
+
+    // Commit the group to scrollback and reset. THRESHOLD decided here: <3 ops →
+    // each as its own normal result line (byte-identical to today's per-op
+    // output); ≥3 → one collapsed summary line. Exactly one endActivity call, so
+    // the commit happens once; a no-op when no group is open (the double-flush
+    // guard the boundary+finally flush sites rely on).
+    flush() {
+      if (groupId === null) return;
+      const id = groupId;
+      const ops = ended;
+      groupId = null;
+      currentKey = null;
+      ended = [];
+      current = null;
+      let line = '';
+      if (ops.length >= GROUP_THRESHOLD) {
+        line = formatFileSummaryLine(fileSummaryState(ops), { pending: false });
+      } else {
+        line = ops
+          .map((op) => renderOperation(op, { mode: 'ansi', phase: 'result' }))
+          .join('\n');
+      }
+      writerModule.endActivity(id, line);
+    },
+  };
+  return api;
+}
+
+module.exports = {
+  GROUP_THRESHOLD,
+  FILE_GROUP_TAGS,
+  normalizeFileTag,
+  isGroupableFileTag,
+  fileGroupKey,
+  fileSummaryState,
+  formatFileSummaryLine,
+  isGroupableFileCore,
+  createFileActivityTracker,
+};