@animalabs/agent-framework 0.27.0 → 0.29.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/thinking-drops.ts

@@ -29,10 +29,11 @@ export interface CompiledForRequest {
   recordedAfter?: number;
 }
 
-/** What a stream's driver reads a call's dropped blocks against (`StartStreamResult`'s two fields, together). */
+/** What a stream's driver reads a call's dropped blocks against (`StartStreamResult`'s fields, together). */
 export interface StreamThinkingDrops {
   place: (entries: readonly ThinkingBindingEntry[]) => PlacedDrop[];
   recordedAfter?: number;
+  branch?: string;
 }
 
 /** A signed block's identity on the wire: a thinking block's signature, a redacted block's data. */
@@ -112,26 +113,19 @@ export function splitThinkingDrops(
 /** Binding failures the context manager's record doesn't track: the account's, not the conversation's. */
 const UNTRACKED_REASONS = new Set(['organization_binding_mismatch', 'end_user_binding_mismatch']);
 
-/**
- * When an agent's unexpected drops call for an operator alert: at the first call that shows any, and again only
- * when a call shows more than the alert last counted. Each call of a stream, and each stream until a strip takes
- * them out, drops the same blocks again, so an unchanged count isn't news. A call that shows no unexpected drop, its
- * report empty, absent or naming only expected ones, ends the incident: the blocks it counted no longer drop. The next
- * one alerts afresh. It's held in memory, so a restart mid-incident alerts once more, and an agent's removal ends its
- * incident (`forget`).
- */
 export class ThinkingLossIncidents {
-  private readonly alerted = new Map<string, number>();
+  private readonly alerted = new Map<string, { count: number; scope: string | undefined }>();
 
-  /** A call's report of `unexpected` drops for `agent`: the count to alert with, or undefined for no alert. */
-  observe(agent: string, unexpected: number): number | undefined {
-    if (unexpected === 0) {
+  /** A call's report of `count` drops for `agent` in `scope`: the count to alert with, or undefined for no alert. */
+  observe(agent: string, count: number, scope?: string): number | undefined {
+    const open = this.alerted.get(agent);
+    if (count === 0) {
       this.alerted.delete(agent);
       return undefined;
     }
-    if (unexpected <= (this.alerted.get(agent) ?? 0)) return undefined;
-    this.alerted.set(agent, unexpected);
-    return unexpected;
+    if (open && open.scope === scope && count <= open.count) return undefined;
+    this.alerted.set(agent, { count, scope });
+    return count;
   }
 
   /** The agent is gone: its incident, if one is open, ends with it. */

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
@@ -67,6 +68,39 @@ function shown(value: unknown): string {
   return head;
 }
 
+function notAnObject(input: unknown, field = 'input'): string {
+  return `its ${field} must be an object, and this call gave ${withArticle(kindOf(input))}`;
+}
+
+export function markedInputRefusal(call: { name: string; unparseableInput?: string }): string | undefined {
+  const text = call.unparseableInput;
+  if (text === undefined) return undefined;
+  // When a stream ends before a call's block stops, membrane marks the call
+  // with what had arrived of its arguments: nothing, a part, or a whole
+  // 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: ${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: ${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: ${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: ${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.';
+}
+
+export function asCalled<T extends { name: string; input?: unknown; unparseableInput?: string }>(call: T): T {
+  return call.unparseableInput !== undefined && markedInputRefusal(call) === undefined ? { ...call, input: {} } : call;
+}
+
 /** A list in prose: `a`, `a or b`, `a, b or c`. */
 function oneOf(items: string[]): string {
   return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
@@ -169,7 +203,7 @@ export function toolArgsProblems(
   if (!schema) return [];
   const absent = input === undefined || input === null;
   if (!absent && (typeof input !== 'object' || Array.isArray(input))) {
-    return [`its ${options.field ?? 'input'} must be an object, and this call gave ${withArticle(kindOf(input))}`];
+    return [notAnObject(input, options.field)];
   }
   const obj = (absent ? {} : input) as Record<string, unknown>;
   const properties = (isMap(schema.properties) ? schema.properties : {}) as Record<string, { type?: unknown; nullable?: unknown; enum?: unknown } | undefined>;
@@ -183,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>)) {
@@ -202,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}.',

package/src/tool-result-guard.ts

@@ -9,6 +9,14 @@ import { resultClaimsOf, rfc005TextOf, toolResultDataToHistoryString } from './t
 import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
+export type WithheldNoticeKind = 'ran' | 'refused' | 'error';
+const GUARD_NOTICES: Record<WithheldNoticeKind, string> = {
+  ran: TOOL_RESULT_GUARD_NOTICE,
+  refused: "Tool result withheld by the guard. The tool didn't run.",
+  error: "Tool result withheld by the guard. The call returned an error, and this notice can't say whether the tool ran.",
+};
+const noticeKind = (result: CompletedToolCall['result'] | undefined): WithheldNoticeKind =>
+  result?.refused === true ? 'refused' : result?.isError === true ? 'error' : 'ran';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
 /** Where a withheld result's original went: a workspace path; the path a
@@ -54,9 +62,12 @@ export interface WithheldHost {
 }
 
 /**
- * The stub a withheld result settles to: #159's neutral notice, then where
- * the original is, then, when its tool marked any, the fields kept from its
- * result (`kept`, from keptWhenWithheld). It names no refusal and no
+ * The stub a withheld result settles to: #159's neutral notice for its
+ * `kind` (a result that isn't an error, a refused call's, or another error's),
+ * then where the original is, then, for an error whose original is in a file
+ * known written, a line telling the agent to read it, then, when its tool
+ * marked any, the fields kept from its result (`kept`, from
+ * keptWhenWithheld). It names no refusal and no
  * category (#159 keeps those in operational logs), so reading the rest back
  * is the agent's deliberate choice (agent-framework #277). The place holds
  * the result as stored, which for one over the inline cap is its capped
@@ -67,7 +78,7 @@ export interface WithheldHost {
  * save failed is still queued in memory, and a restart before its retry
  * loses it.
  */
-export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string): string {
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string, kind: WithheldNoticeKind = 'ran'): string {
   const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
   const keptIn = (only: string) => auditDurable
     ? `is kept ${only}in ${audit}`
@@ -80,8 +91,10 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
       : spill.error === undefined
         ? `Its result is in workspace file ${spill.path}.`
         : `Writing its result to workspace file ${spill.path} failed, so it ${keptIn('only ')}.`;
+  const readable = kind === 'error' && !!spill && 'path' in spill && spill.error === undefined && !spill.unfinished;
+  const readFirst = readable ? ' Read it before calling again.' : '';
   const fields = kept === undefined ? '' : ` Kept from its result: ${kept}`;
-  return `${TOOL_RESULT_GUARD_NOTICE} ${place}${fields}`;
+  return `${GUARD_NOTICES[kind]} ${place}${readFirst}${fields}`;
 }
 
 /**
@@ -140,6 +153,7 @@ interface PendingBatch {
   /** What each result's stub keeps if the batch is withheld, by its index in
    *  content: the fields its tool marked (keptWhenWithheld). */
   kept: Map<number, string>;
+  notices: Map<string, WithheldNoticeKind>;
 }
 
 interface AuditOperation {
@@ -248,7 +262,7 @@ export class ToolResultGuard {
         if (block.type === 'image') images += 1;
         else chars += JSON.stringify(block).length;
       }
-      chars -= TOOL_RESULT_GUARD_NOTICE.length;
+      chars -= GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'].length;
     }
     return Math.max(0, Math.ceil(chars / 4) + images * 1600);
   }
@@ -361,12 +375,13 @@ export class ToolResultGuard {
       // with a placeholder if the audit cannot become durable below.
       console.error(`[tool-result-guard] agent=${this.agentName} staged audit write queued:`, error);
     }
+    const results = new Map(originals.map((call) => [call.id, call.result]));
+    const notices = new Map([...results].map(([id, result]) => [id, noticeKind(result)]));
     const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
-      ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
+      ? { type: 'tool_result', toolUseId: block.toolUseId, content: GUARD_NOTICES[notices.get(block.toolUseId) ?? 'ran'], isError: block.isError }
       : block);
     // What each stub keeps if the batch is withheld, matched to its tool's
     // result by tool use id, keyed by index as the stubs and files are.
