@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/modules/workspace/direct-write.ts

@@ -0,0 +1,425 @@
+/**
+ * A direct mount's writes (MountConfig.backend): disk is the only copy, so a
+ * write lands there whole when its call answers, or doesn't happen and leaves
+ * disk as it was. Ported from anima-research/hands-mcp's staged write
+ * (src/shared.ts), behind the mount's boundary as the workspace's other
+ * effects hold it (effects.ts):
+ *
+ * - The file's directory is located inside the mount (checkDir), and where
+ *   the file lands is judged as a push's write judges it (refusedLanding):
+ *   inside the mount, in no nested mount's directory, and covered by the
+ *   mount's include. A link at the file is refused on a mount that doesn't
+ *   follow links; on one that does, the write goes to the file it leads to
+ *   when the call stages it, judged the same way, and the link stays.
+ * - The new bytes are staged beside the file, in `.workspace-staged-<id>`,
+ *   at the file's mode, special bits included as far as the kernel lets this
+ *   process set them (a setgid bit only for a member of the file's group),
+ *   and renamed over it, so a reader beside the agent never sees half a file
+ *   and a process killed mid-write leaves the old file whole. A file this
+ *   process may not write is refused, as a push's write, which opens it for
+ *   writing, is refused: the rename needs only the directory's permission.
+ *   A process that dies between staging and its rename leaves the staged
+ *   file, under that name, which `ls` and `git status` show; so does a
+ *   refused write whose removal of its staged file fails or can't tell the
+ *   file is its own, or whose directory another writer moved after the
+ *   staging, since the removal goes by path (discard) and the path then
+ *   leads elsewhere. Nothing sweeps it, and the answer doesn't name it.
+ *   The removal checks the staged name holds that file and unlinks it with
+ *   no turn of the event loop between, so only a file another writer puts
+ *   there in that instant can be removed in its place, or one put there
+ *   that a stat can't tell from it: on the freed inode number, with the
+ *   same size, mode and owner, in the same tick of a coarse clock.
+ * - The rename gives a hard-linked path a file of its own, and the other
+ *   links keep the old text: `otherLinks` counts them for the answer.
+ * - Just before the rename, an edit's file is checked unchanged since its
+ *   read, by its bytes, read again, and its identity (checkUnchanged),
+ *   synchronously, so the check and the renames after it run with no turn
+ *   of the event loop between. Only a change landing in that instant isn't
+ *   seen, which for edit_many runs from the check through its last rename:
+ *   no rename can be made conditional.
+ * - No sync. The store-backed kind syncs its pushes for its agreement
+ *   record (reconcile.ts), and a direct mount keeps none, so a power loss
+ *   or a kernel crash can lose a direct write after its answer said it
+ *   landed, as it can a hands-mcp write. A process dying can't: the rename is
+ *   whole by then.
+ *
+ * Node has no openat or renameat, so the stage and the rename go through the
+ * checked directory's path: a directory replaced by another writer on disk
+ * between the directory's check and the staging, or after its last check
+ * (placedStill), can redirect them, as effects.ts says of a create. For
+ * edit_many that last check is each file's, before the other files' checks.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { accessSync, closeSync, constants as fsConstants, lstatSync, openSync, readSync, renameSync, unlinkSync } from 'node:fs';
+import type { BigIntStats } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { relative, sep } from 'node:path';
+import { refusedLanding } from './effects.js';
+import {
+  type CheckedDir,
+  type MountView,
+  NONBLOCK,
+  NOT_FOLLOWED,
+  OUTSIDE_PARENT,
+  checkDir,
+  checkRoot,
+  errno,
+  nameOf,
+  parentOf,
+} from './observe.js';
+
+/** An open that follows no link at the path, where the platform has one. */
+const NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+
+/** The name a staged file starts with, beside the file it replaces. */
+export const STAGED_PREFIX = '.workspace-staged-';
+
+/**
+ * Why a direct write didn't happen when its mount's root was replaced under
+ * it: a direct mount keeps no root to sync to (MountConfig.backend), so its
+ * next call works beneath whatever is there then.
+ */
+export const ROOT_MOVED = 'the mount root changed while this call was being applied: a new call works beneath whatever directory the mount\'s path leads to then';
+
+/**
+ * A file's identity as a write must find it unchanged: device, inode, size,
+ * mode, owner, group, and modification and change times, to the nanosecond.
+ * The mode, owner and group are fields of their own, since a chmod or chown
+ * in the same tick of a coarse clock as the file's last change leaves its
+ * change time as it was (checkUnchanged).
+ */
+export interface FileIdentity {
+  dev: bigint;
+  ino: bigint;
+  size: bigint;
+  mode: bigint;
+  uid: bigint;
+  gid: bigint;
+  mtimeNs: bigint;
+  ctimeNs: bigint;
+}
+
+export const identityOf = (info: BigIntStats): FileIdentity => ({
+  dev: info.dev,
+  ino: info.ino,
+  size: info.size,
+  mode: info.mode,
+  uid: info.uid,
+  gid: info.gid,
+  mtimeNs: info.mtimeNs,
+  ctimeNs: info.ctimeNs,
+});
+
+export const sameIdentity = (a: FileIdentity, b: FileIdentity): boolean =>
+  a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid
+  && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+
+/** Another writer replaced, changed or removed the file between its read and its rename; nothing was written. */
+export class FileChanged extends Error {}
+
+/** Why a direct write didn't happen, in words for its answer; disk is as it was. */
+export class WriteRefused extends Error {}
+
+/** A file's new bytes staged beside it, ready to be renamed over it (stageContained). */
+export interface Staged {
+  /** Where the rename lands: the file's entry in its checked directory, a followed link's file's included. */
+  path: string;
+  /** The staged file, beside it. */
+  temp: string;
+  /**
+   * Which file the staged file is, so the rename moves, and a refusal
+   * removes, that one and no other put at its name: its whole identity,
+   * since a file made where it was unlinked can take its inode number.
+   */
+  tempIdentity: FileIdentity;
+  /** The mount's root and the file's directory, as checked when it was staged. */
+  root: CheckedDir;
+  parent: CheckedDir;
+  /**
+   * The other hard links the replaced file had, counted just before the
+   * rename and kept once it succeeds: the rename gives this path a file of
+   * its own, and they keep the old text. 0 until then, and for a new file.
+   */
+  otherLinks: number;
+}
+
+/**
+ * Test seams. `afterStage` is called once a call's files are staged, before
+ * they're checked unchanged (another writer acting then); `beforeRename`
+ * just before each rename, inside its refusal, so throwing stands for the
+ * rename failing. Production sets neither.
+ */
+export const directWriteTestSeam: {
+  afterStage?: (paths: string[]) => void | Promise<void>;
+  beforeRename?: (path: string) => void;
+} = {};
+
+/** The mount-relative path of a real path inside the mount's root, `/`-separated. */
+function relativeTo(rootReal: string, real: string): string {
+  return relative(rootReal, real).split(sep).join('/');
+}
+
+/**
+ * The checked directory a mount-relative file lies in, beneath a checked
+ * root, or why not. With `makeDirectory`, missing directories are made, as
+ * a push's write makes them; without it, a missing one refuses the write,
+ * since an edit replaces a file that exists.
+ */
+async function directoryOf(view: MountView, rootReal: string, rel: string, makeDirectory: boolean): Promise<CheckedDir> {
+  const checked = await checkDir(view, rootReal, parentOf(rel), { create: makeDirectory });
+  if (checked.kind === 'checked') return checked.dir;
+  if (checked.kind === 'absent') throw new FileChanged(rel);
+  throw new WriteRefused(checked.outside ? OUTSIDE_PARENT : checked.reason);
+}
+
+/**
+ * Stage `bytes` beside the mount-relative file `rel`, to be renamed over it:
+ * the first half of a direct write. The file keeps its mode, special bits
+ * included, as far as the kernel lets this process set them; a new file
+ * takes `0666` less the umask, as a shell's would. Its owner and group are
+ * this process's and the ones its directory gives a new file, and an ACL or
+ * extended attribute on the file isn't carried over, as with any write that
+ * renames over a file. Anything there that isn't a regular file is refused,
+ * and a refusal removes the staged file it made, except where the header
+ * says one is left. The staged file is written and moded through its own
+ * handle, never through its name again.
+ */
+export async function stageContained(
+  view: MountView,
+  rootReal: string,
+  rel: string,
+  bytes: Buffer,
+  { makeDirectory = false }: { makeDirectory?: boolean } = {},
+): Promise<Staged> {
+  const root = await checkRoot(view, rootReal);
+  if ('reason' in root) throw new WriteRefused(root.reason);
+  let parent = await directoryOf(view, rootReal, rel, makeDirectory);
+  let path = parent.at(nameOf(rel));
+  let info = await lstat(path, { bigint: true }).catch((err: unknown) => {
+    if (errno(err) === 'ENOENT') return null;
+    throw new WriteRefused(`cannot stat the file (${errno(err) ?? String(err)})`);
+  });
+  if (info?.isSymbolicLink()) {
+    if (!view.followSymlinks) throw new WriteRefused(NOT_FOLLOWED);
+    // A followed link stands for the file it leads to, as a read takes it:
+    // the write goes there, judged where it lands, and the link stays.
+    const real = await realpath(path).catch((err: unknown) => {
+      throw new WriteRefused(errno(err) === 'ENOENT' ? "a symlink whose target doesn't exist" : `cannot resolve the symlink (${errno(err) ?? String(err)})`);
+    });
+    const leaves = await refusedLanding(view, rootReal, rel, real);
+    if (leaves !== null) throw new WriteRefused(leaves);
+    const realRel = relativeTo(rootReal, real);
+    parent = await directoryOf(view, rootReal, realRel, false);
+    path = parent.at(nameOf(realRel));
+    info = await lstat(path, { bigint: true }).catch((err: unknown) => {
+      // Gone since realpath found it: another writer's change.
+      if (errno(err) === 'ENOENT') throw new FileChanged(rel);
+      throw new WriteRefused(`cannot stat the file the symlink leads to (${errno(err) ?? String(err)})`);
+    });
+    if (info.isSymbolicLink()) throw new FileChanged(rel);
+  } else {
+    // A file, or none yet, reached through a link among its directories
+    // lands where the mount may not act: in a nested mount's directory, or
+    // on a file its own include leaves out (refusedLanding).
+    const leaves = await refusedLanding(view, rootReal, rel, path);
+    if (leaves !== null) throw new WriteRefused(leaves);
+  }
+  if (info?.isDirectory()) throw new WriteRefused('a directory');
+  if (info && !info.isFile()) throw new WriteRefused('not a regular file');
+  // A fixed-length name, so a file whose own name is near the 255-byte limit can still be replaced.
+  const temp = parent.at(`${STAGED_PREFIX}${randomUUID()}`);
+  let made = false;
+  try {
+    // A new file is made at 0666 and the kernel takes the umask off as it
+    // makes it. A file being replaced gives the staged file its own mode,
+    // which only a chmod can set past the umask, and only after the bytes
+    // are written, since a write clears a set-user or set-group bit; until
+    // then the staged file is the owner's alone, so no other user can read
+    // a private file's new text while it's staged.
+    const handle = await open(temp, 'wx', info ? 0o600 : 0o666);
+    made = true;
+    let staged: Staged;
+    try {
+      await handle.writeFile(bytes);
+      if (info) await handle.chmod(Number(info.mode & 0o7777n));
+      const own = await handle.stat({ bigint: true });
+      staged = { path, temp, tempIdentity: identityOf(own), root: root.dir, parent, otherLinks: 0 };
+    } catch (err) {
+      // Removed while its handle is still open, so its device and inode
+      // name it and no other file: one made at its name since can't have
+      // taken its inode number. One that can't be told is left.
+      const mine = await handle.stat({ bigint: true }).catch(() => null);
+      if (mine) removeIf(temp, (there) => there.dev === mine.dev && there.ino === mine.ino);
+      await handle.close().catch(() => undefined);
+      throw err;
+    }
+    try {
+      await handle.close();
+    } catch (err) {
+      // Closed, or not, with its bytes in doubt: removed by its whole identity, as a refusal's.
+      await discard(staged);
+      throw err;
+    }
+    return staged;
+  } catch (err) {
+    // A staged file that couldn't be made names the directory: a push's
+    // write in place needs only the file, and this one needs both.
+    throw new WriteRefused(made
+      ? `cannot write the staged file beside it (${errno(err) ?? String(err)})`
+      : `cannot make the staged file in its directory (${errno(err) ?? String(err)}): a direct write needs to write the file's directory as well as the file`);
+  }
+}
+
+/**
+ * Throw unless the root and the file's directory are still the ones the
+ * staging checked, with a push's words for the directory (effects.ts
+ * moved()).
+ */
+export async function placedStill(staged: Staged): Promise<void> {
+  if (!(await staged.root.stillHere())) throw new WriteRefused(ROOT_MOVED);
+  if (!(await staged.parent.stillHere())) throw new WriteRefused('the directory changed since it was checked');
+}
+
+/**
+ * Throw unless the file is still what its read found: FileChanged when it
+ * changed or is gone, nothing written. `expected` is null for a write, which
+ * read nothing and replaces whatever is there. Either way a link swapped in
+ * at the file the rename replaces (on a mount that follows links, the file
+ * the link at the agent's path led to when the call staged it) is refused
+ * rather than replaced, and so is a file this process may not write. It reads the entry the
+ * rename replaces, and then the file's bytes, synchronously, as renameInto
+ * runs, so a check and the renames after it run with no turn of the event
+ * loop between.
+ *
+ * The identity, taken once the bytes are read, catches a file replaced or
+ * re-moded under the call, which equal bytes wouldn't show. The bytes are
+ * compared with the ones the edit read: a kernel that stamps files from a
+ * coarse clock, as Linux before 6.13 does, leaves a file's identity as it
+ * was after a second write of the same size within one tick of its last
+ * change (on Debian's Linux 6.12.113 with ext4, 1,632 to 1,752 of 2,000
+ * such rewrites kept every stamp, in three runs), and the bytes show that
+ * change on every clock. The bytes are read through an open that follows
+ * no link and doesn't wait on a pipe put at the path since its lstat, and
+ * at most one byte past what the edit read, so the check never blocks and
+ * reads no more than that.
+ */
+export function checkUnchanged(staged: Staged, expected: { identity: FileIdentity; bytes: Buffer } | null): void {
+  let now: BigIntStats;
+  try {
+    now = lstatSync(staged.path, { bigint: true });
+  } catch (err) {
+    if (errno(err) !== 'ENOENT') throw new WriteRefused(`cannot check that it hadn't changed (${errno(err) ?? String(err)})`);
+    if (expected !== null) throw new FileChanged(staged.path);
+    return;
+  }
+  if (now.isSymbolicLink()) throw new WriteRefused('it became a symlink while this call was being applied');
+  if (now.isDirectory()) throw new WriteRefused('a directory');
+  if (!now.isFile()) throw new WriteRefused('not a regular file');
+  // As a push's write, which opens the file for writing, would be refused:
+  // the rename needs only the directory's permission, and would replace a
+  // file its owner made read-only.
+  try {
+    accessSync(staged.path, fsConstants.W_OK);
+  } catch (err) {
+    const code = errno(err);
+    // Removed since the lstat: a write makes the file anew; an edit's read is gone.
+    if (code === 'ENOENT') {
+      if (expected === null) return;
+      throw new FileChanged(staged.path);
+    }
+    if (code === 'EACCES' || code === 'EPERM') {
+      throw new WriteRefused(`a file the host's process may not write (${code}): its mode or owner keeps that process out, and calling again is refused until the file's owner, or whoever runs the host, changes that`);
+    }
+    throw new WriteRefused(`cannot check that the host's process may write it (${code ?? String(err)})`);
+  }
+  if (expected === null) return;
+  let bytes: Buffer;
+  let after: BigIntStats;
+  try {
+    // No link followed, and no wait on a pipe, if either was put at the path since the lstat.
+    const fd = openSync(staged.path, fsConstants.O_RDONLY | NOFOLLOW | NONBLOCK);
+    try {
+      // One byte past what the edit read, enough to see the file differs:
+      // a file another writer made larger, or a pipe a writer keeps
+      // filling, put at the path since, costs no more than that.
+      bytes = readBounded(fd, expected.bytes.length + 1);
+    } finally {
+      closeSync(fd);
+    }
+    // And the entry is still the file the edit read, after its bytes were read.
+    after = lstatSync(staged.path, { bigint: true });
+  } catch (err) {
+    // ELOOP: a link put at the path since the lstat; EAGAIN: a pipe, with a
+    // writer and nothing in it yet. Either is another writer's change.
+    if (errno(err) === 'ENOENT' || errno(err) === 'ELOOP' || errno(err) === 'EAGAIN') throw new FileChanged(staged.path);
+    throw new WriteRefused(`cannot check that it hadn't changed (${errno(err) ?? String(err)})`);
+  }
+  if (!sameIdentity(identityOf(after), expected.identity) || !bytes.equals(expected.bytes)) throw new FileChanged(staged.path);
+}
+
+/** Up to `limit` bytes from the start of `fd`, fewer at its end. */
+function readBounded(fd: number, limit: number): Buffer {
+  const buffer = Buffer.alloc(limit);
+  let filled = 0;
+  while (filled < limit) {
+    // From where the last read ended (a pipe has no positions to read at).
+    const got = readSync(fd, buffer, filled, limit - filled, null);
+    if (got === 0) break;
+    filled += got;
+  }
+  return buffer.subarray(0, filled);
+}
+
+/**
+ * Rename the staged file over the file, synchronously (checkUnchanged says
+ * why), counting the other hard links it splits the path from just before.
+ * A failed rename leaves the file as it was; the caller removes the staged
+ * file (discard).
+ */
+export function renameInto(staged: Staged): void {
+  let otherLinks: number;
+  try {
+    directWriteTestSeam.beforeRename?.(staged.path);
+    // The staged file is still the one this call wrote, not another put at its name.
+    const temp = lstatSync(staged.temp, { bigint: true });
+    if (!temp.isFile() || !sameIdentity(identityOf(temp), staged.tempIdentity)) {
+      throw new WriteRefused('another writer replaced the staged copy of the new text before it could be renamed over the file, which is as it was');
+    }
+    otherLinks = otherLinksAt(staged.path);
+    renameSync(staged.temp, staged.path);
+  } catch (err) {
+    if (err instanceof WriteRefused) throw err;
+    throw new WriteRefused(`cannot rename the staged file over it (${errno(err) ?? (err instanceof Error ? err.message : String(err))})`);
+  }
+  // Set once the rename has happened, so a count never stands for a split that didn't.
+  staged.otherLinks = otherLinks;
+}
+
+/** The other hard links of what the entry at `path` holds: 0 for none there, and when lstat fails, since the count only informs the answer. */
+function otherLinksAt(path: string): number {
+  try {
+    return lstatSync(path).nlink - 1;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Remove a staged file that won't be renamed, best effort: only the file
+ * this call staged, by its whole identity, since whatever another writer
+ * put at its name since is theirs, as renameInto leaves it too. Checked and
+ * removed synchronously, as the rename is (checkUnchanged says why).
+ */
+export async function discard(staged: Staged): Promise<void> {
+  removeIf(staged.temp, (there) => there.isFile() && sameIdentity(identityOf(there), staged.tempIdentity));
+}
+
+/** Unlink what's at `path` if `ours` says it's the file meant; best effort, with no turn of the event loop between the check and the unlink. */
+function removeIf(path: string, ours: (there: BigIntStats) => boolean): void {
+  try {
+    if (ours(lstatSync(path, { bigint: true }))) unlinkSync(path);
+  } catch {
+    // Gone already, or not ours to know: left, as the header says.
+  }
+}

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

@@ -11,8 +11,10 @@
  * and EditMany tools' answers.
  */
 
+import type { ToolResult } from '../../types/events.js';
 import { type Change, type FilePlan, type Leaves, type MatchProblem, SHOWN_MATCHES } from './edit-plan.js';
-import { MAX_LINE_CHARS, jsonLength, numberedLine, safeCut } from './text.js';
+import { answerText, fieldLine, sectionLead, sectionText, shownValue, textAnswer } from './result-text.js';
+import { MAX_LINE_CHARS, numberedLine, safeCut } from './text.js';
 
 /** The tool a call came through, which words its refusals and receipt. */
 export type EditTool = 'edit' | 'edit_many';
@@ -190,8 +192,13 @@ function label(problem: EditProblem): string {
  */
 const FIRST_LINE_MAX = 400;
 
-/** What an answer is: a refusal, whose problems the agent answers and sends again, or the answer to edits stored, which mustn't be sent again. */
-export type AnswerKind = 'refusal' | 'stored';
+/**
+ * What an answer is: a refusal, whose problems the agent answers and sends
+ * again; the answer to edits stored, which mustn't be sent again; or, on a
+ * direct mount, the answer to an edit_many call written partway, whose parts
+ * are each file's outcome.
+ */
+export type AnswerKind = 'refusal' | 'stored' | 'written';
 
 /** A line cut to FIRST_LINE_MAX, as a part's first line is, and as a thrown message is in an answer's head. */
 export function cutLine(line: string): string {
@@ -205,18 +212,25 @@ export function cutLine(line: string): string {
  * shown and send the call again to see the rest: once those are answered,
  * their room can show the rest, details included. For edits stored, the
  * problems are the files disk refused, and a last line that leaves some out
- * points to ls.
+ * points to ls. For edits written partway, they're each file's outcome, and
+ * one that leaves some out points to read.
  */
 function tailText(kind: AnswerKind, maxChars: number, cut: number, problems: number, notes: number, anyShown: boolean): string {
   const items = [
     ...(cut ? [`the details of ${cut} of these`] : []),
-    ...(problems ? [kind === 'refusal' ? `${problems} more ${plural(problems, 'problem')}` : `${problems} more ${plural(problems, 'file')} disk refused`] : []),
+    ...(problems
+      ? [kind === 'refusal'
+        ? `${problems} more ${plural(problems, 'problem')}`
+        : kind === 'stored' ? `${problems} more ${plural(problems, 'file')} disk refused` : `the outcomes of ${problems} more ${plural(problems, 'file')}`]
+      : []),
     ...(notes ? [`${notes} ${plural(notes, 'note')} on the files' copies on disk`] : []),
   ];
   if (!items.length) return '';
   const next = kind === 'stored'
     ? problems ? " ls shows each path's state." : ''
-    : problems && anyShown ? ' Answer the problems shown and send the call again to see the rest.' : '';
+    : kind === 'written'
+      ? problems ? ' Reading a file shows it as disk has it now.' : ''
+      : problems && anyShown ? ' Answer the problems shown and send the call again to see the rest.' : '';
   const list = items.length < 2 ? items[0] : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;
   return `[To keep this answer within ${maxChars.toLocaleString('en-US')} characters, it leaves out ${list}.${next}]`;
 }
@@ -271,9 +285,10 @@ export function fitted(head: string, problems: string[], notes: string[], maxCha
  * counts its problems and names each, in edit order, labelled with its edits.
  * `notes` follow the problems: which copy of a file the edits looked in, and
  * a conflict with disk, which the agent needs whether or not the call stored
- * anything.
+ * anything. On a direct mount, whose edits go to disk with no store between
+ * (`verb` 'wrote'), edit_many says it wrote none.
  */
-export function refusalText(tool: EditTool, problems: EditProblem[], notes: string[], maxChars: number): string {
+export function refusalText(tool: EditTool, problems: EditProblem[], notes: string[], maxChars: number, verb: 'stored' | 'wrote' = 'stored'): string {
   const sorted = [...problems].sort((a, b) => firstEdit(a) - firstEdit(b));
   if (tool === 'edit') {
     const [problem] = sorted;
@@ -281,7 +296,7 @@ export function refusalText(tool: EditTool, problems: EditProblem[], notes: stri
     const whole = problem!.kind === 'file' && problem!.whole ? text : `The edit did nothing: ${text}`;
     return fitted('', [whole], notes, maxChars, 'refusal');
   }
-  const head = `The edit_many call stored none of its edits: ${sorted.length} ${plural(sorted.length, 'problem')}.`;
+  const head = `The edit_many call ${verb} none of its edits: ${sorted.length} ${plural(sorted.length, 'problem')}.`;
   return fitted(head, sorted.map((problem) => `${label(problem)}${problemText(problem, tool)}`), notes, maxChars, 'refusal');
 }
 
@@ -350,7 +365,7 @@ function excerptLine(line: string, n: number, columns: number[]): string {
 
 /**
  * Each edit's first change in a file, as numbered regions merged where they
- * meet, while the budget lasts, counted as the answer's JSON holds them; past
+ * meet, while the budget lasts, counted as the answer's text holds them; past
  * it, the regions are named by their lines.
  */
 export function shownRegions(plan: FilePlan, budget: { left: number }, maxChars: number): string[] {
@@ -396,7 +411,7 @@ export function shownRegions(plan: FilePlan, budget: { left: number }, maxChars:
     // region of millions of lines, which is named by its lines, isn't built
     // whole first. The line before it ("…" between regions, or the line end)
     // counts too, and each line feed between its lines.
-    let cost = out.length ? jsonLength('\n…\n') : jsonLength('\n');
+    let cost = out.length ? '\n…\n'.length : '\n'.length;
     const lines: string[] = [];
     let fits = !omitted.length;
     for (let lineStart = region.start, n = region.from; fits && lineStart < region.end; n++) {
@@ -407,7 +422,7 @@ export function shownRegions(plan: FilePlan, budget: { left: number }, maxChars:
       // changes start on it, a stretch from shortly before each.
       const columns = text.length > MAX_LINE_CHARS ? firsts.filter((first) => first.line === n).map((first) => first.at - lineStart) : [];
       const numberedText = columns.length ? excerptLine(text, n, columns) : numberedLine(text, n);
-      cost += jsonLength(numberedText) + (lines.length ? jsonLength('\n') : 0);
+      cost += numberedText.length + (lines.length ? 1 : 0);
       if (cost > budget.left) fits = false;
       else lines.push(numberedText);
       lineStart = lineEnd + 1;
@@ -507,24 +522,56 @@ function receiptReserve(tool: EditTool, files: StoredFile[], maxChars: number):
     const listed = Math.min(SHOWN_MATCHES, plan.edits.length);
     const range = `${last}–${last}`;
     const note = regionsLeftOut(maxChars, Array.from({ length: listed }, () => range), plan.edits.length - listed, false);
-    regions = Math.max(regions, jsonLength('\n') + jsonLength(note));
+    regions = Math.max(regions, 1 + note.length);
   }
   if (tool === 'edit') return regions;
   const most = files.length;
-  return regions + jsonLength('\n\n') + jsonLength(filesLeftOut(maxChars, most, { notListed: most, unshown: most, notes: most, edits: most })!);
+  return regions + 2 + filesLeftOut(maxChars, most, { notListed: most, unshown: most, notes: most, edits: most })!.length;
+}
+
+/** A file edit_many lists, as its receipt's fields hold it. */
+interface ListedFile {
+  path: string;
+  size: number;
+  replacements: number;
+  modeKept?: string;
+  edits?: number[];
+  note?: string;
+}
+
+/** edit_many's line for a file it lists: its path, size and replacements, and then the edits, the mode kept and the notes it has room for. */
+function listedFileLine(file: ListedFile): string {
+  return `${shownValue(file.path)}: size ${file.size}, replacements ${file.replacements}`
+    + (file.edits !== undefined ? `, edits ${file.edits.join(', ')}` : '')
+    + (file.modeKept !== undefined ? `; modeKept: ${shownValue(file.modeKept)}` : '')
+    + (file.note !== undefined ? `. ${shownValue(file.note)}` : '');
+}
+
+/** edit_many's receipt's text before its changed regions: its counts, and the files it lists. */
+function manyHeadText(data: { edits: number; replacements: number; files: ListedFile[]; filesNotListed?: number }): string {
+  const header = [fieldLine('edits', data.edits), fieldLine('replacements', data.replacements)];
+  if (data.filesNotListed !== undefined) header.push(fieldLine('filesNotListed', data.filesNotListed));
+  return answerText(header, [sectionText('files', data.files.map(listedFileLine).join('\n'))]);
 }
 
 /**
  * The receipt of edits stored: each file's size, replacements and notes, and
  * each edit's first changed region, numbered as read numbers lines, held to
- * `maxChars` as the answer's JSON holds it. Its counts and notes come first;
- * the regions take what is left, and past it a file's regions are named by
- * their lines. edit_many lists its files while they fit, a file whose notes
- * don't fit without them, or without its edits' numbers too, and counts the
- * rest. edit's receipt, of one file, keeps its counts and notes and shows no
- * region where those alone pass `maxChars`.
+ * `maxChars` as the answer's text holds it (result-text.ts). Its counts and
+ * notes come first; the regions take what is left, and past it a file's
+ * regions are named by their lines. edit_many lists its files while they
+ * fit, a file whose notes don't fit without them, or without its edits'
+ * numbers too, and counts the rest. edit's receipt, of one file, keeps its
+ * counts and notes and shows no region where those leave no room for it. The
+ * line that names what a receipt leaves out comes after what it keeps, and
+ * where its counts and notes leave too little room for that line too, as
+ * they can with long notes or a limit far under the 1,000 a residence or an
+ * agent can set, the receipt passes `maxChars` by it, and then reaches its
+ * caller as any result past its limit does: a model's spills, and a script's
+ * call answers ResultTooLarge. Otherwise the model reads the text, and a
+ * script gets the receipt's fields beside it.
  */
-export function editReceipt(tool: EditTool, files: StoredFile[], editCount: number, maxChars: number): Record<string, unknown> {
+export function editReceipt(tool: EditTool, files: StoredFile[], editCount: number, maxChars: number): ToolResult {
   const reserve = receiptReserve(tool, files, maxChars);
   const notesOf = ({ plan, notes }: StoredFile): string[] => {
     const lineEnds = lineEndNote(plan);
@@ -544,28 +591,28 @@ export function editReceipt(tool: EditTool, files: StoredFile[], editCount: numb
   if (tool === 'edit') {
     const file = files[0]!;
     const notes = notesOf(file);
-    const data: Record<string, unknown> = {
+    const head = {
       path: file.path,
       size: file.plan.bytes.length,
       replacements: file.plan.replacements,
       ...(notes.length ? { note: notes.join(' ') } : {}),
       ...(file.modeKept ? { modeKept: file.modeKept } : {}),
-      changed: '',
     };
-    const budget = { left: maxChars - JSON.stringify(data).length - reserve };
-    data.changed = shownRegions(file.plan, budget, maxChars).join('\n');
-    return data;
+    const header = Object.entries(head).map(([key, value]) => fieldLine(key, value));
+    const budget = { left: maxChars - answerText(header).length - sectionLead('changed') - reserve };
+    const changed = shownRegions(file.plan, budget, maxChars).join('\n');
+    return textAnswer(answerText(header, [sectionText('changed', changed)]), { ...head, changed });
   }
-  const listed: Array<Record<string, unknown>> = [];
-  const data: Record<string, unknown> = {
+  const listed: ListedFile[] = [];
+  const data: { edits: number; replacements: number; files: ListedFile[]; filesNotListed?: number; changed: string } = {
     edits: editCount,
     replacements: files.reduce((sum, file) => sum + file.plan.replacements, 0),
     files: listed,
     changed: '',
   };
-  const fits = (entry: Record<string, unknown>) => {
+  const fits = (entry: ListedFile) => {
     listed.push(entry);
-    const fit = JSON.stringify(data).length <= maxChars - reserve;
+    const fit = manyHeadText(data).length + sectionLead('changed') <= maxChars - reserve;
     listed.pop();
     return fit;
   };
@@ -574,7 +621,7 @@ export function editReceipt(tool: EditTool, files: StoredFile[], editCount: numb
   let notListed = 0;
   for (const [i, file] of files.entries()) {
     const notes = notesOf(file);
-    const bare = {
+    const bare: ListedFile = {
       path: file.path,
       size: file.plan.bytes.length,
       replacements: file.plan.replacements,
@@ -597,22 +644,22 @@ export function editReceipt(tool: EditTool, files: StoredFile[], editCount: numb
     if (notes.length && !('note' in entry)) notesLeftOut++;
     if (!('edits' in entry)) editsLeftOut++;
   }
-  const budget = { left: maxChars - JSON.stringify(data).length - reserve };
+  const budget = { left: maxChars - manyHeadText(data).length - sectionLead('changed') - reserve };
   const sections: string[] = [];
   let unshown = 0;
   for (const file of files.slice(0, listed.length)) {
-    const heading = jsonLength(`${file.path}\n`) + (sections.length ? jsonLength('\n\n') : 0);
+    const heading = shownValue(file.path).length + 1 + (sections.length ? 2 : 0);
     if (heading >= budget.left) {
       unshown++;
       continue;
     }
     budget.left -= heading;
-    sections.push(`${file.path}\n${shownRegions(file.plan, budget, maxChars).join('\n')}`);
+    sections.push(`${shownValue(file.path)}\n${shownRegions(file.plan, budget, maxChars).join('\n')}`);
   }
   const last = filesLeftOut(maxChars, files.length, { notListed, unshown, notes: notesLeftOut, edits: editsLeftOut });
   if (last !== null) sections.push(last);
   data.changed = sections.join('\n\n');
-  return data;
+  return textAnswer(answerText([manyHeadText(data)], [sectionText('changed', data.changed)]), data);
 }
 
 const capitalized = (value: string) => value.charAt(0).toUpperCase() + value.slice(1);