mixdog 1.2.4 → 1.2.6

package/src/runtime/agent/orchestrator/tools/builtin/lib/list-helpers.mjs

@@ -4,6 +4,7 @@ import { normalizeErrorMessage } from '../path-diagnostics.mjs';
 import { isBinaryBuffer } from '../binary-file.mjs';
 import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component } from '../device-paths.mjs';
 import { normalizeOutputPath, resolveAgainstCwd } from '../path-utils.mjs';
+import { windowMarker } from '../tool-output-limit.mjs';
 
 /** Report the requested path's result; suggestions never retarget the operation. */
 export async function readFamilyPathEnoentOrError(workDir, fullPath, inputPath, err) {
@@ -52,8 +53,23 @@ export function guardedWalkRoot(inputPath, workDir) {
   return { fullPath };
 }
 
+// Code-unit path order: the tiebreak that makes a size/mtime sort total, so
+// equal keys cannot reorder with the walk (and shift across offset pages).
+export function comparePathsStable(a, b) {
+  const x = String(a);
+  const y = String(b);
+  if (x === y) return 0;
+  return x < y ? -1 : 1;
+}
+
 export function pageContinuationLine(offset, shown, total) {
-  return `... [entries ${offset + 1}-${offset + shown} of ${total}; pass offset:${offset + shown} to continue]`;
+  return windowMarker({
+    unit: 'entries',
+    from: offset + 1,
+    to: offset + shown,
+    total,
+    nextOffset: offset + shown,
+  });
 }
 
 const LINE_COUNT_MAX_BYTES = 2 * 1024 * 1024;

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-delivery.mjs

@@ -0,0 +1,199 @@
+// One shape for every piece of shell output handed to an agent — a foreground
+// result, a background move, task wait/read and a completion notice:
+//   1. ANSI stripped, then `\r` progress frames folded to their last frame
+//      (before anything is counted or cut);
+//   2. a line longer than DELIVERY_LINE_MAX_CHARS is cut: `… [N chars cut]`;
+//   3. DELIVERY_FULL_CHARS or less goes whole; otherwise a head of at most
+//      DELIVERY_HEAD_LINES lines (≤ DELIVERY_HEAD_MAX_CHARS), the marker, and
+//      the last ~DELIVERY_TAIL_CHARS;
+//   4. the marker is the same everywhere and always ends with the full log:
+//      `[… N lines, X KB omitted — read with offset/limit or grep, full log: <path>]`;
+//   5. anything shaped like a harness/system tag is escaped.
+// MIXDOG_SHELL_DELIVERY_MAX_CHARS is the one knob (the whole-delivery cap); the
+// head and tail sizes are fixed. It is separate from the 50 KB
+// MIXDOG_TOOL_OUTPUT_MAX_BYTES that the other tools use.
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPluginData } from '../../../config.mjs';
+import { stripAnsi } from '../../shell-exec-output.mjs';
+import { createCarriageReturnFolder } from '../shell-lossless-compact.mjs';
+import { positiveEnvInt } from '../../../../../shared/tool-output-limit.mjs';
+import { escapeHarnessTags } from '../../../../../shared/shell-output-summary.mjs';
+
+export const DELIVERY_FULL_CHARS = positiveEnvInt('MIXDOG_SHELL_DELIVERY_MAX_CHARS', 6_000);
+const DELIVERY_HEAD_LINES = 10;
+const DELIVERY_HEAD_MAX_CHARS = 1_000;
+const DELIVERY_TAIL_CHARS = 2_000;
+export const DELIVERY_LINE_MAX_CHARS = 2_000;
+
+export { createCarriageReturnFolder };
+
+const newlines = (text) => {
+  let count = 0;
+  for (let i = text.indexOf('\n'); i >= 0; i = text.indexOf('\n', i + 1)) count += 1;
+  return count;
+};
+
+export function formatKb(bytes) {
+  return `${(Math.max(0, bytes) / 1024).toFixed(1)} KB`;
+}
+
+/** The omission marker — identical on every delivery path, path last. */
+export function omissionMarker({ lines, bytes, path }) {
+  return `[… ${lines} lines, ${formatKb(bytes)} omitted — read with offset/limit or grep, full log: ${path}]`;
+}
+
+// `cut` is the number of chars removed from over-long lines.
+function cutLongLines(text) {
+  if (text.length <= DELIVERY_LINE_MAX_CHARS) return { text, cut: 0 };
+  let cut = 0;
+  const cutText = text
+    .split('\n')
+    .map((line) => {
+      if (line.length <= DELIVERY_LINE_MAX_CHARS) return line;
+      cut += line.length - DELIVERY_LINE_MAX_CHARS;
+      return `${line.slice(0, DELIVERY_LINE_MAX_CHARS)} … [${line.length - DELIVERY_LINE_MAX_CHARS} chars cut]`;
+    })
+    .join('\n');
+  return { text: cutText, cut };
+}
+
+/** Step 1 for one chunk (the cut of step 2 is made where the text is
+ *  delivered, so the uncut text can be archived). `fold` carries `\r` state
+ *  across chunks of the same stream; omitted, the chunk is folded on its own. */
+export function prepareShellText(text, fold = createCarriageReturnFolder()) {
+  return fold(stripAnsi(String(text ?? '')));
+}
+
+// `scale` is the share of the delivery budget a stream was given.
+function headOf(text, scale = 1) {
+  let end = 0;
+  for (let line = 0; line < DELIVERY_HEAD_LINES && end < text.length; line += 1) {
+    const newline = text.indexOf('\n', end);
+    end = newline < 0 ? text.length : newline + 1;
+  }
+  return text.slice(0, Math.min(end, Math.floor(DELIVERY_HEAD_MAX_CHARS * scale)));
+}
+
+function tailOf(text, floor = 0, scale = 1) {
+  const start = Math.max(floor, text.length - Math.floor(DELIVERY_TAIL_CHARS * scale));
+  if (start === floor) return text.slice(start);
+  // Start on a line boundary when one is near.
+  const newline = text.indexOf('\n', start);
+  return newline >= 0 && newline - start < 200 && newline + 1 < text.length
+    ? text.slice(newline + 1)
+    : text.slice(start);
+}
+
+/** head + marker + tail; `omitted` counts what lies between them. */
+function joinHeadTail(head, tail, omitted) {
+  const gap = head && !head.endsWith('\n') ? '\n' : '';
+  return `${head}${gap}${omissionMarker(omitted)}\n${tail}`;
+}
+
+// One stream's delivery: `natural` is the length it would have whole (escaped,
+// markers included; Infinity when it can only be shown at its ends) and
+// `render(budget)` the text within `budget` chars. Streams share one budget.
+export const EMPTY_PIECE = { natural: 0, render: () => '' };
+
+/** Step 3 when only the two ends of a long range were read: `total` is the
+ *  whole range's bytes and lines. */
+export function edgesPiece(headText, tailText, { totalBytes, totalLines, path }) {
+  return {
+    natural: Number.POSITIVE_INFINITY,
+    render: (budget) => {
+      const scale = budget / DELIVERY_FULL_CHARS;
+      const head = headOf(escapeHarnessTags(headText), scale);
+      const tail = tailOf(escapeHarnessTags(tailText), 0, scale);
+      return joinHeadTail(head, tail, {
+        lines: Math.max(0, totalLines - newlines(head) - newlines(tail)),
+        bytes: Math.max(0, totalBytes - Buffer.byteLength(head) - Buffer.byteLength(tail)),
+        path,
+      });
+    },
+  };
+}
+
+export { newlines as countNewlines };
+
+/** Steps 2, 3 and 5 on prepared text. `path` names where the whole (uncut)
+ *  text can be read; it is resolved only when something is removed. */
+export function textPiece(text, { path }) {
+  let archive;
+  const where = () => (archive ??= typeof path === 'function' ? path() : path);
+  const { text: cutText, cut } = cutLongLines(text);
+  const shown = escapeHarnessTags(cutText);
+  // Cut long lines are removed content too: the whole text carries the marker.
+  const whole = cut
+    ? `${shown}${shown.endsWith('\n') ? '' : '\n'}${omissionMarker({ lines: 0, bytes: cut, path: where() })}\n`
+    : shown;
+  return {
+    natural: whole.length,
+    render: (budget) => {
+      if (whole.length <= budget) return whole;
+      const scale = budget / DELIVERY_FULL_CHARS;
+      const head = headOf(shown, scale);
+      const tail = tailOf(shown, head.length, scale);
+      const middle = shown.slice(head.length, shown.length - tail.length);
+      return joinHeadTail(head, tail, { lines: newlines(middle), bytes: Buffer.byteLength(middle), path: where() });
+    },
+  };
+}
+
+/** Max-min fair split of `budget` over the streams' natural lengths: a stream
+ *  that fits its fair share is given exactly what it needs, the rest share
+ *  what remains. */
+function shareBudget(lengths, budget) {
+  const shares = lengths.map(() => 0);
+  let open = lengths.map((_, index) => index);
+  let left = Math.max(0, budget);
+  while (open.length) {
+    const fair = left / open.length;
+    const fits = open.filter((index) => lengths[index] <= fair);
+    if (!fits.length) {
+      for (const index of open) shares[index] = fair;
+      break;
+    }
+    for (const index of fits) {
+      shares[index] = lengths[index];
+      left -= lengths[index];
+    }
+    open = open.filter((index) => !fits.includes(index));
+  }
+  return shares;
+}
+
+/** Deliver streams within one shared budget (default: the whole-delivery cap),
+ *  each escaped; the caller deducts what it adds around them. */
+export function fitPieces(pieces, budget = DELIVERY_FULL_CHARS) {
+  const shares = shareBudget(
+    pieces.map((piece) => piece.natural),
+    budget
+  );
+  return pieces.map((piece, index) => escapeHarnessTags(piece.render(shares[index])));
+}
+
+/** Text that has no log of its own is kept where the marker can name it:
+ *  the shell-output folder, swept with the spill files. */
+export function persistDeliveryLog(text, label = 'output') {
+  const dir = join(getPluginData(), 'shell-output');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `delivered_${Date.now().toString(36)}_${randomBytes(4).toString('hex')}.${label}`);
+  writeFileSync(file, text);
+  return file;
+}
+
+/** Steps 1–5 for a whole string, as a piece. Without `path`, the original
+ *  (uncut) text is saved when anything is removed, so the marker can name it. */
+export function shellTextPiece(text, { path = null, label = 'output', fold } = {}) {
+  const prepared = prepareShellText(text, fold);
+  return textPiece(prepared, { path: path || (() => persistDeliveryLog(prepared, label)) });
+}
+
+export function deliverShellText(text, options) {
+  return fitPieces([shellTextPiece(text, options)])[0];
+}
+
+/** Step 5 alone, for text the caller already capped. */
+export { escapeHarnessTags };

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-task-output.mjs