-    const results = new Map(originals.map((call) => [call.id, call.result]));
     const kept = new Map<number, string>();
     for (const [index, block] of content.entries()) {
       const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
@@ -379,7 +394,7 @@ export class ToolResultGuard {
     // which is correct since a reopened guard has no pending batch.
     const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
     this.pending = { id, messageId, content, withheld, wireResults,
-      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept };
+      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept, notices };
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -406,7 +421,7 @@ export class ToolResultGuard {
     if (pending.durable) { pending.submitted = true; return results; }
     const ids = new Set(pending.wireResults.map((result) => result.toolUseId));
     return results.map((result) => ids.has(result.toolUseId)
-      ? { ...result, content: TOOL_RESULT_GUARD_NOTICE } : result);
+      ? { ...result, content: GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'] } : result);
   }
 
   /** The stream carrying this batch ended without a clean round (abort or
@@ -603,7 +618,7 @@ export class ToolResultGuard {
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
-          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index)) }
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index), pending.notices.get(block.toolUseId)) }
           : block);
         try {
           this.append({

package/src/tune-out/coordinator.ts

@@ -15,6 +15,8 @@
  * lifecycle facts (the [Gate: …] precedent).
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
+import { cutToFit, suppliedValue } from '../supplied-text.js';
 import { randomUUID } from 'node:crypto';
 import type { ContentBlock } from '@animalabs/membrane';
 import type { StoredMessage } from '@animalabs/context-manager';
@@ -38,14 +40,14 @@ const WAKE_COALESCE_MS = 2_000;
 const EXPIRY_RETRY_MS = 60_000;
 
 /** Ends a backlog line cut to fit in one of the residents' messages. */
-const CUT_MARK = " [cut to fit; the whole message is in the channel's history]";
+const CUT_MARK = ` [${NOTICE_TAG.cutToFit}; the whole message is in the channel's history]`;
 
 /**
  * tune_out's refusal of a channel already tuned out: its settings, then what
  * its transport is now where the repeat tried to open it again (`transport`,
  * from the framework's dispatch), then how to change the settings.
  */
-export function alreadyTunedOutText(shown: string, p: TuneOutParams, transport?: string): string {
+export function alreadyTunedOutText(quoted: string, p: TuneOutParams, transport?: string): string {
   // A duration so long its end is past what a Date can hold has no time to show.
   const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
   const until = expires && Number.isFinite(expires.getTime())
@@ -53,21 +55,13 @@ export function alreadyTunedOutText(shown: string, p: TuneOutParams, transport?:
     : '';
   // A thrown error's words may end without a stop.
   const now = transport === undefined ? '' : /[.!?]$/.test(transport) ? `${transport} ` : `${transport}. `;
-  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${JSON.stringify(shown)} is already `
+  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${quoted} is already `
     + `tuned out, with cadenceSeconds ${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. `
     + now
     + 'To change those, cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call '
     + 'tune_out again with the new settings.';
 }
 
-/** The first `length` code units of `text`, one fewer where the last would be
- *  the first half of a surrogate pair. */
-function prefixOf(text: string, length: number): string {
-  const cut = text.slice(0, Math.max(0, length));
-  const last = cut.charCodeAt(cut.length - 1);
-  return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
-}
-
 /** What a thrown value says, without throwing: an Error's message, or the
  *  value as text, which String() can't give for an object with no prototype. */
 function thrownReason(error: unknown): string {
@@ -153,6 +147,10 @@ export class TuneOutCoordinator {
     return this.channelRegistry.nameShown({ serverId, channelId });
   }
 
+  private quotedShown(serverId: string, channelId: string): string {
+    return this.channelRegistry.quotedShown({ serverId, channelId });
+  }
+
   /** Restart cadence + expiry timers and re-anchor after a process restart. */
   resumeActiveEpochs(): void {
     let oldestAnchor: number | null = null;
@@ -244,14 +242,14 @@ export class TuneOutCoordinator {
     if (this.hooks.isForkBound({ serverId, channelId })) {
       return {
         ok: false,
-        error: `Nothing changed: a conversation is bound to ${JSON.stringify(this.shown(serverId, channelId))}, so its messages go to that `
+        error: `Nothing changed: a conversation is bound to ${this.quotedShown(serverId, channelId)}, so its messages go to that `
           + "conversation, and tune_out won't divert a channel while one is. Calling tune_out on it again won't change "
           + 'that until the conversation ends, which happens only once the channel has been quiet for a while. Tune '
           + 'out a different channel, or ask whoever runs this host if this one should be diverted.',
       };
     }
     const current = this.channelRegistry.getTuneOutState(serverId, channelId);
-    if (current) return { ok: false, error: alreadyTunedOutText(this.shown(serverId, channelId), current.params), alreadyTunedOut: true };
+    if (current) return { ok: false, error: alreadyTunedOutText(this.quotedShown(serverId, channelId), current.params), alreadyTunedOut: true };
     // A tool's input reaches here as the model wrote it, and the store can't
     // keep a NaN or an Infinity: its append would throw after the registry
     // had marked the channel tuned out. So each option is read as a number
@@ -337,7 +335,7 @@ export class TuneOutCoordinator {
     const ended = this.channelRegistry.cancelTuneOut(serverId, channelId, 'open', source);
     if (!ended) {
       // Its reader is the resident's tune_out: cancel_tuneout finds the channel first.
-      return { ok: false, error: this.notTunedOut(this.shown(serverId, channelId), 'you') };
+      return { ok: false, error: this.notTunedOut(this.quotedShown(serverId, channelId), 'you') };
     }
     this.clearTimers(serverId, channelId);
     this.divertedSinceInvocation.delete(this.key(serverId, channelId));
@@ -360,7 +358,7 @@ export class TuneOutCoordinator {
     // start at 0 and take them all.
     const cap = Math.floor(ended.params.backlogCap);
     const authorOf = (m: Pick<StoredMessage, 'participant' | 'metadata'>): string =>
-      (m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant;
+      suppliedValue((m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant);
     const lineOf = (m: Pick<StoredMessage, 'participant' | 'content' | 'metadata'>): string => {
       const text = m.content
         .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
@@ -370,10 +368,10 @@ export class TuneOutCoordinator {
     };
     // The channel as the resident and the subconscious are shown it.
     const name = this.shown(serverId, channelId);
-    const lifecycle = `[Tune-out: ${name} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
+    const lifecycle = `[${NOTICE_TAG.tuneOut}: ${name} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
     const render = (lines: string[], truncated: number): string => {
       const attrs = [
-        `channel="${name}"`,
+        `channel=${this.quotedShown(serverId, channelId)}`,
         `messages=${backlog.length}`,
         ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
       ];
@@ -417,7 +415,7 @@ export class TuneOutCoordinator {
       // What of the newest line's text fits beside the frame and the mark. A
       // cut shows some of it or none: a room under one character, or one
       // that would split a surrogate pair, leaves the head empty.
-      const head = prefixOf(lines.at(-1) ?? '', room - frameShowing(1) - CUT_MARK.length);
+      const head = cutToFit(lines.at(-1) ?? '', room - frameShowing(1) - CUT_MARK.length);
       if (kept === 0 && head !== '') {
         lines = [head + CUT_MARK];
         shown = shown.slice(-1);
@@ -480,7 +478,7 @@ export class TuneOutCoordinator {
         : '';
       this.hooks.addMessage(
         'user',
-        [{ type: 'text', text: `[Tune-out cancelled: ${this.shown(serverId, channelId)} — ${reason}.${truncNote}${heldNote}]` }],
+        [{ type: 'text', text: `[${NOTICE_TAG.tuneOutCancelled}: ${this.shown(serverId, channelId)} — ${reason}.${truncNote}${heldNote}]` }],
         { system: true, kind: 'tune-out-cancel-report', channelId },
         subName,
       );
@@ -664,8 +662,8 @@ export class TuneOutCoordinator {
 
     const shown = this.shown(serverId, channelId);
     const notice = trigger === 'wake'
-      ? `[Tune-out wake: ${shown} — ${count} addressed message${count === 1 ? '' : 's'}]`
-      : `[Tune-out cadence: ${shown} — ${count} diverted message${count === 1 ? '' : 's'} since your last look]`;
+      ? `[${NOTICE_TAG.tuneOutWake}: ${shown} — ${count} addressed message${count === 1 ? '' : 's'}]`
+      : `[${NOTICE_TAG.tuneOutCadence}: ${shown} — ${count} diverted message${count === 1 ? '' : 's'} since your last look]`;
     this.hooks.addMessage(
       'user',
       [{ type: 'text', text: notice }],
@@ -709,7 +707,7 @@ export class TuneOutCoordinator {
       position: 'system',
       content: [{
         type: 'text',
-        text: `[Standing dispositions]\n${entries.map(([k, v]) => `- ${k}: ${v}`).join('\n')}`,
+        text: `[${NOTICE_TAG.standingDispositions}]\n${entries.map(([k, v]) => `- ${k}: ${v}`).join('\n')}`,
       }],
     };
   }
@@ -809,7 +807,7 @@ export class TuneOutCoordinator {
         if (shared) return { success: false, error: shared, isError: true };
         const channel = named[0];
         if (!channel || !this.channelRegistry.getTuneOutState(channel.serverId, channel.channelId)) {
-          return { success: false, error: this.notTunedOut(name, 'the resident'), isError: true };
+          return { success: false, error: this.notTunedOut(JSON.stringify(name), 'the resident'), isError: true };
         }
         const note = typeof input.text === 'string' && input.text.trim() ? input.text.trim() : undefined;
         const result = this.cancel(channel.serverId, channel.channelId, 'subconscious', 'subconscious judgment', note);
@@ -874,7 +872,7 @@ export class TuneOutCoordinator {
   }
 
   /**
-   * A cancel of a channel that isn't tuned out, by the name the caller gave
+   * A cancel of a channel that isn't tuned out, by the name, quoted, the caller gave
    * or knows it by: which channels are, so the next call can name one, and
    * how a tune-out ends without one. `backlogTo`
    * names the resident as the message's reader knows it: "you" to the
@@ -884,11 +882,11 @@ export class TuneOutCoordinator {
    * neither this list nor the name's lookup (channelsNamed, which reads the
    * registered channels too), and the text claims nothing about it.
    */
-  private notTunedOut(name: string, backlogTo: 'you' | 'the resident'): string {
-    const active = this.listActive().map((e) => JSON.stringify(this.shown(e.serverId, e.channelId)));
+  private notTunedOut(quoted: string, backlogTo: 'you' | 'the resident'): string {
+    const active = this.listActive().map((e) => this.quotedShown(e.serverId, e.channelId));
     const opening = active.length === 0
       ? 'no connected channel is tuned out now.'
-      : `no connected channel ${JSON.stringify(name)} is tuned out. Connected channels tuned out now: `
+      : `no connected channel ${quoted} is tuned out. Connected channels tuned out now: `
         + `${active.join(', ')}.`;
     return `Nothing was cancelled: ${opening} A tune-out also ends by itself when its duration runs out, or at the `
       + `first wake past its wake budget, and its backlog goes to ${backlogTo} then.`;

package/src/tune-out/tools.ts

@@ -113,7 +113,10 @@ export interface SubconsciousConfig {
    * agent-prefixed identifier.
    */
   name?: string;
-  /** Model id; defaults to the primary agent's (same-model side-process). */
+  /** Model id; defaults to the primary agent's (same-model side-process).
+   *  Another id, compared exactly, makes the subconscious leave out the
+   *  fields that describe the primary's model, its window and its thinking
+   *  binding (SUBCONSCIOUS_MODEL_FIELDS); nothing here sets its own. */
   model?: string;
   /**
    * The voice/criteria mode block — recipe-side and co-authored with the