@animalabs/agent-framework 0.26.2 → 0.28.0

package/src/modules/workspace/read-page.ts

@@ -0,0 +1,228 @@
+import type { ToolResult } from '../../types/events.js';
+import { answerText, fieldLine, sectionLead, sectionText, textAnswer } from './result-text.js';
+import { type FileText, MAX_LINE_CHARS, numberedLine, safeCut } from './text.js';
+import { didNothing } from './answers.js';
+
+/**
+ * One page of a read, held to the result limit as its text measures it: a
+ * model reads the page's text (result-text.ts), and what passes the caller's
+ * limit doesn't reach it whole. A model's result spills into a file, cut, and
+ * a script gets ResultTooLarge in its place. So a page stops before its text
+ * would pass the limit, and its note says where to continue. A script's
+ * answer carries the page's fields, its content among them, beside its text,
+ * and the limit counts the text alone. A script's limit counts each character
+ * at the six bytes it takes at most in the answer, and no character but a
+ * control character takes more than three, so the text and the fields
+ * together pass what the script takes only on a page of more than half that
+ * limit (about 3.7 million characters at the default 128 MiB of script
+ * memory) holding control characters.
+ */
+
+/** How many lines a read shows when it isn't given a limit. */
+export const DEFAULT_READ_LINE_LIMIT = 2000;
+
+/** What a read says about the text it shows, besides the lines themselves. */
+export function textNotes(file: FileText): string[] {
+  const notes: string[] = [];
+  if (file.crlfEnds > 0) {
+    // A line whose own text ends in a CR shows its line end's CR too (fileText).
+    const kept = file.crKept > 0
+      ? `, except on ${file.crKept} ${file.crKept === 1 ? 'line whose own text ends in a CR, which shows' : 'lines whose own text ends in a CR, which show'} both CRs`
+      : '';
+    notes.push(file.lfEnds > 0
+      ? `Line ends are mixed, ${file.crlfEnds} CRLF and ${file.lfEnds} LF, and a CRLF end is shown without its CR${kept}. An edit matches text as read shows it, and keeps each line's end.`
+      : `Line ends are CRLF, shown without the CR${kept}. An edit matches text as read shows it, and keeps the CRLF ends.`);
+  }
+  if (file.bom) notes.push('The file starts with a UTF-8 BOM, which isn\'t shown. An edit keeps it.');
+  if (!file.utf8) notes.push(NOT_UTF8);
+  return notes;
+}
+
+const NOT_UTF8 = 'The file isn\'t valid UTF-8: each invalid byte sequence shows as U+FFFD. Edit refuses this file, and write replaces it whole.';
+
+const joined = (notes: Array<string | null>): string | undefined => {
+  const kept = notes.filter((n): n is string => n !== null);
+  return kept.length > 0 ? kept.join(' ') : undefined;
+};
+
+/** A page's fields: a line page's or a character page's, and its content, numbered lines or raw text. */
+type Page = { path: string; content: string; note?: string } & Record<string, string | number | null | undefined>;
+
+/** A page's text: its fields, one to a line in their order, and then its content under its label. */
+function pageText(page: Page): string {
+  const header = Object.entries(page)
+    .filter((entry): entry is [string, string | number | null] => entry[0] !== 'content' && entry[1] !== undefined)
+    .map(([key, value]) => fieldLine(key, value));
+  return answerText(header, [sectionText('content', page.content)]);
+}
+
+/** A page as read answers it: its text for the model, and its fields for a script. */
+const pageAnswer = (page: Page): ToolResult => textAnswer(pageText(page), page);
+
+/**
+ * Lines from `offset` (1-based), at most `limit` of them, each numbered and a
+ * long one cut with the offsetChars and limitChars that read the rest. The
+ * page is the longest whose text fits within `maxChars`; where none fits
+ * with its first line as a page shows it, that line is cut shorter, at the
+ * most the page has room for. Where the page's last line is cut, its note
+ * names where that line's rest starts and how long it is, since reading on in
+ * order starts there: before the next line, or, on the page that ends the
+ * file, before the file is read whole. A page whose own fields and least
+ * content pass `maxChars` still moves on, and passes it. With no `maxChars`,
+ * for a call made in process, which takes the data itself, the page holds to
+ * `limit` alone and shows every line whole.
+ */
+export function linePage(path: string, file: FileText, offset: number, limit: number, maxChars: number | undefined, extraNotes: string[] = []): ToolResult {
+  const { lines, starts } = file;
+  const total = lines.length;
+  const first = offset - 1;
+  const notes = [...textNotes(file), ...extraNotes];
+  if (first >= total) {
+    // Nothing to show: an empty file, or an offset past the last line. No
+    // range is claimed, and the line count says where the file ends.
+    const note = joined([
+      // Reading an empty file from its start is reading it whole.
+      first > 0 ? `Line ${first + 1} is past the end: the file has ${total} line${total === 1 ? '' : 's'}.` : null,
+      ...notes,
+    ]);
+    return pageAnswer({ path, totalLines: total, ...(note !== undefined ? { note } : {}), content: '' });
+  }
+  const last = Math.min(first + limit, total);
+  const shown = (i: number, maxLineChars = MAX_LINE_CHARS) =>
+    numberedLine(lines[i], i + 1, maxLineChars,
+      (cut) => `read the rest with offsetChars=${starts[i] + cut} and limitChars=${lines[i].length - cut}`);
+  // Where the rest of line i starts in the stored text, shown at most
+  // maxLineChars long, as its marker says; null for a line shown whole.
+  const restOf = (i: number, maxLineChars: number): number | null =>
+    lines[i].length > maxLineChars ? starts[i] + safeCut(lines[i], maxLineChars) : null;
+  // The rest's length is what's left of the line as a page shows it, so a
+  // character read of it ends where the line does.
+  const cutLine = (to: number, rest: number) =>
+    `Line ${to} is cut: read its rest with offsetChars=${rest} and limitChars=${starts[to - 1]! + lines[to - 1]!.length - rest}`;
+  const limitNote = (to: number, rest: number | null) =>
+    `Truncated at ${limit} lines (file has ${total}).${rest === null ? '' : ` ${cutLine(to, rest)}.`} Use offset/limit to read more.`;
+  const budgetNote = (to: number, rest: number | null) =>
+    `Stopped at line ${to} to stay within the ${maxChars}-character result limit (file has ${total}). `
+    + (rest === null ? `Continue with offset=${to + 1}.` : `${cutLine(to, rest)}, then continue with offset=${to + 1}.`);
+  const page = (to: number, content: string, note: string | undefined): Page => ({
+    path, totalLines: total, fromLine: first + 1, toLine: to, ...(note !== undefined ? { note } : {}), content,
+  });
+  if (maxChars === undefined) {
+    const whole = lines.slice(first, last).map((line, k) => numberedLine(line, first + k + 1, Infinity)).join('\n');
+    return pageAnswer(page(last, whole, joined([last < total ? limitNote(last, null) : null, ...notes])));
+  }
+  // The note of the page that ends at line `to`, its last line shown at most
+  // lastMax long: the page that ends where it was asked to, at the file's end
+  // or the line limit, says so, and any other says it stopped for the limit.
+  const noteAt = (to: number, lastMax = MAX_LINE_CHARS) => {
+    const rest = restOf(to - 1, lastMax);
+    const endNote = to < total ? limitNote(to, rest) : rest === null ? null : `${cutLine(to, rest)}.`;
+    return joined([to === last ? endNote : budgetNote(to, rest), ...notes]);
+  };
+  // A page's text's length: its fields' and note's, measured with no content,
+  // and its content's, under the content's label. A page here has a line.
+  const lengthAt = (to: number, contentChars: number, note: string | undefined) =>
+    pageText(page(to, '', note)).length + sectionLead('content') + contentChars;
+  // The page is the longest that fits. Its length isn't monotone in its
+  // lines: the page that ends the file carries no stop note, the one at the
+  // line limit a shorter one than a stop, and one whose last line is cut a
+  // longer one. But every page carries `notes` and a longer page shows more,
+  // so once a page passes the limit with those alone, no longer one fits.
+  const shownLines: string[] = [];
+  let contentChars = 0;
+  let best = 0;
+  for (let i = first; i < last; i++) {
+    const line = shown(i);
+    shownLines.push(line);
+    // Each line after the first comes after a line feed.
+    contentChars += line.length + (i > first ? 1 : 0);
+    if (lengthAt(i + 1, contentChars, noteAt(i + 1)) <= maxChars) best = shownLines.length;
+    else if (lengthAt(i + 1, contentChars, joined(notes)) > maxChars) break;
+  }
+  if (best > 0) {
+    shownLines.length = best;
+    return pageAnswer(page(first + best, shownLines.join('\n'), noteAt(first + best)));
+  }
+  // No page fits with its first line as a page shows it: the loop tried that
+  // page first, since a read's limit is at least 1, and it is pageWith(top).
+  // So the line is cut shorter, at the most the page has room for, and ends
+  // the page: its note names where the line's rest starts and how long it is,
+  // since that comes next. Each cut is measured on the page itself, since its
+  // note names the cut. Every cut below `top` shows a marker. A longer cut
+  // adds a character of text at least, and the offsets only grow, but the
+  // rest's length is in the marker and in the note, so where it loses a digit
+  // the page loses two characters: it can be one character shorter than the
+  // page a cut before. The search takes the page as growing with the cut.
+  // Such a dip is one cut, and the next is many cuts away, so the longest cut
+  // that fits is the one the search finds or, past a dip, at most two cuts
+  // further, four code units at most, and those are tried too.
+  const pageWith = (chars: number) => page(first + 1, shown(first, chars), noteAt(first + 1, chars));
+  const fitsAt = (chars: number) => pageText(pageWith(chars)).length <= maxChars;
+  const top = Math.min(lines[first].length, MAX_LINE_CHARS);
+  let fits = 0;
+  let over = top;
+  while (over - fits > 1) {
+    const mid = Math.floor((fits + over) / 2);
+    if (fitsAt(mid)) fits = mid; else over = mid;
+  }
+  // The search ends with `fits + 1` measured as too long, or as `top`.
+  const found = fits;
+  for (let chars = found + 2; chars <= found + 4 && chars < top; chars++) if (fitsAt(chars)) fits = chars;
+  return pageAnswer(pageWith(fits));
+}
+
+const splitsPair = (text: string, at: number): boolean =>
+  at > 0 && at < text.length
+  && text.charCodeAt(at - 1) >= 0xd800 && text.charCodeAt(at - 1) <= 0xdbff
+  && text.charCodeAt(at) >= 0xdc00 && text.charCodeAt(at) <= 0xdfff;
+
+/**
+ * Raw text from `offsetChars`, at most `limitChars` code units (one more to
+ * keep a surrogate pair whole), stopped sooner where its page's text would
+ * pass `maxChars`, if there is one.
+ */
+export function characterPage(path: string, file: FileText, offsetChars: number, limitChars: number, maxChars: number | undefined, extraNotes: string[] = []): ToolResult {
+  const text = file.raw;
+  const start = Math.min(offsetChars, text.length);
+  if (splitsPair(text, start)) {
+    return {
+      success: false,
+      isError: true,
+      error: didNothing('read', `"offsetChars" ${start} falls between the two halves of a surrogate pair, one character in UTF-16. `
+        + `Give ${start - 1} or ${start + 1}; a page's nextOffsetChars never splits one.`),
+    };
+  }
+  let end = start + Math.min(limitChars, text.length - start);
+  if (splitsPair(text, end)) end++;
+  const notes = [...(file.utf8 ? [] : [NOT_UTF8]), ...extraNotes];
+  // A page that stops short of what it was asked for gives what's left of
+  // that as limitChars, so a reader that follows its notes ends where it
+  // asked to: at a cut line's end, for the rest a line page's note names.
+  const stoppedNote = (to: number, left: number) =>
+    `Stopped at character ${to} to stay within the ${maxChars}-character result limit; read the rest of what you asked for with offsetChars=${to} and limitChars=${left}.`;
+  const page = (to: number, note: string | undefined): Page => ({
+    path,
+    totalChars: text.length,
+    offsetChars: start,
+    nextOffsetChars: to < text.length ? to : null,
+    ...(note !== undefined ? { note } : {}),
+    content: text.slice(start, to),
+  });
+  const whole = page(end, joined(notes));
+  if (maxChars === undefined || pageText(whole).length <= maxChars) return pageAnswer(whole);
+  // As many characters as fit beside the rest of the page, which takes the
+  // most with the largest offset it could stop at and the most left. A page
+  // moves by whole characters, a surrogate pair at once, so it never stops
+  // inside one.
+  const overhead = pageText({ ...page(end, joined([stoppedNote(end, end - start), ...notes])), nextOffsetChars: end, content: '' }).length + sectionLead('content');
+  const step = (at: number) => (splitsPair(text, at + 1) ? 2 : 1);
+  let to = Math.min(end, start + Math.max(0, maxChars - overhead));
+  if (splitsPair(text, to)) to--;
+  // A page always moves on, by one character at least, though a limit too
+  // small for the page's own fields and its first character then passes it:
+  // with room for one code unit, a surrogate pair is still taken whole. Where
+  // that reaches the page's own end, it holds all it was asked for, so it
+  // names no stop.
+  if (to === start) to = Math.min(end, start + step(start));
+  return pageAnswer(page(to, joined([to < end ? stoppedNote(to, end - to) : null, ...notes])));
+}

