@animalabs/agent-framework 0.26.1 → 0.27.0

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

@@ -0,0 +1,222 @@
+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';
+
+/**
+ * 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: 'offsetChars splits a surrogate pair; use nextOffsetChars from the previous page.' };
+  }
+  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/result-text.ts

@@ -0,0 +1,119 @@
+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')}`);
+}
+
+/** 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/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;
-}

package/src/modules/workspace/types.ts

@@ -20,24 +20,44 @@ export interface MountConfig {
    * Where the mount's tools get what they read (default: 'chronicle').
    * - 'chronicle': the workspace keeps the mount's files in its store, where
    *   writes and edits land first, and takes in disk's changes under the
-   *   three-way rule as its listings, searches, syncs and scans reach them.
-   *   A read of a path the store doesn't hold takes in a new file there;
-   *   otherwise it reads the store's copy.
-   * - 'direct': for a checkout an agent reads, not one it changes. Every
-   *   read, listing and search is disk's own copy as it is when it runs,
-   *   and none of its files go into the store. No scan or watcher
+   *   three-way rule as `read`, listings, searches, syncs and scans reach
+   *   them. Its tools read the store's copy.
+   * - 'direct': for a checkout, such as a git one, whose history is its
+   *   own. Every read, listing and search is disk's own copy as it is when
+   *   it runs, and none of its files go into the store. No scan or watcher
    *   runs, so no call waits behind one, and `sync`, `materialize` and the
-   *   watch settings have nothing to act on. Only with `mode: 'read-only'`,
-   *   and not with `watch` other than 'never', `watchDebounceMs`,
-   *   `watchRootPollMs`, a `wakeOnChange` that would wake (true, or a
-   *   non-empty list) or `autoMaterialize: true`: each of those would never
-   *   act, and the workspace refuses the mount. Its `ignore`
+   *   watch settings have nothing to act on. Not with `watch` other than
+   *   'never', `watchDebounceMs`, `watchRootPollMs`, a `wakeOnChange` that
+   *   would wake (true, or a non-empty list) or `autoMaterialize: true`:
+   *   each of those would never act, and the workspace refuses the mount.
+   *   Writable, as any mount with no `mode` is, its `write`, `edit`,
+   *   `edit_many` and `delete` land on disk when they answer, or don't
+   *   happen: a file is staged beside itself in `.workspace-staged-<id>` and
+   *   renamed over itself, keeping its mode, so no reader sees half of it;
+   *   an edit is applied to disk's text as it is now, and again on top of a
+   *   change another writer makes meanwhile; and `edit_many` checks every
+   *   edit before writing its files one by one, naming each file's outcome
+   *   if a write fails partway. A file with other hard links gets a file of
+   *   its own at its path, and the others keep the old text; a file this
+   *   process may not write is refused. Nothing is synced, so a power loss
+   *   can lose a write its answer called landed. An undo or other move of
+   *   the store's head leaves the files as they are, and at the agent's next
+   *   start the framework tells it once that writes from turns its history
+   *   no longer holds are still on disk. Where each agent's latest write
+   *   lies is saved at a clean stop, in a record no branch switch rewinds,
+   *   so a restart on another branch still tells it, and after a crash a
+   *   move away from the writes since then isn't told. The framework's own
+   *   files, its
+   *   tool-result spills, saved payloads and fetched references, never go to
+   *   a mount configured direct. Its `ignore`
    *   has a default (see there). Paths, links, its `include`, other mounts'
    *   directories, size limits and the walk cap hold as on a 'chronicle'
-   *   mount. Its tools read beneath whatever directory is at its
-   *   root, with no check against the one a 'chronicle' run of it last
-   *   agreed with. Where that root now lies elsewhere than the last start
-   *   placed it, each call nests in it, as a start would now, every mount
+   *   mount. Its tools read and write beneath whatever directory is at its
+   *   root when each call starts, with no check against the one a
+   *   'chronicle' run of it last agreed with, so a root repointed through a
+   *   link is read and written where it leads now. Where that root now lies
+   *   elsewhere than the last start placed it, each call nests in it, as a
+   *   start would now, every mount
    *   configured beneath its path, where that path leads beneath its root,
    *   and every other mount whose root, as that start placed it, lies
    *   beneath where its root lies now, or whose configured path lies
@@ -52,7 +72,10 @@ export interface MountConfig {
    * them pending, or an intent the workspace can't read, which may hold one
    * of those. They stay in view, and the workspace says so on stderr and
    * through the framework's ops alerts, naming them and the ways to start it
-   * direct. It runs unwatched, and walks by the direct kind's default
+   * direct. Until a start finds none held, it takes no writes, edits or
+   * deletions, so what's held only shrinks: a `sync` of a held path takes
+   * disk's copy, and a `materialize` naming the mount writes the store's.
+   * It runs unwatched, and walks by the direct kind's default
    * ignore list where its config names none; `ls` without a path, and
    * `status`, give its `backend` as 'chronicle' and that list. A mount that
    * ran direct and runs as 'chronicle' again takes in what disk changed
@@ -290,7 +313,8 @@ export interface MountConfig {
   /**
    * If true, writes/edits/deletes via the module's tools materialize to the
    * filesystem immediately (not just into Chronicle tree state). Required for
-   * any mount shared across agents as a communication channel — without it,
+   * any store-backed mount shared across agents as a communication channel (a
+   * direct mount's writes reach disk without it, and it's refused there) — without it,
    * another agent's watcher on the same directory sees nothing. The watcher
    * suppresses its own echoes, so this doesn't cause self-wake loops.
    */