@animalabs/agent-framework 0.26.2 → 0.28.0

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, type DiskState } 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; disk: DiskState; files: ListedFile[]; filesNotListed?: number }): string {
+  const header = [fieldLine('edits', data.edits), fieldLine('replacements', data.replacements), fieldLine('disk', data.disk)];
+  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, disk: DiskState): ToolResult {
   const reserve = receiptReserve(tool, files, maxChars);
   const notesOf = ({ plan, notes }: StoredFile): string[] => {
     const lineEnds = lineEndNote(plan);
@@ -544,28 +591,30 @@ 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,
+      disk,
       ...(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; disk: DiskState; files: ListedFile[]; filesNotListed?: number; changed: string } = {
     edits: editCount,
     replacements: files.reduce((sum, file) => sum + file.plan.replacements, 0),
+    disk,
     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 +623,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 +646,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);

package/src/modules/workspace/effects.ts

@@ -47,7 +47,9 @@ import type { FileHandle } from 'node:fs/promises';
 import {
   type CheckedDir,
   type MountView,
+  LEAVES_MOUNT,
   NONBLOCK,
+  NOT_A_DIRECTORY,
   NOT_FOLLOWED,
   OUTSIDE_PARENT,
   ROOT_REPLACED,
@@ -58,7 +60,6 @@ import {
   leadsInto,
   nameOf,
   coversLanding,
-  namesNestedPlace,
   nestedAtReal,
   parentOf,
 } from './observe.js';
@@ -232,7 +233,7 @@ export async function writeContained(
   createMode?: number,
 ): Promise<{ perm: number; widenRefused: boolean; modeKept: boolean }> {
   const checked = await parentFor(view, rootReal, rel, true);
-  if (checked.kind !== 'checked') throw new EffectFailed('a parent path is not a directory', false);
+  if (checked.kind !== 'checked') throw new EffectFailed(NOT_A_DIRECTORY, false);
   const parent = checked.dir;
   const root = checked.root;
   const target = parent.at(nameOf(rel));
@@ -258,8 +259,16 @@ export async function writeContained(
       touched = true;
       return handle;
     } catch (err) {
-      // O_EXCL refuses any entry: a file, a directory or a link.
-      if (errno(err) === 'EEXIST') throw new EffectFailed('something appeared at this path since it was checked', false);
+      // O_EXCL refuses any entry: a file, a directory or a link, one that
+      // leads nowhere included, which a followed observation reads as absent.
+      if (errno(err) === 'EEXIST') {
+        const link = (await lstat(target).catch(() => null))?.isSymbolicLink() === true;
+        const leads = link ? await stat(target).then(() => 'somewhere', (e: unknown) => errno(e)) : null;
+        throw new EffectFailed(leads === 'ENOENT' || leads === 'ENOTDIR'
+          ? 'a symlink that leads nowhere is at this path, and a push makes a file only where nothing is, forced or not; '
+            + 'whoever runs this host can remove the link or make it lead to a file, and a materialize then writes it'
+          : 'something appeared at this path since it was checked', false);
+      }
       throw new EffectFailed(`cannot create the file (${errno(err) ?? message(err)})`, false);
     }
   };
@@ -385,11 +394,11 @@ export async function writeContained(
  * the link is what's refused. The opened file's check (checkOpened) asks
  * it, and so does a create, before anything is made.
  */
-async function refusedLanding(view: MountView, rootReal: string, rel: string, real: string): Promise<string | null> {
-  const leaves = view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT;
+export async function refusedLanding(view: MountView, rootReal: string, rel: string, real: string): Promise<string | null> {
+  const leaves = view.followSymlinks ? LEAVES_MOUNT : OUTSIDE_PARENT;
   if (!contained(rootReal, real)) return leaves;
-  const holder = nestedAtReal(real, view.nested);
-  if (holder) return namesNestedPlace(holder.rest, holder.include, false) ? leadsInto(view.name, rel, holder) : view.followSymlinks ? leaves : NOT_FOLLOWED;
+  const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
+  if (holder) return holder.names(false) ? leadsInto(view.name, rel, holder) : view.followSymlinks ? leaves : NOT_FOLLOWED;
   if (!(await coversLanding(view, rootReal, real, rel))) return view.followSymlinks ? leaves : NOT_FOLLOWED;
   return null;
 }
@@ -566,15 +575,15 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     // The link itself is what is removed; a followed one must still lie inside.
     if (!view.followSymlinks) throw new EffectFailed(NOT_FOLLOWED, false);
     const real = await realpath(target).catch(() => null);
-    if (real === null || !contained(rootReal, real)) throw new EffectFailed('a symlink that leaves the mount', false);
+    if (real === null || !contained(rootReal, real)) throw new EffectFailed(LEAVES_MOUNT, false);
     // One leading into a nested mount's directory is that mount's: the link
     // and the file it leads to are left as they are. Where that mount's
     // include leaves the place out, it's no mount's, and the link leaves this
     // one (namesNestedPlace).
-    const holder = nestedAtReal(real, view.nested);
+    const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
     if (holder) {
-      const directory = holder.include !== undefined && await stat(real).then((s) => s.isDirectory(), () => false);
-      throw new EffectFailed(namesNestedPlace(holder.rest, holder.include, directory) ? leadsInto(view.name, rel, holder) : 'a symlink that leaves the mount', false);
+      const directory = holder.judgedByInclude && await stat(real).then((s) => s.isDirectory(), () => false);
+      throw new EffectFailed(holder.names(directory) ? leadsInto(view.name, rel, holder) : LEAVES_MOUNT, false);
     }
     const through = await stat(real, { bigint: true }).catch(() => null);
     if (through === null) throw new EffectFailed(CHANGED, false);
@@ -586,7 +595,7 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     if (!through.isFile()) throw new EffectFailed(through.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file', false);
     // One leading to a file this mount's own include leaves out leaves the
     // mount too, and that file isn't read for a hash (coversLanding).
-    if (!(await coversLanding(view, rootReal, real, rel))) throw new EffectFailed('a symlink that leaves the mount', false);
+    if (!(await coversLanding(view, rootReal, real, rel))) throw new EffectFailed(LEAVES_MOUNT, false);
     file = through;
   } else if (info.isDirectory()) {
     throw new EffectFailed('a directory', false);