@@ -1,11 +1,34 @@
+// Incremental delivery of a shell task's output. Each task (the authorized
+// task object) owns one cursor per stream; every wait, read, background move
+// and completion notice delivers only the bytes after it, in the shared
+// delivery shape (lib/shell-delivery.mjs). The cursor always advances over the
+// whole unseen range, even when its middle is omitted: omitted bytes are never
+// re-sent, the marker's log path is how to get them back.
 import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
 import { stripAnsi } from '../../shell-exec-output.mjs';
 import { FileEncodingSniffer, ShellStreamDecoder, alignedOffset, oemTextEncoding } from '../../shell-codepage.mjs';
+import {
+  DELIVERY_FULL_CHARS,
+  countNewlines,
+  createCarriageReturnFolder,
+  edgesPiece,
+  escapeHarnessTags,
+  fitPieces,
+  formatKb,
+  omissionMarker,
+  persistDeliveryLog,
+  prepareShellText,
+  textPiece,
+} from './shell-delivery.mjs';
 
-import { TOOL_OUTPUT_PAGE_BYTES, TOOL_OUTPUT_TAIL_BYTES } from '../../../../../shared/tool-output-budget.mjs';
 const cursors = new WeakMap();
 const ESC = '\x1b';
 const PENDING_ANSI_INTRODUCER = new RegExp(`${ESC}(?:\\[[0-?]*[ -/]*|\\](?:(?!${ESC}\\\\)[^\x07\x9c])*)?$`);
