@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/supplied-text.ts

@@ -0,0 +1,154 @@
+/**
+ * Text the framework didn't write (what a participant or a server supplied),
+ * put beside structure of the framework's own: the reply judge's document,
+ * and notices the framework writes. A value that can end its line can start
+ * a line that reads as the framework's own.
+ */
+
+import { CONTEXT_MANAGER_TAGS, MEMBRANE_TAGS, NOTICE_TAG } from './notice-tags.js';
+
+/** Every form of line break a reader might take for one: CR LF, CR, LF,
+ *  vertical tab, form feed, NEL, and the Unicode line and paragraph separators. */
+const LINE_BREAK = /\r\n|[\r\n\u000b\u000c\u0085\u2028\u2029]/g;
+
+/** Text with each line break, in whatever form, as `\n`. */
+export function normalizeLineBreaks(text: string): string {
+  return text.replace(LINE_BREAK, '\n');
+}
+
+/** A value kept to one line: each run of line breaks, in whatever form, as one
+ *  space, so it can't end the line it's put in or start one of its own. */
+export function oneLine(text: string): string {
+  return normalizeLineBreaks(text).replace(/\n+/g, ' ');
+}
+
+const INVISIBLE = '\\p{Cf}\\p{Default_Ignorable_Code_Point}';
+const SKIPPED = `[\\s\\p{Cc}${INVISIBLE}]`;
+const tagWord = (word: string): string =>
+  [...word].map((c) => (/[\\^$.*+?()[\]{}|/]/.test(c) ? `\\${c}` : c)).join(`${SKIPPED}*`);
+const NOTICE_OPENING = new RegExp(
+  `\\[(?=${SKIPPED}*(?:${[...Object.values(NOTICE_TAG), ...CONTEXT_MANAGER_TAGS, ...MEMBRANE_TAGS].map((tag) => tag.split(' ').map(tagWord).join(`${SKIPPED}+`)).join('|')})(?![\\p{L}\\p{N}]))`,
+  'giu',
+);
+
+/**
+ * Texts read as one string, joined by line breaks, with a backslash put
+ * before the bracket of each opening of a listed tag (NOTICE_TAG,
+ * CONTEXT_MANAGER_TAGS, MEMBRANE_TAGS) that hasn't one before it in its own
+ * text. A text `marks` says false of is read and never changed.
+ *
+ * Every opening, not only one that starts a line: membrane's XML formatter
+ * writes `participant: ` before each message, so the framework's own
+ * openings stand mid-line there too. It joins a message's text blocks with
+ * line breaks and sets its images apart from that text, while the native
+ * formatter sends each block on its own, so an opening split across a
+ * message's text blocks is one either way. In any case, by Unicode's case folding, and
+ * through whitespace, control and invisible characters anywhere inside the
+ * bracket, which a model reads past.
+ */
+export function markedTexts(texts: readonly string[], marks: readonly boolean[] = []): string[] {
+  const starts: number[] = [];
+  let at = 0;
+  for (const text of texts) {
+    starts.push(at);
+    at += text.length + 1;
+  }
+  const offsets: number[][] = texts.map(() => []);
+  for (const match of texts.join('\n').matchAll(NOTICE_OPENING)) {
+    let holder = texts.length - 1;
+    while (starts[holder]! > match.index) holder--;
+    const offset = match.index - starts[holder]!;
+    if (marks[holder] !== false && texts[holder]![offset - 1] !== '\\') offsets[holder]!.push(offset);
+  }
+  return texts.map((text, i) => withMarks(text, offsets[i]!));
+}
+
+function withMarks(text: string, offsets: readonly number[]): string {
+  let marked = '';
+  let from = 0;
+  for (const offset of offsets) {
+    marked += `${text.slice(from, offset)}\\`;
+    from = offset;
+  }
+  return marked + text.slice(from);
+}
+
+function closedWithin(text: string, at: number): boolean {
+  let depth = 0;
+  for (let i = at; i < text.length; i++) {
+    if (text[i] === '[') depth++;
+    else if (text[i] === ']' && --depth === 0) return true;
+  }
+  return false;
+}
+
+function unmarkedOpenings(text: string): number[] {
+  return [...text.matchAll(NOTICE_OPENING)].map((match) => match.index).filter((at) => text[at - 1] !== '\\');
+}
+
+export function markedText(text: string): string {
+  return markedTexts([text])[0]!;
+}
+
+export function markNoticeOpenings<T extends object>(blocks: readonly T[], marks: (index: number) => boolean = () => true): T[] {
+  const at: number[] = [];
+  blocks.forEach((block, index) => {
+    const { type, text } = (block ?? {}) as { type?: unknown; text?: unknown };
+    if (type === 'text' && typeof text === 'string') at.push(index);
+  });
+  const textOf = (index: number): string => (blocks[index] as unknown as { text: string }).text;
+  const marked = markedTexts(at.map(textOf), at.map(marks));
+  const out = [...blocks];
+  at.forEach((index, i) => {
+    if (marked[i] !== textOf(index)) out[index] = { ...blocks[index]!, text: marked[i] };
+  });
+  return out;
+}
+
+export function suppliedValue(value: unknown): string {
+  return markedText(oneLine(String(value)));
+}
+
+export function cutToFit(text: string, length: number): string {
+  let end = Math.max(0, Math.floor(length));
+  if (end >= text.length) return text;
+  for (;;) {
+    const last = text.charCodeAt(end - 1);
+    if (end < text.length && last >= 0xd800 && last <= 0xdbff) end--;
+    else if (text[end - 1] === '\\' && text[end] === '[') end--;
+    else {
+      const cut = text.slice(0, end);
+      const open = unmarkedOpenings(cut).find((at) => !closedWithin(cut, at));
+      if (open === undefined) return cut;
+      end = open;
+    }
+  }
+}
+
+export function showsAsItself(value: string): boolean {
+  return value !== '' && suppliedValue(value) === value && value.isWellFormed() && !EDGE_OR_QUOTE.test(value);
+}
+
+const EDGE_OR_QUOTE = /^\s|\s$|["\\]/;
+
+export function quotedValue(value: unknown, space?: number): string {
+  return (JSON.stringify(value, null, space) ?? 'null').replace(/"(?:[^"\\]|\\.)*"/g, (literal) => quotedString(JSON.parse(literal)));
+}
+
+function quotedString(text: string): string {
+  let quoted = '';
+  let from = 0;
+  for (const match of text.matchAll(NOTICE_OPENING)) {
+    quoted += `${jsonText(text.slice(from, match.index))}\\u005b`;
+    from = match.index + 1;
+  }
+  return `"${quoted}${jsonText(text.slice(from))}"`;
+}
+
+// JSON.stringify leaves NEL, U+2028 and U+2029 as they are.
+const jsonText = (text: string): string =>
+  JSON.stringify(text).slice(1, -1).replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+
+export function nameToTypeBack(name: string): string {
+  return showsAsItself(name) ? name : quotedValue(name);
+}

