@animalabs/agent-framework 0.22.2 → 0.23.0

package/src/tool-image-ledger.ts

@@ -27,6 +27,7 @@
  */
 
 import { createHash, randomBytes } from 'node:crypto';
+import { REFERENCE_STUB_MAX_CHARS, referenceTypeLabel } from './mcpl/references.js';
 import { safeSlice } from './safe-slice.js';
 
 export interface RetainedToolImage {
@@ -189,8 +190,9 @@ function mintLedgerNonce(): string {
 /** Grammar of a ref this module mints: `img_<ledger nonce>_<sequence>`. */
 export const TOOL_IMAGE_REF_RE = /^img_[0-9a-z]+_\d+$/;
 
-/** RFC 6838 type/subtype token characters (lowercased); no parameters. */
-const MEDIA_TYPE_ESSENCE_RE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
+/** RFC 6838 type/subtype token characters (lowercased), each name at most
+ *  127 characters (its section 4.2); no parameters. */
+const MEDIA_TYPE_ESSENCE_RE = /^[a-z0-9!#$&^_.+-]{1,127}\/[a-z0-9!#$&^_.+-]{1,127}$/;
 export const FALLBACK_MEDIA_TYPE = 'application/octet-stream';
 
 /**
@@ -228,21 +230,32 @@ export type ParsedImagePlaceholder =
     /** The placeholder exactly as it appears in the text. */
     text: string;
   }
-  /** An RFC-005 reference stub whose testimony says image — bytes live
+  /** An RFC-005 reference stub whose text shows an image type — bytes live
    *  behind fetch_reference, never in this ledger. Occupies a slot so the
    *  index cannot slide past it. */
   | {
     kind: 'reference';
     refId: string;
-    /** Mime sniffed from the stub text; null when the stub names none. */
-    mediaType: string | null;
+    /** The image type the stub shows, as a stub shows a type (sanitized and
+     *  bounded), lowercased: the first `image/` token in its text, which can
+     *  come from its name. */
+    mediaType: string;
     offset: number;
     /** The stub line exactly as it appears in the text. */
     text: string;
   };
 
-const PLACEHOLDER_RE = /\[image: ([a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+), (~?[\d.]+(?:B|KB|MB))(?:, ref (img_[0-9a-z]+_\d+))?\]/g;
-/** `[ref_1_ab3d] cam.png — image/png, 1.2MB claimed — from tool result — …` (one line). */
+/**
+ * `[image: image/png, ~691KB, ref img_k7x3q2_7]`. Each part is bounded by
+ * what formatToolImagePlaceholder writes, so text shaped like a placeholder
+ * but longer is no slot: a type and a subtype name at RFC 6838's 127
+ * characters each (normalizeMediaType writes none longer), and a size's
+ * number, a ledger nonce and a sequence at 16 characters each, a safe
+ * integer's digits.
+ */
+const PLACEHOLDER_RE = /\[image: ([a-z0-9!#$&^_.+-]{1,127}\/[a-z0-9!#$&^_.+-]{1,127}), (~?[\d.]{1,16}(?:B|KB|MB))(?:, ref (img_[0-9a-z]{1,16}_\d{1,16}))?\]/g;
+/** `[ref_1_ab3d] cam.png — image/png, 1.2MB claimed — from tool result — …`
+ *  (one line, at most REFERENCE_STUB_MAX_CHARS long: see parseImagePlaceholders). */
 const REFERENCE_STUB_RE = /^\[(ref_[0-9a-z]+_[0-9a-z]+)\] ([^\n]*)$/gm;
 const IMAGE_MIME_RE = /\bimage\/[a-z0-9!#$&^_.+-]+/i;
 
@@ -252,6 +265,13 @@ const IMAGE_MIME_RE = /\bimage\/[a-z0-9!#$&^_.+-]+/i;
  * untrusted — a tool result can quote someone else's placeholder verbatim —
  * so the caller MUST cross-check a resolved ref's provenance against the
  * tool_result block it was found in before handing out bytes.
+ *
+ * Decided from the text alone, so a stored result counts the same however
+ * long ago it was written, across restarts and registry evictions. A
+ * reference stub is a slot when its text shows an image type, and a
+ * non-image reference is no slot. A line shaped like a stub but longer than
+ * buildReferenceStub writes (REFERENCE_STUB_MAX_CHARS) is quoted text and no
+ * slot either, so a slot's text is bounded wherever it is kept.
  */
 export function parseImagePlaceholders(text: string): ParsedImagePlaceholder[] {
   const out: ParsedImagePlaceholder[] = [];
@@ -259,43 +279,142 @@ export function parseImagePlaceholders(text: string): ParsedImagePlaceholder[] {
     out.push({ kind: 'inline', mediaType: m[1]!, sizeLabel: m[2]!, ref: m[3] ?? null, offset: m.index ?? 0, text: m[0] });
   }
   for (const m of text.matchAll(REFERENCE_STUB_RE)) {
-    const mime = m[2]!.match(IMAGE_MIME_RE);
-    out.push({ kind: 'reference', refId: m[1]!, mediaType: mime ? mime[0].toLowerCase() : null, offset: m.index ?? 0, text: m[0] });
+    if (m[0].length > REFERENCE_STUB_MAX_CHARS) continue;
+    const shown = m[2]!.match(IMAGE_MIME_RE);
+    if (!shown) continue;
+    out.push({ kind: 'reference', refId: m[1]!, mediaType: referenceTypeLabel(shown[0]).toLowerCase(), offset: m.index ?? 0, text: m[0] });
   }
   out.sort((a, b) => a.offset - b.offset);
   return out;
 }
 
 /**
- * Cut `text` to at most `cap` chars WITHOUT losing or splitting an image
- * slot. The stored tool_result text is the only place the inventory
- * discovers tool images, while the live wire still delivers every image
- * regardless of text length — so a slot dropped by truncation is an image
- * the resident saw that the index silently slides past (the #104 failure,
- * one representation over). Returns the head to keep and the slots that
- * fell at or past the cut, to be re-appended verbatim after the truncation
- * notice. A slot straddling the cut moves the cut back to its start, so the
- * head never contains a partial slot (a partial reference-stub line would
- * otherwise still re-parse and be counted twice).
+ * The most image slots a stored copy keeps past its cut: a bound on what it
+ * carries there, set at the ledger's entry limit, the most images it holds
+ * bytes for. Serializing a result retains its images in order before their
+ * placeholders are written, and every agent's ledger is built with the
+ * defaults, so once a result is stored a save can reach bytes for at most
+ * its newest DEFAULT_TOOL_IMAGE_LEDGER_MAX_ENTRIES images, fewer when the
+ * ledger's limit on held characters binds first, and an inline image older
+ * than those can only fail. Image stubs and quoted placeholders count toward
+ * the bound too, so where they follow a result's images past the cut, the
+ * newest slots kept can leave out an image whose bytes the ledger still
+ * holds.
+ */
+export const MAX_KEPT_IMAGE_SLOTS = DEFAULT_TOOL_IMAGE_LEDGER_MAX_ENTRIES;
+
+/** The ranges `[start, end)` of a tool result's text that its live copy
+ *  showed beside its images: each text block up to where the live copy cut it
+ *  at the inline cap (toolResultCutAt), and every other block whole. They
+ *  come in text order and never overlap, as the blocks do, and
+ *  cutStoredToolResult relies on that. */
+export type ShownRanges = ReadonlyArray<readonly [number, number]>;
+
+/** A tool result's stored copy, cut at its inline cap. */
+export interface StoredCut {
+  /** The text before the cut. */
+  head: string;
+  /** The image slots past the cut that the stored copy re-appends after its
+   *  truncation notice, in text order: the newest MAX_KEPT_IMAGE_SLOTS of
+   *  those the live copy showed. */
+  kept: string[];
+  /** How many image slots past the cut the live copy showed. */
+  fell: number;
+}
+
+/**
+ * Where a tool result's text longer than `cap` is cut: by its stored copy
+ * (cutStoredToolResult), by history's own truncation (truncateForHistory),
+ * and by its live copy, for each text block beside an image
+ * (tryNativeToolResultContent, framework.ts), so the stored copy and the live
+ * copy cut alike. The text's length when it isn't longer than `cap`.
+ *
+ * The cut is made at the cap, or before it when the cap would split a
+ * surrogate pair (safeSlice's rule), and that is where the moves back are
+ * measured from. It moves back to the start of a placeholder it would split,
+ * and then to the start of a stub-shaped line it would split when at most
+ * REFERENCE_STUB_MAX_CHARS of the line lie before it, since that part could
+ * still read as a slot. So no slot straddles the cut, and the text before it
+ * never ends in part of one. A longer part, which can't parse as a slot,
+ * stays before the cut. Each move back lands on a `[`, so it splits no pair.
  */
-export function splitPreservingImageSlots(text: string, cap: number): { head: string; tail: string[] } {
-  const slots = parseImagePlaceholders(text);
-  let cutAt = cap;
-  for (const slot of slots) {
-    if (slot.offset < cutAt && slot.offset + slot.text.length > cutAt) cutAt = slot.offset;
+export function toolResultCutAt(text: string, cap: number): number {
+  if (text.length <= cap) return text.length;
+  let cutAt = safeSlice(text, 0, cap).length;
+  // Neither grammar crosses a newline, so only the line holding the cut can
+  // be split; it is read whole, as the parser reads it.
+  const lineStart = text.lastIndexOf('\n', cutAt - 1) + 1;
+  const newline = text.indexOf('\n', cutAt);
+  const line = text.slice(lineStart, newline === -1 ? text.length : newline);
+  for (const m of line.matchAll(PLACEHOLDER_RE)) {
+    const start = lineStart + (m.index ?? 0);
+    if (start < cutAt && start + m[0].length > cutAt) cutAt = start;
   }
-  return {
-    head: safeSlice(text, 0, cutAt),
-    tail: slots.filter((slot) => slot.offset >= cutAt).map((slot) => slot.text),
-  };
+  for (const m of line.matchAll(REFERENCE_STUB_RE)) {
+    const start = lineStart + (m.index ?? 0);
+    if (start < cutAt && start + m[0].length > cutAt && cutAt - start <= REFERENCE_STUB_MAX_CHARS) cutAt = start;
+  }
+  return cutAt;
 }
 
-/** Text to append after a truncation notice so the preserved slots stay
- *  parseable (each reference stub on its own line). Empty when none. */
-export function formatPreservedImageSlots(tail: string[]): string {
-  if (tail.length === 0) return '';
-  return `\n[${tail.length} image slot(s) fell past the cut; kept here in order so save_recent_image still counts them:]\n`
-    + tail.join('\n');
+/**
+ * Cut a tool result's text at its inline `cap` as its stored copy keeps it
+ * (toolResultCutAt): the stored copy keeps what the live copy showed. A text
+ * within the cap is all head, with nothing kept after it.
+ *
+ * `shown` is what the live copy showed beside the stored text: null when the
+ * live copy was the text itself, as for every result that carried no inline
+ * image. Then what the cut keeps is exactly what the resident saw, and
+ * nothing past it is kept (#403). A result that carried an inline image went
+ * to the model as native blocks (tryNativeToolResultContent, framework.ts),
+ * every image whatever the text's length, so its stored text is the only
+ * place save_recent_image's inventory finds them, and a slot dropped by the
+ * cut would be an image the resident saw that the index slides past (#104).
+ * The image slots past the cut that lie wholly within what the live copy
+ * showed are kept, the newest MAX_KEPT_IMAGE_SLOTS of them, since the
+ * inventory counts from the end.
+ */
+export function cutStoredToolResult(text: string, cap: number, shown: ShownRanges | null): StoredCut {
+  const cutAt = toolResultCutAt(text, cap);
+  const head = text.slice(0, cutAt);
+  if (shown === null) return { head, kept: [], fell: 0 };
+  // The slots and the ranges both come in text order, so one pass walks
+  // them together: a range that ends where a slot starts, or before, holds
+  // no later slot either.
+  const past: ParsedImagePlaceholder[] = [];
+  let r = 0;
+  for (const slot of parseImagePlaceholders(text)) {
+    if (slot.offset < cutAt) continue;
+    while (r < shown.length && shown[r]![1] <= slot.offset) r++;
+    const range = shown[r];
+    if (range && slot.offset >= range[0] && slot.offset + slot.text.length <= range[1]) past.push(slot);
+  }
+  return { head, kept: past.slice(-MAX_KEPT_IMAGE_SLOTS).map((slot) => slot.text), fell: past.length };
+}
+
+/** What a stored copy re-appends after its truncation notice: the kept
+ *  slots, each on its own line so a reference stub stays parseable, under a
+ *  note saying how many fell past the cut, and how many of those were left
+ *  out and aren't counted. Empty when none fell past the cut. */
+export function formatKeptImageSlots(cut: StoredCut): string {
+  if (cut.fell === 0) return '';
+  const leftOut = cut.fell - cut.kept.length;
+  const note = leftOut === 0
+    ? `${cut.fell} image slot(s) fell past the cut; kept here in order so save_recent_image still counts them:`
+    : `${cut.fell} image slot(s) fell past the cut. The last ${cut.kept.length} are kept here in order so `
+      + `save_recent_image still counts them; the ${leftOut} before them are left out, and it doesn't count them:`;
+  return `\n[${note}]\n${cut.kept.join('\n')}`;
+}
+
+/**
+ * The image slots a tool result's stored copy holds: its text's, or, when the
+ * text is longer than `cap`, those the cut keeps, in head and after the
+ * notice (cutStoredToolResult). The notice itself holds none. For counting a
+ * result before its stored copy is written, as it will count after.
+ */
+export function storedImageSlots(text: string, cap: number, shown: ShownRanges | null): ParsedImagePlaceholder[] {
+  const cut = cutStoredToolResult(text, cap, shown);
+  return parseImagePlaceholders(cut.head + formatKeptImageSlots(cut));
 }
 
 export function sha256Hex(bytes: Buffer): string {

package/src/tool-presentation.ts

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { constants, fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closestNames } from './closest-names.js';
+import { boundedErrorMessage, errorMessage } from './error-message.js';
 import type { ToolDefinition, ToolResult } from './types/events.js';
 
 export interface ToolPresentationConfig {
@@ -22,23 +24,145 @@ export interface PresentationSnapshot {
   entries: { name: string; source: string; visible: boolean; originalDescription: string; description: string; descriptionSource?: string; inputSchema: ToolDefinition['inputSchema'] }[];
 }
 const MAX_BYTES = 256 * 1024;
+/**
+ * Opened with each read of a presentation file, as observe.ts opens workspace
+ * files: a FIFO at the operator's path opens at once and fails the regular-file
+ * check, where a blocking open would hold the whole process (it's synchronous)
+ * until something opened the FIFO for writing.
+ */
+const NONBLOCK = typeof constants.O_NONBLOCK === 'number' ? constants.O_NONBLOCK : 0;
+const MAX_DESCRIPTION_CHARS = 32768;
 const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read']);
 export const isPresentationTool = (name: string): boolean => name === 'set_tool_visibility' || name === 'set_tool_description';
 const hash = (value: string): string => createHash('sha256').update(value).digest('hex');
 
-export function parsePresentation(raw: string): PresentationDocument {
-  const doc = JSON.parse(raw);
-  if (!doc || doc.version !== 1 || !doc.tools || typeof doc.tools !== 'object' || Array.isArray(doc.tools)
-      || Object.keys(doc).some(k => !['version', 'tools'].includes(k))) throw new Error('Expected {"version":1,"tools":{...}}');
-  for (const [name, value] of Object.entries(doc.tools)) {
-    if (!name || !value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid override: ${name}`);
+/**
+ * A presentation or defaults file this host can't use. Each problem is a
+ * clause about the file, such as `the entry for "x" has "visible": "no",
+ * which must be true or false`; whoever reports it names the file and says
+ * what follows from it.
+ */
+class PresentationFileError extends Error {
+  constructor(problems: string[]) {
+    const more = problems.length - 10;
+    super((more > 0 ? [...problems.slice(0, 10), `${more} more problem${more === 1 ? '' : 's'}`] : problems).join('; '));
+  }
+}
+
+/** An edit refused, in words for the agent: its message is the whole result. */
+class PresentationRefusal extends Error {}
+
+const count = (n: number): string => n.toLocaleString('en-US');
+
+/** A text's length in code points, so a character outside the Basic Multilingual Plane, such as 😀, counts once where UTF-16 counts it twice. */
+const characters = (text: string): number => [...text].length;
+
+/** A text's first `n` characters, never splitting a code point. */
+const firstCharacters = (text: string, n: number): string => [...text].slice(0, n).join('');
+
+/** A name as a message quotes it: whole up to 60 characters, and past that cut, with its length, since a file can hold a key of any size. */
+function quoted(name: string): string {
+  return characters(name) <= 60 ? JSON.stringify(name) : `${JSON.stringify(firstCharacters(name, 57))}... (${count(characters(name))} characters)`;
+}
+
+/** A file's problem as a message quotes it: its own clauses whole, and anything else bounded, since nobody wrote that text for its reader. */
+const problemText = (error: unknown): string => error instanceof PresentationFileError ? error.message : boundedErrorMessage(error);
+
+/** A value as a message quotes it: short JSON for a scalar, the kind of anything bigger. */
+function shown(value: unknown): string {
+  if (Array.isArray(value)) return 'an array';
+  if (value !== null && typeof value === 'object') return 'an object';
+  const json = JSON.stringify(value) ?? String(value);
+  return characters(json) > 40 ? `${firstCharacters(json, 37)}...` : json;
+}
+
+/** Names quoted and joined: "a", "a" and "b", "a", "b" and "c"; past ten, the first ten and how many more, since a file can hold any number of keys. Each is quoted by `quote`: quoted() by default, which cuts a file's long keys, or JSON.stringify for names the agent should copy whole. */
+function quotedList(names: string[], conjunction: 'and' | 'or' = 'and', quote: (name: string) => string = quoted): string {
+  const each = names.slice(0, 10).map((name) => quote(name));
+  if (names.length > 10) return `${each.join(', ')} ${conjunction} ${count(names.length - 10)} more`;
+  return each.length > 1 ? `${each.slice(0, -1).join(', ')} ${conjunction} ${each[each.length - 1]}` : each.join('');
+}
+
+/**
+ * Every problem that keeps a document from being used, each by where it is;
+ * none for a usable one. A defaults file (`descriptionsOnly`) may set
+ * descriptions only, since visibility is the resident's to choose.
+ */
+function documentProblems(doc: unknown, descriptionsOnly: boolean): string[] {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return [`its top level is ${shown(doc)}, not an object like {"version":1,"tools":{}}`];
+  const top = doc as Record<string, unknown>;
+  const problems: string[] = [];
+  if (top.version !== 1) problems.push(`"version" must be 1, and ${Object.hasOwn(top, 'version') ? `it is ${shown(top.version)}` : "it's missing"}`);
+  const extra = Object.keys(top).filter((key) => key !== 'version' && key !== 'tools');
+  if (extra.length) problems.push(`only "version" and "tools" belong at the top level, not ${quotedList(extra)}`);
+  const tools = top.tools;
+  if (!tools || typeof tools !== 'object' || Array.isArray(tools)) {
+    problems.push(`"tools" must be an object of tool names, and ${Object.hasOwn(top, 'tools') ? `it is ${shown(tools)}` : "it's missing"}`);
+    return problems;
+  }
+  const setsVisibility: string[] = [];
+  for (const [name, value] of Object.entries(tools)) {
+    if (!name) { problems.push('"tools" has an entry with an empty name'); continue; }
+    const entry = `the entry for ${quoted(name)}`;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) { problems.push(`${entry} is ${shown(value)}, not an object such as {"visible":false}`); continue; }
     const item = value as Record<string, unknown>;
-    if (Object.keys(item).some(k => !['description', 'visible'].includes(k))
-      || ('description' in item && (typeof item.description !== 'string' || item.description.length > 32768))
-      || ('visible' in item && typeof item.visible !== 'boolean')) throw new Error(`Invalid description/visibility for ${name}`);
-    if (protectedNames.has(name) && item.visible === false) throw new Error(`Cannot hide recovery tool ${name}`);
+    const unknown = Object.keys(item).filter((key) => key !== 'description' && key !== 'visible');
+    if (unknown.length) problems.push(`${entry} has ${quotedList(unknown)}, and an entry may have only ${descriptionsOnly ? '"description"' : '"description" and "visible"'}`);
+    if (Object.hasOwn(item, 'description')) {
+      if (typeof item.description !== 'string') problems.push(`${entry} has a "description" that is ${shown(item.description)}, not a string`);
+      else if (characters(item.description) > MAX_DESCRIPTION_CHARS) problems.push(`${entry} has a "description" of ${count(characters(item.description))} characters, over the ${count(MAX_DESCRIPTION_CHARS)} allowed`);
+    }
+    if (!Object.hasOwn(item, 'visible')) continue;
+    if (descriptionsOnly) setsVisibility.push(name);
+    else if (typeof item.visible !== 'boolean') problems.push(`${entry} has "visible": ${shown(item.visible)}, which must be true or false`);
+    else if (!item.visible && protectedNames.has(name)) problems.push(`${entry} hides it, which isn't allowed, since workspace--read, set_tool_visibility and set_tool_description are how the catalogue is read and how these settings are undone`);
   }
-  return doc;
+  if (setsVisibility.length) problems.push(`it sets "visible" for ${quotedList(setsVisibility)}, and a defaults file may set only descriptions, since visibility is yours to choose`);
+  return problems;
+}
+
+function parseDocument(raw: string, descriptionsOnly: boolean): PresentationDocument {
+  let doc: unknown;
+  try { doc = JSON.parse(raw); }
+  catch (error) { throw new PresentationFileError([`it isn't valid JSON: ${errorMessage(error)}`]); }
+  const problems = documentProblems(doc, descriptionsOnly);
+  if (problems.length) throw new PresentationFileError(problems);
+  return doc as PresentationDocument;
+}
+
+/** A resident's presentation document, or an error naming every problem that keeps it from being used. */
+export function parsePresentation(raw: string): PresentationDocument {
+  return parseDocument(raw, false);
+}
+
+/**
+ * What an agent is told when an edit fails. Every throw in `edit()` comes
+ * before its rename, and the cleanup after it never throws, so nothing was
+ * changed: a refusal says so in its own words, a file this host can't use is
+ * the host's to repair, and anything else is reported as the error it is.
+ */
+function editFailure(error: unknown): string {
+  if (error instanceof PresentationRefusal) return error.message;
+  if (error instanceof PresentationFileError) return `Nothing was changed: your tool presentation file can't be used (${error.message}), and these tools won't write over it until it's repaired. Ask whoever runs this host to repair it.`;
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  return `Nothing was changed: the edit failed (${typeof code === 'string' ? code : boundedErrorMessage(error)}). Ask whoever runs this host to check your tool presentation file and its directory.`;
+}
+
+/** Whether a path is a symbolic link, so an open that found nothing can tell a dangling link from no file. */
+function isLink(path: string): boolean {
+  try { return lstatSync(path).isSymbolicLink(); } catch { return false; }
+}
+
+/** Runs one step of an edit's cleanup, which must not throw: it returns what the step threw, if it did. */
+function tidy(step: () => void): { error: unknown } | undefined {
+  try { step(); return undefined; } catch (error) { return { error }; }
+}
+
+/** What an edit says when its lock couldn't be removed afterwards, since every later edit will meet that lock. */
+function lockLeftBehind(error: unknown): string {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  return `This edit couldn't remove its lock afterwards, the presentation file's name with .lock added${typeof code === 'string' ? ` (${code})` : ''}. `
+    + 'Until whoever runs this host removes it, set_tool_visibility and set_tool_description will be refused, saying an edit left its lock behind.';
 }
 
 export function presentationTools(path: string): ToolDefinition[] {
@@ -56,44 +180,51 @@ export class ToolPresentation {
   constructor(readonly config: ToolPresentationConfig) {}
   private read(path = this.config.path, allowMissing = true): string {
     let fd: number;
-    try { fd = openSync(path, 'r'); }
-    catch (error) { if (allowMissing && (error as NodeJS.ErrnoException).code === 'ENOENT') return '{"version":1,"tools":{}}'; throw error; }
+    try { fd = openSync(path, constants.O_RDONLY | NONBLOCK); }
+    catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') {
+        if (isLink(path)) throw new PresentationFileError(["it's a symbolic link to a file that doesn't exist"]);
+        if (allowMissing) return '{"version":1,"tools":{}}';
+        throw new PresentationFileError(["it doesn't exist"]);
+      }
+      throw new PresentationFileError([`it couldn't be opened: ${code ?? boundedErrorMessage(error)}`]);
+    }
     try {
       const stat = fstatSync(fd);
-      if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error('Presentation must be a regular file under 256 KiB');
+      if (!stat.isFile()) throw new PresentationFileError(["it isn't a regular file"]);
+      if (stat.size > MAX_BYTES) throw new PresentationFileError([`it's ${count(stat.size)} bytes, over the ${count(MAX_BYTES)} (256 KiB) this host reads`]);
       const data = Buffer.alloc(MAX_BYTES + 1);
-      let size = 0, count = 0;
-      while (size < data.length && (count = readSync(fd, data, size, data.length - size, null)) > 0) size += count;
-      if (size > MAX_BYTES) throw new Error('Presentation exceeds 256 KiB');
+      let size = 0, bytesRead = 0;
+      while (size < data.length && (bytesRead = readSync(fd, data, size, data.length - size, null)) > 0) size += bytesRead;
+      if (size > MAX_BYTES) throw new PresentationFileError([`it grew past ${count(MAX_BYTES)} bytes (256 KiB) while it was being read`]);
       return data.subarray(0,size).toString('utf8');
     } finally { closeSync(fd); }
   }
   resolve(tools: ToolDefinition[], sources: ReadonlyMap<string, string> = new Map()): PresentationSnapshot {
     let raw = '', doc: PresentationDocument = {version:1,tools:{}}, diagnostics: string[] = [];
     try { raw = this.read(); doc = parsePresentation(raw); }
-    catch (error) { diagnostics.push(`Overrides not applied: ${String(error)}. Default visibility and component descriptions retained.`); }
+    catch (error) { diagnostics.push(`Your tool presentation file can't be used (${problemText(error)}), so none of its settings apply: every tool is visible and shows its configured default description, or its installed one where none is configured. set_tool_visibility and set_tool_description won't change the file until it's repaired; ask whoever runs this host to repair it.`); }
     const defaults = new Map<string, {description: string; path: string}>();
     const configuredSources = new Set<string>();
     for (const profile of this.config.defaults ?? []) {
       if (configuredSources.has(profile.source)) {
-        diagnostics.push(`Duplicate defaults source ignored: ${profile.source}`); continue;
+        diagnostics.push(`The description defaults for ${JSON.stringify(profile.source)} are configured twice; only the first is read, and the other is ignored. Ask whoever runs this host to remove the duplicate.`); continue;
       }
       configuredSources.add(profile.source);
       // Absent components contribute neither tools nor missing-file errors.
       if (!tools.some(t => (sources.get(t.name) ?? 'Unattributed') === profile.source)) continue;
       try {
-        const profileDoc = parsePresentation(this.read(profile.path, false));
-        if (Object.values(profileDoc.tools).some(item => Object.keys(item).some(k => k !== 'description')))
-          throw new Error('Component defaults may contain descriptions only; visibility belongs to the resident');
+        const profileDoc = parseDocument(this.read(profile.path, false), true);
         for (const tool of tools) {
           if ((sources.get(tool.name) ?? 'Unattributed') !== profile.source) continue;
           const item = Object.hasOwn(profileDoc.tools, tool.name) ? profileDoc.tools[tool.name] : undefined;
           if (item?.description !== undefined) defaults.set(tool.name, {description:item.description,path:profile.path});
         }
-      } catch (error) { diagnostics.push(`Component defaults not applied (${profile.source}): ${String(error)}`); }
+      } catch (error) { diagnostics.push(`The description defaults for ${JSON.stringify(profile.source)} can't be used (${problemText(error)}), so its tools show their installed descriptions, or yours where you set one. Ask whoever runs this host to fix that defaults file.`); }
     }
     const names = new Set(tools.map(t => t.name));
-    for (const name of Object.keys(doc.tools)) if (!names.has(name)) diagnostics.push(`Not currently available: ${name}`);
+    for (const name of Object.keys(doc.tools)) if (!names.has(name)) diagnostics.push(`Not currently available: ${quoted(name)}`);
     const entries = tools.map(tool => {
       const override = Object.hasOwn(doc.tools, tool.name) ? doc.tools[tool.name] : undefined;
       // Always retain a usable discovery signpost, even when its wording is overridden.
@@ -111,39 +242,98 @@ export class ToolPresentation {
   edit(tool: string, input: unknown, available: ToolDefinition[]): ToolResult {
     const lock = this.config.path + '.lock';
     let fd: number | undefined, tempFd: number | undefined, temp: string | undefined;
+    let result: ToolResult, lockLeft: { error: unknown } | undefined;
     try {
-      if (!isPresentationTool(tool)) throw new Error('Unknown editing tool');
-      const value = input as Record<string, unknown>;
+      if (!isPresentationTool(tool)) throw new Error(`${tool} isn't a tool presentation editing tool`);
       const field = tool === 'set_tool_visibility' ? 'visible' : 'description';
-      if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.name !== 'string'
-        || Object.keys(value).some(k=> !['name',field].includes(k)) || !Object.hasOwn(value,field)) throw new Error('Invalid editing arguments');
-      if (!available.some(t=>t.name===value.name)) throw new Error('Tool is not currently available to this agent');
-      if (field === 'visible' ? typeof value.visible !== 'boolean' : value.description !== null && typeof value.description !== 'string') throw new Error(`Invalid ${field}`);
-      fd = openSync(lock, 'wx', 0o600);
+      const name = this.editedName(tool, field, input, available);
+      const value = input as Record<string, unknown>;
+      try { fd = openSync(lock, 'wx', 0o600); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        throw new PresentationRefusal("Nothing was changed: an earlier edit of your tool presentation file left its lock behind, or another edit is in progress. Call this again in a few seconds. If it fails the same way, ask whoever runs this host to remove the stale lock, the presentation file's name with .lock added, once nothing is editing the file.");
+      }
       let mode = 0o600;
-      try { const stat = lstatSync(this.config.path); if (stat.isSymbolicLink()) throw new Error('Edit the target file directly; tool editing refuses symlinks'); mode = stat.mode & 0o777; }
+      try {
+        const stat = lstatSync(this.config.path);
+        if (stat.isSymbolicLink()) throw new PresentationRefusal("Nothing was changed: your tool presentation file is a symbolic link, and these tools don't write through links. Ask whoever runs this host to make the change in the file it points to, or to replace the link with that file.");
+        mode = stat.mode & 0o777;
+      }
       catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
       const before = this.read(), doc = parsePresentation(before);
-      const old = Object.hasOwn(doc.tools,value.name) ? doc.tools[value.name] : {};
+      const old = Object.hasOwn(doc.tools,name) ? doc.tools[name] : {};
       const updated = {...old};
       if (field === 'description' && value.description === null) delete updated.description;
       else Object.assign(updated,{[field]:value[field]});
-      Object.defineProperty(doc.tools,value.name,{value:updated,enumerable:true,writable:true,configurable:true});
+      Object.defineProperty(doc.tools,name,{value:updated,enumerable:true,writable:true,configurable:true});
       const next = JSON.stringify(doc,null,2)+'\n';
+      // editedName has checked what this adds, so this can't fail on the agent's input;
+      // it keeps a gap in those checks from writing a file the host would then ignore.
       parsePresentation(next);
-      if (Buffer.byteLength(next)>MAX_BYTES) throw new Error('Presentation exceeds 256 KiB');
+      const size = Buffer.byteLength(next);
+      if (size>MAX_BYTES) throw new PresentationRefusal(`Nothing was changed: with this change your tool presentation file would be ${count(size)} bytes, ${count(size - MAX_BYTES)} over its limit of ${count(MAX_BYTES)} (256 KiB). `
+        + (field === 'description' ? 'Use a shorter description, or make room by restoring descriptions you no longer need with "description": null.' : 'Make room by restoring descriptions you no longer need with set_tool_description and "description": null.')
+        + ' Entries for tools no longer available to you can be removed only by whoever runs this host.');
       temp = this.config.path + '.' + randomUUID() + '.tmp';
       tempFd = openSync(temp,'wx',0o600);
       writeFileSync(tempFd,next);
       fchmodSync(tempFd,mode); // preserve permissions on the opened inode, never a replacement path
-      if (this.read() !== before) throw new Error('File changed concurrently; retry after reading it');
+      if (this.read() !== before) throw new PresentationRefusal('Nothing was changed: your tool presentation file changed while this edit was being made. Call this again; it applies to the file as it is now.');
       const opened = fstatSync(tempFd), named = lstatSync(temp);
       if (!named.isFile() || named.dev !== opened.dev || named.ino !== opened.ino)
-        throw new Error('Temporary file changed concurrently; retry after checking the directory');
+        throw new PresentationRefusal('Nothing was changed: the temporary copy this edit was writing was replaced while it was written. Call this again; if it fails the same way, ask whoever runs this host to check what else writes beside your tool presentation file.');
       renameSync(temp,this.config.path); temp=undefined;
-      return {success:true,data:{name:value.name,[field]:value[field],effective:'next newly compiled request',catalogue:this.config.cataloguePath}};
-    } catch (error) { return {success:false,isError:true,error:String(error)}; }
-    finally { if(tempFd!==undefined) closeSync(tempFd); if(temp) try{unlinkSync(temp);}catch{} if(fd!==undefined){closeSync(fd);unlinkSync(lock);} }
+      result = {success:true,data:{name,[field]:value[field],effective:'next newly compiled request',catalogue:this.config.cataloguePath}};
+    } catch (error) { result = {success:false,isError:true,error:editFailure(error)}; }
+    finally {
+      // After the rename the edit's result must stand, so no cleanup step may throw.
+      const tempFdToClose = tempFd, tempToRemove = temp, lockFd = fd;
+      if (tempFdToClose !== undefined) tidy(() => closeSync(tempFdToClose));
+      if (tempToRemove) tidy(() => unlinkSync(tempToRemove));
+      if (lockFd !== undefined) {
+        tidy(() => closeSync(lockFd));
+        lockLeft = tidy(() => unlinkSync(lock));
+        // A lock already gone was removed by something else, so none is left.
+        if ((lockLeft?.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') lockLeft = undefined;
+      }
+    }
+    if (!lockLeft) return result;
+    return result.success
+      ? {...result,data:{...(result.data as Record<string, unknown>),note:lockLeftBehind(lockLeft.error)}}
+      : {...result,error:`${result.error} ${lockLeftBehind(lockLeft.error)}`};
+  }
+  /**
+   * The name of the tool an edit is for, once the agent's arguments hold up;
+   * otherwise a refusal naming every problem with them and the call to make.
+   * The limits a file would refuse (a description's length, the tools that
+   * can't be hidden) are checked here too, so they read as the agent's input
+   * rather than as a problem with the file.
+   */
+  private editedName(tool: string, field: 'visible' | 'description', input: unknown, available: ToolDefinition[]): string {
+    const usage = field === 'visible'
+      ? `set_tool_visibility takes {"name": a tool's exact name, "visible": true or false}.`
+      : `set_tool_description takes {"name": a tool's exact name, "description": the new text, or null to restore the default}.`;
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new PresentationRefusal(`Nothing was changed: the arguments were ${shown(input)}, not an object. ${usage}`);
+    const args = input as Record<string, unknown>, problems: string[] = [];
+    if (!Object.hasOwn(args, 'name')) problems.push('"name" is missing');
+    else if (typeof args.name !== 'string') problems.push(`"name" is ${shown(args.name)}, not a string`);
+    if (!Object.hasOwn(args, field)) problems.push(`"${field}" is missing`);
+    else if (field === 'visible' ? typeof args.visible !== 'boolean' : args.description !== null && typeof args.description !== 'string')
+      problems.push(`"${field}" is ${shown(args[field])}, not ${field === 'visible' ? 'true or false' : 'a string or null'}`);
+    const extra = Object.keys(args).filter((key) => key !== 'name' && key !== field);
+    if (extra.length) problems.push(`${quotedList(extra)} ${extra.length > 1 ? "aren't arguments" : "isn't an argument"} of ${tool}`);
+    if (problems.length) throw new PresentationRefusal(`Nothing was changed: ${problems.join('; ')}. ${usage}`);
+    const name = args.name as string;
+    if (!available.some((t) => t.name === name)) {
+      const near = closestNames(name, available.map((t) => t.name));
+      throw new PresentationRefusal(`Nothing was changed: no tool named ${quoted(name)} is available to you.${near.length ? ` Did you mean ${quotedList(near, 'or', JSON.stringify)}?` : ''}`
+        + ` Copy the exact name from your tool catalogue's index, workspace--read {"path":${JSON.stringify(this.config.cataloguePath)},"limit":140}, reading on with "offset" if the index runs past that.`);
+    }
+    if (field === 'description' && typeof args.description === 'string' && characters(args.description) > MAX_DESCRIPTION_CHARS)
+      throw new PresentationRefusal(`Nothing was changed: the description is ${count(characters(args.description))} characters, over the ${count(MAX_DESCRIPTION_CHARS)} allowed. Shorten it and call set_tool_description again.`);
+    if (field === 'visible' && args.visible === false && protectedNames.has(name))
+      throw new PresentationRefusal(`Nothing was changed: ${name} can't be hidden, since workspace--read, set_tool_visibility and set_tool_description are how you read the catalogue and undo these changes. Calling this again won't change that.`);
+    return name;
   }
 }
 export function renderCatalogue(snapshot: PresentationSnapshot): string {
@@ -164,7 +354,8 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     `Read details: workspace--read {"path":${JSON.stringify(snapshot.cataloguePath)},"offset":LINE,"limit":LINES}.`,
     'Line references below belong to this revision; reread the index after changes.', '',
   ];
-  for (const diagnostic of snapshot.diagnostics) lines.push('Diagnostic: '+diagnostic);
+  // One line each: a quoted parse error can hold the file's own line breaks.
+  for (const diagnostic of snapshot.diagnostics) lines.push('Diagnostic: '+diagnostic.replace(/\r\n|\r|\n/g, '\\n'));
   lines.push('## Index by source', '');
   const index = new Map<string, number>();
   for (const [source, entries] of groups) {