@animalabs/agent-framework 0.22.1 → 0.22.3

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 { 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,138 @@ export interface PresentationSnapshot {
   entries: { name: string; source: string; visible: boolean; originalDescription: string; description: string; descriptionSource?: string; inputSchema: ToolDefinition['inputSchema'] }[];
 }
 const MAX_BYTES = 256 * 1024;
+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[] {
@@ -57,43 +174,50 @@ export class ToolPresentation {
   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; }
+    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 +235,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 +347,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) {

package/src/tool-result-guard.ts

@@ -3,8 +3,8 @@ import { isDeepStrictEqual } from 'node:util';
 import type { ContextManager, MessageId, MessageMetadata } from '@animalabs/context-manager';
 import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
 import type { CompletedToolCall } from './types/index.js';
-import { isStateExistsError } from './module-registry.js';
-import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { ensureStateRegistered } from './module-registry.js';
+import { rfc005TextOf, toolResultDataToHistoryString } from './tool-result-history.js';
 import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
@@ -101,7 +101,10 @@ export function keptWhenWithheld(result: CompletedToolCall['result'], maxChars:
   const fields = data as Record<string, unknown>;
   const kept = Object.fromEntries(keys.filter((key) => Object.hasOwn(fields, key)).map((key) => [key, fields[key]]));
   if (Object.keys(kept).length === 0) return undefined;
-  const whole = toolResultDataToHistoryString(kept);
+  // Data that RFC-005 shows as text, such as a reference's stub, keeps that
+  // text: picked out of it, a kept uri would lose the type that makes it a
+  // reference, and be written out of the stub that hides it.
+  const whole = rfc005TextOf(fields) ?? toolResultDataToHistoryString(kept);
   if (!maxChars || whole.length <= maxChars) return whole;
   // Never half a surrogate pair: the stub goes to the provider as text, so
   // the cut can be one character short of the cap.
@@ -295,11 +298,7 @@ export class ToolResultGuard {
   private write(record: Record<string, unknown>): void {
     const store = this.cm.getStore();
     if (!this.registered) {
-      try {
-        store.registerState({ id: TOOL_RESULT_GUARD_AUDIT_STATE, strategy: 'append_log' });
-      } catch (error) {
-        if (!isStateExistsError(error)) throw error;
-      }
+      ensureStateRegistered(store, { id: TOOL_RESULT_GUARD_AUDIT_STATE, strategy: 'append_log' });
       this.registered = true;
     }
     store.appendToStateJson(TOOL_RESULT_GUARD_AUDIT_STATE, record);

package/src/tool-result-history.ts

@@ -11,11 +11,24 @@
  *
  * For MCP-shaped content arrays, this helper keeps text blocks verbatim and
  * replaces image blocks with a short `[image: mimeType, ~NKB]` placeholder.
- * For anything else it falls back to JSON.
+ * For anything else it falls back to JSON, written by RFC-005's rules at
+ * every depth (historyJson): a reference is shown as its stub wherever it
+ * sits in the data, so its uri never reaches history, and inline data that
+ * claims a uri or a disposition is withheld.
  */
 
 import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './mcpl/references.js';
-import { formatPreservedImageSlots, formatToolImagePlaceholder, splitPreservingImageSlots } from './tool-image-ledger.js';
+import { NON_STRING_TEXT_PLACEHOLDER } from './mcpl/visible-content.js';
+import { formatToolImagePlaceholder, toolResultCutAt } from './tool-image-ledger.js';
+
+/** Where one block of a content array sits in its history text, and what
+ *  kind of block it was: text, an inline image (its placeholder), an RFC-005
+ *  reference (its stub), or inline data withheld for a contradiction. */
+export interface HistoryBlockSpan {
+  kind: 'text' | 'image' | 'reference' | 'withheld';
+  start: number;
+  end: number;
+}
 
 export interface HistorySerializeOptions {
   /**
@@ -25,6 +38,13 @@ export interface HistorySerializeOptions {
    * handle in history; null leaves the legacy ref-less form.
    */
   imageRef?: (blockIndex: number, image: { data: string; mimeType: string }) => string | null;
+  /**
+   * Called once a content array has been serialized block by block, rather
+   * than given up on for the fallback, with where each block sits in the
+   * joined text, before any cut at `maxChars`. The framework reads from it
+   * what a result's live copy showed (#403).
+   */
+  onBlocks?: (spans: HistoryBlockSpan[]) => void;
 }
 
 /**
@@ -54,7 +74,7 @@ export function toolResultDataToHistoryString(
   const fromArray = tryHistoryStringFromContentArray(data, options);
   // JSON leaves out undefined, a function and a symbol: a result with no data
   // is stored as no text, as an empty content array is.
-  const str = fromArray ?? (JSON.stringify(data) as string | undefined) ?? '';
+  const str = fromArray ?? historyJson(data) ?? '';
   return maxChars ? truncateForHistory(str, maxChars) : str;
 }
 
@@ -80,52 +100,136 @@ export function nonErrorResultText(
   return toolResultDataToHistoryString(data, maxChars, options);
 }
 
-/** Bounded copy of an arbitrary string with the standard truncation notice.
- *  Image slots past the cut are re-appended, never dropped (issue #104). */
+/** Bounded copy of an arbitrary string with the standard truncation notice,
+ *  cut at the cap as a tool result's stored copy is (toolResultCutAt), so it
+ *  never ends in part of a slot. Each of its callers' readers sees this
+ *  very text, never the images behind a placeholder, so nothing past the cut
+ *  is kept for save_recent_image's index (#403). The framework stores a tool
+ *  result with spillOrTruncate, which keeps the slots past its cut that the
+ *  result's live copy showed. */
 export function truncateForHistory(str: string, maxChars: number): string {
   if (str.length <= maxChars) return str;
-  const { head, tail } = splitPreservingImageSlots(str, maxChars);
-  return head
-    + '\n\n[truncated — original was ' + str.length + ' chars]'
-    + formatPreservedImageSlots(tail);
+  return str.slice(0, toolResultCutAt(str, maxChars)) + '\n\n[truncated — original was ' + str.length + ' chars]';
 }
 
 /**
  * If `data` is an MCP content array whose every block has a shape we
  * recognize, return a history-safe string (images → placeholders). Otherwise
- * return `null` to defer to the caller's fallback (JSON, usually).
+ * return `null` to defer to the fallback, historyJson, which shows a
+ * reference anywhere in the data as its stub.
  */
 function tryHistoryStringFromContentArray(data: unknown, options?: HistorySerializeOptions): string | null {
   if (!Array.isArray(data)) return null;
-  const parts: string[] = [];
+  const parts: Array<{ kind: HistoryBlockSpan['kind']; text: string }> = [];
   for (const [blockIndex, raw] of data.entries()) {
     if (!raw || typeof raw !== 'object') return null;
     const b = raw as { type?: unknown; text?: unknown; data?: unknown; mimeType?: unknown };
-    if (b.type === 'text' && typeof b.text === 'string') {
-      parts.push(b.text);
+    if (b.type === 'text') {
+      // A text that isn't a string shows as the converters' placeholder,
+      // rather than sending the whole array to the JSON fallback.
+      parts.push({ kind: 'text', text: typeof b.text === 'string' ? b.text : NON_STRING_TEXT_PLACEHOLDER });
     } else if (isInlineContradiction(b)) {
       // RFC-005 vector 2: checked before the data branch so inline data
       // claiming bulk disposition is withheld, not rendered.
-      parts.push(INLINE_WITHHELD_TEXT);
+      parts.push({ kind: 'withheld', text: INLINE_WITHHELD_TEXT });
     } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
       // Decoded byte estimate from base64 length (3/4 ratio, rounded).
       const approxBytes = Math.floor(b.data.length * 3 / 4);
       const ref = options?.imageRef?.(blockIndex, { data: b.data, mimeType: b.mimeType }) ?? null;
-      parts.push(formatToolImagePlaceholder(b.mimeType, formatSize(approxBytes), ref));
+      parts.push({ kind: 'image', text: formatToolImagePlaceholder(b.mimeType, formatSize(approxBytes), ref) });
     } else if (b.type === 'resource' || ((b.type === 'image' || b.type === 'audio') && typeof (b as { uri?: unknown }).uri === 'string')) {
       // RFC-005 reference block: a bounded stub, never the raw block JSON
       // (which used to inline the URI — and the whole array — into history).
-      // Image-typed stubs still occupy a slot in save_recent_image's
-      // inventory (a failing one — bytes live behind fetch_reference), so
-      // the index never slides past an image the resident saw.
+      // A stub that shows an image type occupies a slot in
+      // save_recent_image's inventory (a failing one — bytes live behind
+      // fetch_reference), so the index never slides past an image the
+      // resident saw.
       const stub = referenceStubOrNull(b, 'from tool result');
       if (stub === null) return null;
-      parts.push(stub);
+      parts.push({ kind: 'reference', text: stub });
     } else {
       return null;
     }
   }
-  return parts.join('\n');
+  if (options?.onBlocks) {
+    const spans: HistoryBlockSpan[] = [];
+    let start = 0;
+    for (const part of parts) {
+      spans.push({ kind: part.kind, start, end: start + part.text.length });
+      start += part.text.length + 1; // the newline that joins them
+    }
+    options.onBlocks(spans);
+  }
+  return parts.map((part) => part.text).join('\n');
+}
+
+/**
+ * Whether RFC-005 governs a value of a tool result's data, wherever it sits.
+ * A reference is a `resource` with a uri, at its top level or under
+ * `resource` (where MCP embeds a resource's uri), or an `image` or `audio`
+ * given by uri; inline data is an `image` or `audio` whose data is a string.
+ * A uri that is null, absent or empty counts as none, and data that isn't a
+ * string isn't inline data, so a record that only shares one of those type
+ * names is data. A uri of any other value, string or not, counts, so a
+ * credential fails closed.
+ */
+function governedByRfc005(b: Record<string, unknown>): boolean {
+  if (b.type === 'resource') return hasUri(b.uri) || (isPlainRecord(b.resource) && hasUri(b.resource.uri));
+  if (b.type === 'image' || b.type === 'audio') return typeof b.data === 'string' || hasUri(b.uri);
+  return false;
+}
+
+function hasUri(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== '';
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A value of a tool result's data as history shows it, by RFC-005's rules,
+ * wherever it sits in the data. A value RFC-005 governs (governedByRfc005) is
+ * shown as the reference lanes show it: a reference as its stub, an invalid
+ * one (such as a uri that isn't a string, or MCP's embedded resource, whose
+ * uri isn't at its top level) as an unrecognized-block line, and inline data
+ * that also claims a uri or a disposition as withheld, so no uri is ever
+ * shown. Inline data that claims neither is itself, as is any other value:
+ * a block of another type keeps its fields, a `resource_link`'s uri among
+ * them, since RFC-005 governs references.
+ */
+function shownInHistory(value: unknown): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  const b = value as Record<string, unknown>;
+  if (!governedByRfc005(b)) return value;
+  if ((b.type === 'image' || b.type === 'audio') && typeof b.data === 'string') {
+    // JSON writes every field, so here inline data beside a uri of any value
+    // is withheld, not only beside a string one as in the lanes, which show
+    // no uri: an object can carry a credential. An empty uri carries none.
+    return hasUri(b.uri) || b.disposition !== undefined ? INLINE_WITHHELD_TEXT : value;
+  }
+  return referenceStubOrNull(b, 'from tool result') ?? value;
+}
+
+/**
+ * The text RFC-005 shows a value of a tool result's data as, when it shows it
+ * as text rather than as its fields: a reference's stub, an invalid one's
+ * unrecognized-block line, or inline data withheld. Null for any other value.
+ */
+export function rfc005TextOf(value: unknown): string | null {
+  const shown = shownInHistory(value);
+  return shown !== value && typeof shown === 'string' ? shown : null;
+}
+
+/**
+ * JSON of a tool result's data with each value in it shown as history shows
+ * it (shownInHistory), at any depth. Data that is itself shown as text, such
+ * as a bare reference, is that text.
+ */
+function historyJson(data: unknown): string | undefined {
+  const root = shownInHistory(data);
+  if (root !== data && typeof root === 'string') return root;
+  return JSON.stringify(data, (_key, value: unknown) => shownInHistory(value)) as string | undefined;
 }
 
 function formatSize(bytes: number): string {