package/src/tool-args.ts

@@ -1,3 +1,4 @@
+import { nameToTypeBack, quotedValue } from './supplied-text.js';
 import type { ToolDefinition } from './types/index.js';
 
 /** A run of 16 or more digits, which membrane's XML parser passes as text for
@@ -79,20 +80,20 @@ export function markedInputRefusal(call: { name: string; unparseableInput?: stri
   // object. A block still open when a stream breaks the API's block order
   // is marked the same way, and one that had stopped with its object's JSON,
   // so the arguments may be another call's (ToolUseContent.unparseableInput).
-  if (/^[ \t\n\r]*$/.test(text)) return `Nothing was done: ${call.name} its arguments never arrived; call it again with them whole.`;
+  if (/^[ \t\n\r]*$/.test(text)) return `Nothing was done: ${nameToTypeBack(call.name)} its arguments never arrived; call it again with them whole.`;
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
   } catch {
-    return `Nothing was done: ${call.name} its arguments must be one JSON object, and this call gave text that isn't JSON, which may have been cut off: ${shown(text)}; call it again with one JSON object.`;
+    return `Nothing was done: ${nameToTypeBack(call.name)} its arguments must be one JSON object, and this call gave text that isn't JSON, which may have been cut off: ${shown(text)}; call it again with one JSON object.`;
   }
   if (parsed === null) return undefined;
-  if (typeof parsed !== 'object' || Array.isArray(parsed)) return `Nothing was done: ${call.name} ${notAnObject(parsed)}.`;
-  return `Nothing was done: ${call.name} its arguments came in a response that didn't arrive whole and in order, so they can't be taken as this call's; call it again.`;
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) return `Nothing was done: ${nameToTypeBack(call.name)} ${notAnObject(parsed)}.`;
+  return `Nothing was done: ${nameToTypeBack(call.name)} its arguments came in a response that didn't arrive whole and in order, so they can't be taken as this call's; call it again.`;
 }
 
 export function cutOffRefusal(call: { name: string }): string {
-  return `Nothing was done: ${call.name} didn't run, because the response it was in was cut off at the output limit. ` +
+  return `Nothing was done: ${nameToTypeBack(call.name)} didn't run, because the response it was in was cut off at the output limit. ` +
     'To make the call, send less in one response: shorter text before it, shorter arguments, or fewer calls at once.';
 }
 
@@ -216,7 +217,7 @@ export function toolArgsProblems(
     const kinds = admittedKinds(declared(key));
     if (value !== undefined && (value !== null || takesNull(declared(key)))) continue;
     missing.add(key);
-    const wanted = kinds.length > 0 ? `"${key}" (${oneOf(kinds.map(withArticle))})` : `"${key}"`;
+    const wanted = kinds.length > 0 ? `${quotedValue(key)} (${oneOf(kinds.map(withArticle))})` : quotedValue(key);
     problems.push(`needs ${wanted}, and this call gave ${value === null ? 'null' : 'none'}`);
   }
   if (missing.size > 0 && declaresKeysPlainly(schema as Record<string, unknown>)) {
@@ -235,11 +236,11 @@ export function toolArgsProblems(
     const kind = kindOf(value);
     const largeInteger = kind === 'string' && kinds.includes('number') && LARGE_INTEGER_TEXT.test(value as string);
     if (kinds.length > 0 && !kinds.includes(kind) && !largeInteger) {
-      problems.push(`"${key}" must be ${oneOf(kinds.map(withArticle))}, and this call gave ${withArticle(kind)}`);
+      problems.push(`${quotedValue(key)} must be ${oneOf(kinds.map(withArticle))}, and this call gave ${withArticle(kind)}`);
       continue;
     }
     if (Array.isArray(param.enum) && !param.enum.includes(value)) {
-      problems.push(`"${key}" must be one of ${oneOf(param.enum.map(shown))}, and this call gave ${shown(value)}`);
+      problems.push(`${quotedValue(key)} must be one of ${oneOf(param.enum.map((e) => quotedValue(e)))}, and this call gave ${shown(value)}`);
     }
   }
   return problems;

package/src/tool-image-ledger.ts

@@ -26,6 +26,7 @@
  * of bytes from another surface is the failure this exists to end.
  */
 