package/src/modules/workspace/reconcile.ts

@@ -53,9 +53,11 @@ import {
   sameRootIdentity,
 } from './disk-agreement.js';
 import type { BranchIntent, BranchIntents, ConflictKind, ConflictRecord, DiskCounterpart } from './branch-intent.js';
+import { storedBytes, type StoredBytes } from './sync.js';
 import {
   IGNORED,
   type MountView,
+  NOT_A_DIRECTORY,
   OTHER_MOUNT,
   ROOT_REPLACED,
   type Walk,
@@ -75,6 +77,7 @@ import {
   withinIncludes,
 } from './observe.js';
 import { EffectFailed, type Expect, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
+import { errnoWords } from './answers.js';
 
 export type EntryState =
   | 'synced'
@@ -486,7 +489,7 @@ function inTheWay(reason: string | undefined, deletion: boolean): string | null
   }
   // A deletion below a file finds nothing there to unlink, so only a write
   // meets this one.
-  if (reason === 'a parent path is not a directory') {
+  if (reason === NOT_A_DIRECTORY) {
     return 'disk has a file or a symlink where this path needs a directory, and no push writes below one, forced or not — ' +
       'move or remove it on disk and materialize again, or write the file under another path';
   }
@@ -506,7 +509,7 @@ function inTheWay(reason: string | undefined, deletion: boolean): string | null
  * to pass.
  */
 function forcedWay(note: string | undefined, deletion: boolean, forced: string): string {
-  if (note === 'cannot open (EACCES)') return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
+  if (note === `cannot open (${errnoWords('EACCES')})`) return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
   return '';
 }
 
@@ -914,8 +917,8 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
       byDesign = OTHER_MOUNT;
     } else if (!opts.named) {
       const slash = path.lastIndexOf('/');
-      const above = slash < 0 ? undefined : passedOverAt(path.slice(0, slash), mount.view.ignore, mount.view.others);
-      const own = above === undefined && !walk ? passedOverAt(path, mount.view.ignore, mount.view.others) : undefined;
+      const above = slash < 0 ? undefined : passedOverAt(path.slice(0, slash), mount.view.ignore, mount.view.others, true);
+      const own = above === undefined && !walk ? passedOverAt(path, mount.view.ignore, mount.view.others, false) : undefined;
       byDesign = above ?? own;
     } else if (scope.kind === 'dir') {
       byDesign = passedOverBetween(scope.dir, path, ignoreBeneath(scope.dir, mount.view.ignore), mount.view.others);
@@ -1028,9 +1031,13 @@ export async function reconcilePass(
   }
 
   // The evidence about to be recorded describes the root it was gathered
-  // under, which is recorded first (once per mount), so no crash can leave
-  // evidence without its root.
-  if (gathered.rootIdentity && planned.some((x) => x.verdict.adopt !== undefined || x.verdict.p !== undefined)) {
+  // under, which is recorded first, so no crash can leave evidence without
+  // its root. Once a root is recorded, every pass that found it offers it,
+  // evidence or none: the same root on a new device, or with its first
+  // birth time, is recorded again (recordRootIdentity writes nothing
+  // otherwise), and a quiet mount's passes are where an old record learns
+  // its birth time.
+  if (gathered.rootIdentity && (agreement.rootIdentity(mount.name) !== undefined || planned.some((x) => x.verdict.adopt !== undefined || x.verdict.p !== undefined))) {
     agreement.recordRootIdentity(mount.name, gathered.rootIdentity);
   }
 
@@ -1386,12 +1393,12 @@ export async function pushPaths(
         continue;
       }
       const priorP = p && (p.kind === 'absent' || p.kind === 'content') ? p : null;
-      const blob = store.getBlob(s.hash);
+      const stored = storedBytes(store, s.hash);
       const forcedMode = mount.modesObserved && s.mode !== undefined && s.mode !== (d.kind === 'file' ? d.mode : undefined) ? s.mode : undefined;
       const agreedMode = priorP?.kind === 'content' ? priorP.mode : undefined;
-      if (blob) {
+      if ('bytes' in stored) {
         plans.push({
-          path, kind: 'write', blob, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect,
+          path, kind: 'write', blob: stored.bytes, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect,
           ...(forcedMode !== undefined ? { apply: forcedMode } : {}),
           ...(forcedMode !== undefined && d.kind === 'file' && agreedMode !== d.mode ? { overDisk: true as const } : {}),
           ...(s.mode !== undefined ? { storeMode: s.mode } : {}),
@@ -1400,7 +1407,7 @@ export async function pushPaths(
           ...(agreedMode !== undefined ? { priorMode: agreedMode } : {}),
           ...(d.kind === 'file' && d.mode !== undefined ? { seenMode: d.mode } : {}),
         });
-      } else result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
+      } else result.skipped.push({ path, reason: unstoredCopy(stored) });
       continue;
     }
     if (v.mode === 'adopt' && s && d.kind === 'file') {
@@ -1426,7 +1433,7 @@ export async function pushPaths(
     }
     // Whatever the verdict learned about disk (an agreement, a resolved
     // intent) is recorded before anything is pushed over it, and the root it
-    // was learned under before that (once per mount), as a pass does.
+    // was learned under before that, as a pass does.
     if (v.p !== undefined) agreement.recordRootIdentity(mount.name, root.identity);
     if (v.p === 'forget') agreement.forget(mount.name, path);
     else if (v.p !== undefined) agreement.set(mount.name, path, v.p, { afterCommittedState: true });
@@ -1551,11 +1558,12 @@ export async function pushPaths(
       plans.push({ path, kind: 'unlink', prior, before: agreement.get(mount.name, path), expect });
       continue;
     }
-    const blob = store.getBlob(s.hash);
-    if (!blob) {
-      result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
+    const stored = storedBytes(store, s.hash);
+    if (!('bytes' in stored)) {
+      result.skipped.push({ path, reason: unstoredCopy(stored) });
       continue;
     }
+    const blob = stored.bytes;
     // The store's mode goes to disk with its bytes where the file is new,
     // the push is forced, or disk still has the mode they last agreed on. A
     // push that completes our own unconfirmed one, whose bytes landed, is a
@@ -1774,3 +1782,7 @@ export async function pushPaths(
   agreement.maybeCheckpoint();
   return result;
 }
+
+function unstoredCopy(stored: Exclude<StoredBytes, { bytes: Buffer }>): string {
+  return 'missing' in stored ? 'the workspace copy is missing from the store' : `the workspace copy is unreadable in the store (${stored.unreadable})`;
+}

package/src/modules/workspace/result-text.ts

@@ -0,0 +1,121 @@
+import type { ToolResult } from '../../types/events.js';
+
+/**
+ * The text a model reads of read's, grep's, edit's and edit_many's answers:
+ * a header of the answer's own fields, one `key: value` to a line in the
+ * fields' order, then its sections, each a `--- label ---` line and the lines
+ * under it, an empty one left out. The answer's fields themselves reach a
+ * script as its structuredContent (ToolResult.structured), and a page or a
+ * receipt is held to the call's result limit as this text measures it.
+ */
+
+/** The characters Unicode says end a line (UAX #14's mandatory breaks): LF, VT, FF, CR, NEL, U+2028 and U+2029. */
+const LINE_BREAK = /[\n\v\f\r\u0085\u2028\u2029]/;
+
+/**
+ * A value as a header line, a section's label or a listed line writes it: as
+ * it is, or, where it holds a line break or starts with a quote, as a JSON
+ * string. A path can hold a line break, and so can a note naming it or a line
+ * of a file grep matched; written as it is, it would start a line that reads
+ * as one of the answer's own. A value written as it is never starts with a
+ * quote, so one that does is always the quoted form, which gives back exactly
+ * what the value holds: without that, a value that is itself a JSON string,
+ * such as a line of a file reading `"a\nb"`, would read as the quoted form of
+ * another. JSON leaves NEL, U+2028 and U+2029 as they are, so they're escaped
+ * too.
+ */
+export function shownValue(value: string | number | boolean | null): string {
+  if (typeof value !== 'string') return String(value);
+  if (!value.startsWith('"') && !LINE_BREAK.test(value)) return value;
+  return JSON.stringify(value).replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+export type DiskState = 'done' | 'waits for materialize' | 'waits for materialize with applyDeletions' | 'in conflict with disk';
+
+/** A header line: a field's key and its value as shownValue writes it. */
+export const fieldLine = (key: string, value: string | number | boolean | null): string => `${key}: ${shownValue(value)}`;
+
+/** A section's text, its label and then its lines; an empty section is no text. */
+export const sectionText = (label: string, body: string): string => (body === '' ? '' : `--- ${label} ---\n${body}`);
+
+/** The answer's text: its header lines and then its sections, each on lines of its own. */
+export const answerText = (header: string[], sections: string[] = []): string =>
+  [...header, ...sections.filter((section) => section !== '')].join('\n');
+
+/** How much a section with any lines adds to its answer's text before them: the line feed before its label, and the label's line. */
+export const sectionLead = (label: string): number => `\n--- ${label} ---\n`.length;
+
+/** A success whose text is what the model reads and whose fields reach a script as its structuredContent. */
+export const textAnswer = (text: string, structured: Record<string, unknown>): ToolResult =>
+  ({ success: true, data: [{ type: 'text', text }], structured });
+
+/** A grep result: the matches of one version of a file. */
+export interface GrepResult {
+  file: string;
+  state?: string;
+  version: string;
+  lineEndings?: string;
+  matches: Array<{ line: number; text: string; context?: string[] }>;
+}
+
+/** What grep found, as its structuredContent holds it. */
+export interface GrepAnswer {
+  pattern: string;
+  results: GrepResult[];
+  totalMatches: number;
+  note?: string;
+  skipped?: Array<{ file: string; reason: string; size?: number; mimeType?: string }>;
+  incomplete?: Array<{ path: string; reason: string }>;
+}
+
+/**
+ * grep's text: its pattern, match count and note, then a section for each
+ * version of a file it matched, labelled with the file, the version, the
+ * file's state where grep gives one and its line ends where it has them, then
+ * what it skipped and where its search was incomplete. As grep writes them, a
+ * match's line reads `N:text`, and where the call asked for context, each
+ * line around it reads `N-text`: matches whose context meets or overlaps are
+ * one run of lines, each line once, and `--` stands between runs with lines
+ * left out between them. Each match's context starts `contextBefore` lines
+ * before it, or at the file's first line. A line's text is written through
+ * shownValue, since more of the answer follows it.
+ */
+export function grepText(answer: GrepAnswer, contextBefore: number): string {
+  const header = [fieldLine('pattern', answer.pattern), fieldLine('totalMatches', answer.totalMatches)];
+  if (answer.note !== undefined) header.push(fieldLine('note', answer.note));
+  const sections = answer.results.map((result) => {
+    const label = `${shownValue(result.file)}: ${result.version}`
+      + (result.state !== undefined ? ` (${result.state})` : '')
+      + (result.lineEndings !== undefined ? `; lineEndings: ${result.lineEndings}` : '');
+    const lines: string[] = [];
+    const matched = new Set(result.matches.map((match) => match.line));
+    // The last line written: matches come in line order, so a window that
+    // meets or overlaps the run before it goes on from there.
+    let last = 0;
+    for (const match of result.matches) {
+      if (match.context === undefined) {
+        lines.push(`${String(match.line).padStart(6)}:${shownValue(match.text)}`);
+        continue;
+      }
+      const first = Math.max(1, match.line - contextBefore);
+      match.context.forEach((text, k) => {
+        const n = first + k;
+        if (n <= last) return;
+        if (last > 0 && n > last + 1) lines.push('--');
+        lines.push(`${String(n).padStart(6)}${matched.has(n) ? ':' : '-'}${shownValue(text)}`);
+        last = n;
+      });
+    }
+    return sectionText(label, lines.join('\n'));
+  });
+  if (answer.skipped !== undefined) {
+    sections.push(sectionText('skipped', answer.skipped.map((skip) => {
+      const facts = [...(skip.size !== undefined ? [`${skip.size} bytes`] : []), ...(skip.mimeType !== undefined ? [skip.mimeType] : [])];
+      return `${shownValue(skip.file)}: ${shownValue(skip.reason)}${facts.length ? ` (${facts.join(', ')})` : ''}`;
+    }).join('\n')));
+  }
+  if (answer.incomplete !== undefined) {
+    sections.push(sectionText('incomplete', answer.incomplete.map((gap) => `${shownValue(gap.path)}: ${shownValue(gap.reason)}`).join('\n')));
+  }
+  return answerText(header, sections);
+}

package/src/modules/workspace/sync.ts

@@ -6,6 +6,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { JsStore } from '@animalabs/chronicle';
 
 export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
 
@@ -18,3 +19,18 @@ export function hashContent(content: string | Buffer): string {
   hash.update(content);
   return hash.digest('hex');
 }
+
+export type StoredBytes = { bytes: Buffer } | { missing: true } | { unreadable: string };
+
+export function storedBytes(store: JsStore, hash: string): StoredBytes {
+  try {
+    const blob = store.getBlob(hash);
+    return blob ? { bytes: blob } : { missing: true };
+  } catch (error) {
+    if (store.isClosed()) throw error;
+    // Chronicle's getBlob throws, rather than answering null, for a blob file
+    // it can't read whole or whose format, checksum or hash doesn't check out,
+    // such as one a write cut short left truncated.
+    return { unreadable: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/modules/workspace/text.ts

@@ -1,7 +1,9 @@
+import { isUtf8 } from 'node:buffer';
+
 /**
- * Lines numbered the way `cat -n` numbers them, with a long one cut, and a
- * string's length as JSON, which a budget for a stored result counts. edit's
- * answers use them.
+ * A stored file's text as read shows it and grep searches it, and lines
+ * numbered the way `cat -n` numbers them, with a long one cut. Read, grep and
+ * edit's answers use them.
  */
 
 /** Whether the bytes open with a UTF-8 byte order mark. */
@@ -9,6 +11,57 @@ export function hasBom(bytes: Uint8Array): boolean {
   return bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
 }
 
+export interface FileText {
+  /** The bytes decoded as UTF-8, as character paging reads them: a BOM and every CR kept. */
+  raw: string;
+  /**
+   * Its lines, as read shows them and grep searches them: without the BOM, a
+   * CR before a line feed dropped, and a final line end ending the last line
+   * rather than starting an empty one. So "a\r\nb\r\n" is two lines, and an
+   * empty text has none. A line whose own text ends in a CR keeps its line
+   * end's CR too, as stored: an edit reads a CR before a line feed in its old
+   * text as part of the line end, so text copied from "a\r" and the next line
+   * would lose the CR that is the line's own.
+   */
+  lines: string[];
+  /** Where each line starts in `raw`. */
+  starts: number[];
+  bom: boolean;
+  /** How many line ends were CRLF, and how many a bare LF. */
+  crlfEnds: number;
+  lfEnds: number;
+  /** How many lines with a CRLF end keep its CR, since their own text ends in a CR. */
+  crKept: number;
+  /** Whether the bytes are valid UTF-8; where they aren't, `raw` holds U+FFFD. */
+  utf8: boolean;
+}
+
+export function fileText(bytes: Buffer): FileText {
+  const raw = bytes.toString('utf-8');
+  const bom = hasBom(bytes);
+  const lines: string[] = [];
+  const starts: number[] = [];
+  let crlfEnds = 0;
+  let lfEnds = 0;
+  let crKept = 0;
+  // A BOM decodes to the single code unit U+FEFF.
+  for (let at = bom ? 1 : 0; at < raw.length;) {
+    const lf = raw.indexOf('\n', at);
+    starts.push(at);
+    if (lf === -1) {
+      lines.push(raw.slice(at));
+      break;
+    }
+    const crlf = lf > at && raw.charCodeAt(lf - 1) === 13;
+    if (crlf) crlfEnds++; else lfEnds++;
+    const keepsCr = crlf && lf - 1 > at && raw.charCodeAt(lf - 2) === 13;
+    if (keepsCr) crKept++;
+    lines.push(raw.slice(at, crlf && !keepsCr ? lf - 1 : lf));
+    at = lf + 1;
+  }
+  return { raw, lines, starts, bom, crlfEnds, lfEnds, crKept, utf8: isUtf8(bytes) };
+}
+
 /** How long a line read shows before it cuts the line. */
 export const MAX_LINE_CHARS = 2000;
 
@@ -26,43 +79,16 @@ export function safeCut(value: string, at: number): number {
 /**
  * One line numbered the way `cat -n` numbers it: a six-wide number, a tab and
  * the line. A line longer than `maxChars` is cut, saying how many characters
- * it holds past the cut, and `readOn` adds how to read them.
+ * it holds past the cut, or, where `readOn` is given, how to read them.
  */
 export function numberedLine(line: string, n: number, maxChars = MAX_LINE_CHARS, readOn?: (cut: number) => string): string {
   const number = String(n).padStart(6);
   if (line.length <= maxChars) return `${number}\t${line}`;
   const cut = safeCut(line, maxChars);
-  return `${number}\t${line.slice(0, cut)} [… ${line.length - cut} more chars${readOn ? `; ${readOn(cut)}` : ''}]`;
+  return `${number}\t${line.slice(0, cut)} [… ${readOn ? readOn(cut) : `${line.length - cut} more chars`}]`;
 }
 
 /** Lines numbered from `start`, each as numberedLine shows it. */
 export function numbered(lines: string[], start: number, maxChars = MAX_LINE_CHARS): string {
   return lines.map((line, i) => numberedLine(line, start + i, maxChars)).join('\n');
 }
-
-/**
- * How many characters a string takes inside JSON's quotes, as JSON.stringify
- * writes it: a quote, a backslash or a control character is escaped, and so
- * is a lone surrogate.
- */
-export function jsonLength(value: string): number {
-  let length = 0;
-  for (let i = 0; i < value.length; i++) length += jsonCharLength(value, i);
-  return length;
-}
-
-/** The JSON length of the code unit at `i`, as jsonLength counts it. */
-export function jsonCharLength(value: string, i: number): number {
-  const c = value.charCodeAt(i);
-  if (c === 0x22 || c === 0x5c) return 2;
-  if (c < 0x20) return c === 0x08 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d ? 2 : 6;
-  if (c >= 0xd800 && c <= 0xdbff) {
-    const next = value.charCodeAt(i + 1);
-    return next >= 0xdc00 && next <= 0xdfff ? 1 : 6;
-  }
-  if (c >= 0xdc00 && c <= 0xdfff) {
-    const before = i > 0 ? value.charCodeAt(i - 1) : 0;
-    return before >= 0xd800 && before <= 0xdbff ? 1 : 6;
-  }
-  return 1;
-}