+// An unseen range up to this size is read whole; a longer one only at its two
+// ends (the middle is counted, never loaded).
+const FULL_READ_BYTES = 64 * 1024;
+const EDGE_READ_BYTES = 16 * 1024;
+const COUNT_CHUNK_BYTES = 1 << 20;
 
 function newCursor() {
   return {
@@ -13,6 +36,7 @@ function newCursor() {
     preview: '',
     decoder: new ShellStreamDecoder(),
     ansi: '',
+    fold: createCarriageReturnFolder(),
     sniffer: new FileEncodingSniffer(),
     committed: false,
   };
@@ -26,13 +50,6 @@ function pendingAnsiIntroducer(sequence) {
   return '\x1b';
 }
 
-// First index at or after `start` that does not sit inside a UTF-8 sequence.
-function utf8Boundary(bytes, start, end) {
-  let index = start;
-  while (index < end && (bytes[index] & 0xc0) === 0x80) index++;
-  return index;
-}
-
 function visibleText(cursor, text) {
   const value = cursor.ansi + text;
   // Retain only the introducer of an unfinished CSI/OSC, not its potentially
@@ -45,21 +62,123 @@ function visibleText(cursor, text) {
   return stripAnsi(value.slice(0, pending.index));
 }
 
+function readBytes(fd, start, length) {
+  const buffer = Buffer.alloc(Math.max(0, length));
+  const count = length > 0 ? readSync(fd, buffer, 0, length, start) : 0;
+  return buffer.subarray(0, count);
+}
+
+function countNewlinesInRange(fd, start, end) {
+  let count = 0;
+  const buffer = Buffer.alloc(Math.min(COUNT_CHUNK_BYTES, Math.max(1, end - start)));
+  for (let position = start; position < end; ) {
+    const bytes = readSync(fd, buffer, 0, Math.min(buffer.length, end - position), position);
+    if (bytes <= 0) break;
+    for (let i = 0; i < bytes; i += 1) if (buffer[i] === 10) count += 1;
+    position += bytes;
+  }
+  return count;
+}
+
+function decodeVisible(cursor, bytes, flush) {
+  let decoded = cursor.decoder.write(bytes);
+  if (flush) decoded += cursor.decoder.end();
+  return prepareShellText(visibleText(cursor, decoded), cursor.fold);
+}
+
+// One unseen file range [start, end) in the delivery shape. A long range is
+// read only at its ends; the tail starts a fresh decoder at a character
+// boundary, as the original paging did when it skipped bytes.
+function readRange(fd, cursor, { start, end, label, flush, path }) {
+  const total = end - start;
+  if (total <= FULL_READ_BYTES) {
+    const text = decodeVisible(cursor, readBytes(fd, start, total), flush);
+    return { piece: textPiece(text, { path }), bytes: total, lines: countNewlines(text), text };
+  }
+  const headText = decodeVisible(cursor, readBytes(fd, start, EDGE_READ_BYTES), false);
+  const tailStart = alignedOffset(fd, end - EDGE_READ_BYTES, label || 'utf-8');
+  cursor.decoder = new ShellStreamDecoder(oemTextEncoding(), label);
+  cursor.ansi = '';
+  cursor.fold = createCarriageReturnFolder();
+  const tailText = decodeVisible(cursor, readBytes(fd, tailStart, end - tailStart), flush);
+  const lines = countNewlinesInRange(fd, start, end);
+  return {
+    piece: edgesPiece(headText, tailText, { totalBytes: total, totalLines: lines, path }),
+    bytes: total,
+    lines,
+    text: tailText,
+  };
+}
+
+const PERCENT_RE = /(\d{1,3}(?:\.\d+)?)\s?%/g;
+const ETA_RE = /\b(?:ETA|eta|remaining|left)\b[:=\s]*(\d+(?::\d{2}){1,2}|\d+(?:\.\d+)?\s?(?:h|m|s|min|sec)\b)/g;
+
+function lastMatch(pattern, text) {
+  let found = null;
+  for (const match of text.matchAll(pattern)) found = match;
+  return found;
+}
+
+/** What changed since the agent last saw the job: growth, last line, any
+ *  visible percent/ETA. Used where a still-running job is reported. */
+function progressDigest(growth) {
+  const bytes = growth.reduce((sum, entry) => sum + entry.bytes, 0);
+  const lines = growth.reduce((sum, entry) => sum + entry.lines, 0);
+  const text = growth
+    .map((entry) => entry.text)
+    .filter(Boolean)
+    .join('\n');
+  const parts = [
+    bytes > 0 ? `+${formatKb(bytes)}, +${lines} lines since you last saw it` : 'no new output since you last saw it',
+  ];
+  const last = text
+    .split('\n')
+    .reverse()
+    .find((line) => line.trim());
+  if (last) parts.push(`last line: ${JSON.stringify(last.trim().slice(0, 200))}`);
+  const percent = lastMatch(PERCENT_RE, text);
+  if (percent && Number(percent[1]) <= 100) parts.push(`${percent[1]}%`);
+  const eta = lastMatch(ETA_RE, text);
+  if (eta) parts.push(`ETA ${eta[1].trim()}`);
+  return `[progress] ${parts.join(' · ')} — still running, not an error`;
+}
+
+/** A whole finished log as a piece of the delivery (a foreground command whose
+ *  capture spilled to disk), read with a fresh cursor. */
+export function shellLogPiece(path) {
+  const cursor = newCursor();
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const size = fstatSync(fd).size;
+    const label = cursor.sniffer.probe(fd, size, true);
+    if (label) cursor.decoder.force(label);
+    return readRange(fd, cursor, { start: 0, end: size, label, flush: true, path }).piece;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
 // Cursor ownership follows the authorized task object, not a globally supplied
 // task id. Bounded synchronous reads make concurrent task reads non-overlapping.
 // Only bytes actually read advance the cursor; previews never stand in for a
 // file offset, since a preview may contain an omitted middle.
-// Explicit tail reads never change the incremental cursor. A terminal read
-// prioritizes the final diagnostics; any skipped bytes remain in the raw file.
-export function readShellTaskOutput(task, result = {}, { output = 'new' } = {}) {
+// Explicit tail reads (`output: 'tail'`) never change the incremental cursor.
+// `terminal` flushes the decoders (the producer finished); `digest` prefixes
+// the progress digest for a job reported while still running.
+export function readShellTaskOutput(
+  task,
+  result = {},
+  { output = 'new', terminal = task.status !== 'running', digest = false } = {}
+) {
   const replay = output === 'tail';
-  const terminal = task.status !== 'running';
-  const limit = terminal || replay ? TOOL_OUTPUT_TAIL_BYTES : TOOL_OUTPUT_PAGE_BYTES;
+  const growth = [];
   let streams = replay ? new Map() : cursors.get(task);
   if (!streams) {
     streams = new Map();
     cursors.set(task, streams);
   }
+  // A note, or a stream's body: stdout and stderr share one delivery budget.
   const sections = [];
   for (const stream of ['stdout', 'stderr']) {
     const path = result[`${stream}_path`];
@@ -73,15 +192,15 @@ export function readShellTaskOutput(task, result = {}, { output = 'new' } = {})
     if (!path) {
       const preview = String(result[`${stream}_preview`] || '');
       const delta = preview.startsWith(cursor.preview) ? preview.slice(cursor.preview.length) : preview;
-      const bytes = Buffer.from(delta);
-      const start = utf8Boundary(bytes, Math.max(0, bytes.length - limit), bytes.length);
-      if (start) {
-        sections.push(`[${stream}: ${start} preview bytes omitted; no original log path available]`);
-        cursor.ansi = '';
-      }
-      const text = visibleText(cursor, bytes.subarray(start).toString('utf8'));
+      const text = prepareShellText(visibleText(cursor, delta), cursor.fold);
       cursor.preview = preview;
-      if (text) sections.push(`[${stream}]\n${text}`);
+      growth.push({ bytes: Buffer.byteLength(delta), lines: countNewlines(text), text });
+      // A preview has no log of its own: a capped one is saved for the marker.
+      if (text)
+        sections.push({
+          prefix: `[${stream}]\n`,
+          piece: textPiece(text, { path: () => persistDeliveryLog(text, stream) }),
+        });
       continue;
     }
     let fd;
@@ -102,30 +221,37 @@ export function readShellTaskOutput(task, result = {}, { output = 'new' } = {})
         cursor.decoder.force(label);
       }
       const readEnd = label ? size : cursor.sniffer.safeEnd(size);
-      let start = terminal || replay ? Math.max(cursor.offset, readEnd - limit) : cursor.offset;
-      if (start > cursor.offset) {
-        start = Math.min(readEnd, alignedOffset(fd, start, label || 'utf-8'));
-        sections.push(`[${stream}: ${start - cursor.offset} earlier bytes omitted; read ${path} for the original log]`);
+      let start = cursor.offset;
+      let earlier = '';
+      if (replay && readEnd - start > FULL_READ_BYTES) {
+        // A replay shows the recent part; everything before it is counted.
+        start = Math.min(readEnd, alignedOffset(fd, readEnd - FULL_READ_BYTES, label || 'utf-8'));
+        earlier = omissionMarker({ lines: countNewlinesInRange(fd, 0, start), bytes: start, path });
         cursor.decoder = new ShellStreamDecoder(oemTextEncoding(), label);
-        cursor.ansi = '';
-      }
-      const buffer = Buffer.alloc(Math.min(limit, Math.max(0, readEnd - start)));
-      const count = buffer.length ? readSync(fd, buffer, 0, buffer.length, start) : 0;
-      cursor.offset = start + count;
-      let decoded = cursor.decoder.write(buffer.subarray(0, count));
-      if (terminal && cursor.offset === size) decoded += cursor.decoder.end();
-      const text = visibleText(cursor, decoded);
-      if (text) sections.push(`[${stream}]\n${text}`);
-      if (cursor.offset < size) {
-        sections.push(
-          `[${stream}: ${size - cursor.offset} unread bytes; task read continues, read ${path} for the original log]`
-        );
       }
+      const range = readRange(fd, cursor, { start, end: readEnd, label, flush: terminal && readEnd === size, path });
+      cursor.offset = readEnd;
+      growth.push(range);
+      if (range.piece.natural)
+        sections.push({ prefix: `[${stream}]\n${earlier ? `${earlier}\n` : ''}`, piece: range.piece });
     } catch (error) {
       sections.push(`[${stream} read error: ${error.message}]`);
     } finally {
       if (fd !== undefined) closeSync(fd);
     }
   }
-  return sections.join('\n\n') || (replay ? '(no output)' : '(no new output)');
+  // Notes and prefixes come off the budget; the streams split what is left.
+  const fixed = sections.reduce(
+    (sum, item) => sum + (item.prefix ?? item).length,
+    2 * Math.max(0, sections.length - 1)
+  );
+  const pieces = sections.filter((item) => item.piece);
+  const bodies = fitPieces(
+    pieces.map((item) => item.piece),
+    DELIVERY_FULL_CHARS - fixed
+  );
+  const body =
+    sections.map((item) => (item.piece ? `${item.prefix}${bodies[pieces.indexOf(item)]}` : item)).join('\n\n') ||
+    (replay ? '(no output)' : '(no new output)');
+  return escapeHarnessTags(digest ? `${progressDigest(growth)}\n\n${body}` : body);
 }

package/src/runtime/agent/orchestrator/tools/builtin/list-tool.mjs

@@ -6,10 +6,16 @@ import { markScopedCacheIncomplete, markScopedCacheUnsafe } from '../../session/
 import { cacheGet, cacheSet, lstatPathsForMtime } from './cache-layers.mjs';
 import { runScopedSearchInFlight } from './lib/scoped-search-flight.mjs';
 import { NOISE_DIR_NAMES, walkDir } from './glob-walk.mjs';
-import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
+import { TOOL_OUTPUT_MAX_BYTES, capMarker } from './tool-output-limit.mjs';
 import { runRgWindowedLines } from './native-search-runner.mjs';
 import { tryServeListMetadata } from './native-search-client.mjs';
-import { countTextFileLines, guardedWalkRoot, normalizeListHeadLimit, pageContinuationLine } from './lib/list-helpers.mjs';
+import {
+  countTextFileLines,
+  guardedWalkRoot,
+  comparePathsStable,
+  normalizeListHeadLimit,
+  pageContinuationLine,
+} from './lib/list-helpers.mjs';
 import { reportToolProgress } from './lib/tool-progress.mjs';
 import { displayRelPath, statWalkRoot } from './list-tool-shared.mjs';
 import { executeFindFilesTool } from './find-files-tool.mjs';
@@ -338,9 +344,9 @@ async function fillRowMetadata(rows, workDir, options) {
 }
 
 function sortListRows(rows, sort) {
-  if (sort === 'mtime') rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  else if (sort === 'size') rows.sort((a, b) => b.size - a.size);
-  else rows.sort((a, b) => a.path.localeCompare(b.path));
+  if (sort === 'mtime') rows.sort((a, b) => b.mtimeMs - a.mtimeMs || comparePathsStable(a.path, b.path));
+  else if (sort === 'size') rows.sort((a, b) => b.size - a.size || comparePathsStable(a.path, b.path));
+  else rows.sort((a, b) => a.path.localeCompare(b.path) || comparePathsStable(a.path, b.path));
 }
 
 // What an empty page means: offset past the end is a windowing condition,
@@ -390,15 +396,17 @@ async function scanList(request, cacheKey, workDir, options) {
   if (root.error) return root.error;
   if (!root.stat.isDirectory()) {
     if (!root.stat.isFile()) return `Error: not a directory — ${normalizeOutputPath(fullPath)}`;
-    const out = listFileLine(fullPath, root.stat, meta, meta ? await countTextFileLines(fullPath, root.stat.size) : null);
+    const out = listFileLine(
+      fullPath,
+      root.stat,
+      meta,
+      meta ? await countTextFileLines(fullPath, root.stat.size) : null
+    );
     cacheSet(cacheKey, out, { scopes: [fullPath] });
     return out;
   }
-  const { rows, walkResult, walkWarnings, truncatedByCap, nativeDeep, cacheSafe, nativeMetaMissing } = await collectListRows(
-    request,
-    workDir,
-    options
-  );
+  const { rows, walkResult, walkWarnings, truncatedByCap, nativeDeep, cacheSafe, nativeMetaMissing } =
+    await collectListRows(request, workDir, options);
   const rootFailure = walkRootFailureLine(options, walkResult, walkWarnings, 'list walk');
   if (rootFailure) return rootFailure;
   if (!nativeDeep && needsGlobalStat) await fillRowMetadata(rows, workDir, options);
@@ -439,7 +447,11 @@ async function renderListPage({ request, rows, walkWarnings, truncatedByCap, nat
   if (paged) lines.push(pageContinuationLine(offset, sliced.length, rows.length));
   if (truncatedByCap) {
     lines.push(
-      `... walk truncated at ${LIST_ABSOLUTE_CAP} rows or ${LIST_WALK_TIMEOUT_MS}ms timeout; narrow the path or lower depth for a complete listing`
+      capMarker({
+        limit: `${LIST_ABSOLUTE_CAP} rows or ${LIST_WALK_TIMEOUT_MS}ms`,
+        shown: 'listing incomplete',
+        narrow: 'narrow the path or lower depth',
+      })
     );
   }
   for (const warning of walkWarnings) lines.push(directoryReadFailureLine(warning, true));
@@ -516,7 +528,7 @@ function renderTreeOutput(lines, walkWarnings, { headLimit, offset }) {
     outputCharTruncated = true;
     out =
       out.slice(0, TOOL_OUTPUT_MAX_BYTES) +
-      `\n... [output truncated at ${Math.round(TOOL_OUTPUT_MAX_BYTES / 1024)} KB; narrow path or lower depth]`;
+      `\n${capMarker({ limit: TOOL_OUTPUT_MAX_BYTES, narrow: 'narrow path or lower depth' })}`;
   }
   return { out, outputCharTruncated };
 }

package/src/runtime/agent/orchestrator/tools/builtin/read-batch.mjs

@@ -1,4 +1,5 @@
 import { READ_BATCH_RANGE_COALESCE_GAP_LINES } from './read-constants.mjs';
+import { windowMarker } from './tool-output-limit.mjs';
 
 // Slices a `read` body (full mode) to the line window [origOffset+1,
 // origOffset+origLimit] (1-based line numbers in the body). Lines whose
@@ -81,15 +82,15 @@ export function sliceReadBodyByLines(body, origOffset, origLimit, readOffsetBase
   else if (finiteLast) requestedLast = lastLine;
   const emittedStart = keptFirst ?? firstLine;
   const emittedLast = keptLast !== null ? Math.min(requestedLast, keptLast) : requestedLast;
-  const totalPart = haveTotal ? ` of ${totalNum}` : '';
   const moreToRead = haveTotal ? emittedLast < totalNum : finiteLast;
   // Report the next caller coordinate without prescribing another read;
   // whatever remains fits one wider read, not a walk window by window.
-  let continuationPart = '';
-  if (moreToRead && Number.isFinite(emittedLast)) {
-    continuationPart = `; pass offset:${emittedLast + readOffsetBase} to continue`;
-  }
-  const newFooter = `[lines ${emittedStart}-${emittedLast}${totalPart}${continuationPart}]`;
+  const newFooter = windowMarker({
+    from: emittedStart,
+    to: emittedLast,
+    total: haveTotal ? totalNum : null,
+    nextOffset: moreToRead && Number.isFinite(emittedLast) ? emittedLast + readOffsetBase : null,
+  });
   return kept.join('\n') + (kept.length ? '\n' : '') + newFooter;
 }
 

package/src/runtime/agent/orchestrator/tools/builtin/read-formatting.mjs

@@ -1,6 +1,6 @@
 import { READ_LINE_NO_SEP } from '../../../../shared/read-row-numbers.mjs';
 import { mergeReadRanges } from './read-ranges.mjs';
-import { TOOL_OUTPUT_MAX_BYTES, positiveEnvInt } from './tool-output-limit.mjs';
+import { TOOL_OUTPUT_MAX_BYTES, capMarker, positiveEnvInt } from './tool-output-limit.mjs';
 
 // Smart-truncate cap: a no-window read returns the file until this cap, past
 // which head+tail are shown and the model pages the rest with offset (footer
@@ -18,9 +18,23 @@ const READ_MAX_RENDERED_LINE_CHARS = 2_000;
 // (runtime/shared/read-row-numbers.mjs).
 export const LINE_NO_SEP = READ_LINE_NO_SEP;
 
-export function buildSmartReadTruncationMarker(totalLines, fileBytes) {
+// Cap marker for the elided middle of a no-window read. With the omitted
+// line span it names the continuation offset; without, narrowing advice.
+export function buildSmartReadTruncationMarker(totalLines, fileBytes, omitted = null) {
   const kb = Math.max(1, Math.round((Number(fileBytes) || 0) / 1024));
-  return `... [TRUNCATED - ${totalLines} lines / ${kb} KB; read located windows with {file_path, offset, limit}] ...`;
+  const limit = fileBytes > SMART_READ_MAX_BYTES ? SMART_READ_MAX_BYTES : `${SMART_READ_MAX_LINES} lines`;
+  if (!omitted) {
+    return capMarker({
+      limit,
+      shown: `${totalLines} lines / ${kb} KB`,
+      narrow: 'read located windows with {file_path, offset, limit}',
+    });
+  }
+  return capMarker({
+    limit,
+    shown: `lines ${omitted.from}-${omitted.to} of ${totalLines} omitted (${kb} KB file)`,
+    nextOffset: omitted.from,
+  });
 }
 
 function rangeFromRenderedReadRows(rows, fallbackStartLine = 1) {
@@ -56,9 +70,10 @@ export function smartReadTruncate(renderedWithLineNos, totalLines, fileBytes) {
   const tailRows = rows.slice(tailStart);
   const head = headRows.join('\n');
   const tail = tailRows.join('\n');
-  const marker = buildSmartReadTruncationMarker(totalLines, fileBytes);
+  const marker = buildSmartReadTruncationMarker(totalLines, fileBytes, { from: headCount + 1, to: tailStart });
   return {
     text: `${head}\n${marker}\n${tail}`,
+    marker,
     truncated: true,
     totalLines,
     ranges: mergeReadRanges(