+import { NOTICE_TAG } from './notice-tags.js';
 import { createHash, randomBytes } from 'node:crypto';
 import { REFERENCE_STUB_MAX_CHARS, referenceTypeLabel } from './mcpl/references.js';
 import { safeSlice } from './safe-slice.js';
@@ -256,7 +257,7 @@ export type ParsedImagePlaceholder =
 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 REFERENCE_STUB_RE = new RegExp(`^\\[(${NOTICE_TAG.referenceId}_[0-9a-z]+_[0-9a-z]+)\\] ([^\\n]*)$`, 'gm');
 const IMAGE_MIME_RE = /\bimage\/[a-z0-9!#$&^_.+-]+/i;
 
 /**

package/src/tool-presentation.ts

@@ -32,7 +32,8 @@ const MAX_BYTES = 256 * 1024;
  */
 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']);
+// The toolsets meta-tools are how a hidden tool is reached again, so they stay.
+const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read', 'toolsets--open', 'toolsets--act', 'toolsets--look', 'toolsets--close']);
 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');
 
@@ -175,7 +176,7 @@ function lockLeftBehind(error: unknown): string {
 }
 
 export function presentationTools(path: string): ToolDefinition[] {
-  const signpost = ` Read the generated catalogue with workspace--read {"path":${JSON.stringify(path)},"limit":140}. Hidden tools remain available; changes affect the next newly compiled request, not an in-flight stream.`;
+  const signpost = ` Read the generated catalogue with workspace--read {"path":${JSON.stringify(path)},"limit":140}. A hidden tool moves out of your tool list into the host's "settings" toolset (an MCPL server's tool, into that server's tab): toolsets--look lists it there, and toolsets--act calls it once that toolset is open. Changes affect the next newly compiled request, not an in-flight stream.`;
   return [
     {name:'set_tool_visibility', description:'Show or hide a tool definition. Hiding does not revoke permission.' + signpost,
       inputSchema:{type:'object',properties:{name:{type:'string'},visible:{type:'boolean'}},required:['name','visible'],additionalProperties:false}},
@@ -341,7 +342,7 @@ export class ToolPresentation {
     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.`);
+      throw new PresentationRefusal(`Nothing was changed: ${name} can't be hidden, since workspace--read, set_tool_visibility, set_tool_description and the toolsets-- tools are how you read the catalogue, reach hidden tools and undo these changes. Calling this again won't change that.`);
     return name;
   }
 }
@@ -356,7 +357,7 @@ export function renderCatalogue(snapshot: PresentationSnapshot): string {
     '# Tool catalogue — generated from currently available tools', '',
     `Revision: ${snapshot.revision}`, '',
     `${snapshot.entries.length} tools: ${visible} visible, ${snapshot.entries.length-visible} hidden.`,
-    'Visible = supplied in new requests. Hidden = stored away, still available.',
+    'Visible = not hidden by you: in your tool list, unless the host keeps it in its "settings" toolset or a server\'s tab (toolsets--look shows those). Hidden = moved into the "settings" toolset, or its MCPL server\'s tab: toolsets--look shows it, toolsets--act calls it once that toolset is open.',
     'These are your visibility choices, not fixed primary/secondary rankings.',
     'Copy exact names from the index; similar-sounding names may not exist.',
     'Show a hidden tool: set_tool_visibility {"name":"EXACT_NAME","visible":true}.',