@animalabs/agent-framework 0.28.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/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}.',

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/types/agent.ts

@@ -55,13 +55,15 @@ export interface AgentConfig {
    * Enforced at dispatch for registered agent callers; omitted means 'all'.
    * - 'all': all available tools
    * - string[]: exact tool names, including module--utility names for utilities.
-   * Utilities aren't tools of their own: an agent's model and its scripts are
-   * offered them only through 'utils', whose run checks the utility's own
-   * name. An agent that should use a utility lists both 'utils' and
-   * 'module--utility'. The name alone passes the dispatch check for any call
-   * by that name, whether the host makes it with executeToolCall on the
-   * agent's behalf or the model or a script makes it without being offered
-   * it. The slot is hidden when no utility is permitted.
+   * Utilities and the host's other rarely-used tools are in the host's
+   * built-in toolset ("settings"), out of the tool list: the model reaches
+   * them with toolsets--open {toolset:"settings"} and toolsets--act, each
+   * checked under the tool's own name. An agent that should use a utility
+   * from its model lists 'toolsets--open', 'toolsets--act' and
+   * 'module--utility' (an agent without the two meta-tools keeps every other
+   * tool in its list, but no utility). The name alone passes the dispatch
+   * check for any call by that name, whether the host makes it with
+   * executeToolCall on the agent's behalf or the model or a script makes it.
    * Trusted module calls are exempt. Genuinely unidentified public callers,
    * including unknown legacy names, remain unrestricted. Framework-created
    * identities have tool authority only while registered.
@@ -580,8 +582,9 @@ export interface InferenceRequest {
    * the turn's auto-published plain-text speech here so a single TRUNK agent
    * replies in the channel it is answering — not the process-global most-recent-
    * inbound locus, which a concurrent message elsewhere can hijack (item-3
-   * redux). Undefined for non-channel wakes (heartbeat, timers, module events),
-   * which correctly fall back to the global default channel, except an
+   * redux). Undefined for non-channel wakes (heartbeat, timers, module events).
+   * A heartbeat's turn takes no channel at all, and holds its plain speech as
+   * drafts; any other falls back to the global default channel, except an
    * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
@@ -604,6 +607,17 @@ export interface InferenceRequest {
    * it starts. Hosts don't set it.
    */
   autoContinueRun?: AutoContinueRun;
+  /**
+   * Framework-set: whether this wake's turn is a heartbeat's, which has no
+   * channel and holds its plain speech as drafts. True on a wake that
+   * continues a heartbeat's turn with no channel of its own (an autoContinue
+   * continuation, a bounce's resend wake, a ` !` continuation, and a re-arm,
+   * which copies its trigger), and on a merged batch whose causes include a
+   * heartbeat's wake and name no channel; false on a merged batch with none,
+   * so the batch's first request doesn't decide it. Unset, a wake is a
+   * heartbeat's when its `source` is `heartbeat`. Hosts don't set it.
+   */
+  heartbeatTurn?: boolean;
   /**
    * True when the triggering message explicitly addressed the agent (mention,
    * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake

package/src/types/framework.ts

@@ -218,6 +218,50 @@ export interface FrameworkConfig {
    */
   providerHold?: ProviderHoldHook;
 
+  /**
+   * Delays before a turn whose retries ran out is sent again, in ms (default
+   * `[120000, 480000, 1920000]`: 2, 8 and 32 minutes), or `false` never to.
+   * When a persistent agent's turn ends exhausted on a transient failure (a
+   * server error, an overload, a rate limit, a network failure, or a timeout
+   * membrane marks retryable and not as a deadline it reports as run out, such
+   * as a 408 or a socket's ETIMEDOUT), its trigger is queued again after the
+   * first delay, as a wake of its own. It opens where the exhausted turn's
+   * plain speech was going: its locus, where a message mid-turn may have moved
+   * it, else its trigger channel. Carrying that channel, it ranks as addressed
+   * in a merged wake's choice of channel, so a newer ambient wake from
+   * elsewhere doesn't take it; an autoContinue continuation's still yields its
+   * channel to any wake's, as it does on main; a continuation's, such as a
+   * budget restart's, names no author. A re-arm that would have to guess a
+   * channel isn't sent again: one whose turn was woken for a channel id that
+   * names no one registered channel and never found one, and whose request
+   * names none of its own. A failure that states a wait is held for that wait
+   * first, as any turn's is, and a deadline ends the turn as before, whether
+   * the host set it or membrane marks one as run out: the runtime's or
+   * undici's on a sent request, the Anthropic adapter's watchdogs, or the
+   * Anthropic SDK's timeout, which covers its connect timeout too. Until one
+   * of the re-armed turn's rounds has run or had its tool calls cut off, its
+   * failure gets no retries from the error policy: on another transient
+   * failure the next delay follows, until the list runs out, and a failure of
+   * any other kind ends the re-arming. A wake for the agent while it waits
+   * starts its turn at once, with the re-armed trigger merged in. That turn is
+   * the wake's: the error policy retries its failures. A completed turn starts
+   * the count again, and so does a message said to the agent: not a system
+   * message or notice; not an edit, reaction or deletion, unless an edit is
+   * the first version of a message the agent sees; not a message its own view
+   * leaves out, such as one a tune-out holds from it; and not the agent's own
+   * schedule, the heartbeat's tick or reminder, a self-wake timer it set, or a
+   * script's wake. A notice a module or an MCPL server stores as a message
+   * counts. A message in the residents' shared slot counts for each resident
+   * that reads it. Any other wake leaves the count going on. A re-armed turn's
+   * transient failure writes no `[inference-failed]` marker unless a round of
+   * it ran or had its tool calls cut off; any other failure of it writes one.
+   * Each counts toward the hard-down streak. Ephemeral runs and conversation
+   * forks are never re-armed. The wait and the count are kept in memory:
+   * `stop()` drops them, and so does a restart. The wait isn't a turn, so
+   * `abortInference()` doesn't end it.
+   */
+  exhaustedTurnRearmMs?: number[] | false;
+
   /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
   syncIntervalMs?: number;
 

package/src/types/module.ts

@@ -72,10 +72,11 @@ export type ModuleMessage = StoredMessage & {
    * True on a message a tune-out holds from the residents: one that arrived
    * in a tuned-out channel, stamped `metadata.tuneOut` as it came in. The
    * store keeps it, but no resident is shown the row itself: no resident's
-   * compiled view includes it, during the tune-out or after it, and a tool
-   * boundary of a turn alive when it arrived stores it without injecting it
-   * into the live turn. The subconscious reads it. Its text can still reach
-   * a resident in rows of their own, which aren't marked, such as the
+   * compiled view includes it, during the tune-out or after it, and a
+   * resident's tool boundary of a turn alive when it arrived stores it
+   * without injecting it into the live turn. The subconscious reads it. Its
+   * text can still reach a resident in rows of their own, which aren't
+   * marked, such as the
    * cancel's `<tuned-out-backlog>` row, with the text of the tune-out's newest
    * messages, up to `backlogCap` of them and as many as fit in one of the
    * residents' messages, the stored ones first and then those still held;
@@ -142,16 +143,27 @@ export interface Module {
 
   /**
    * Utilities: agent-invocable operations that deliberately do NOT get a
-   * first-class tool slot. Every tool schema taxes every inference; a
-   * capability used twice a month shouldn't. Utilities are listed, described,
-   * and invoked through the framework's single `utils` tool instead — same
-   * ToolDefinition shape, same un-prefixed names, and dispatch arrives at the
-   * SAME handleToolCall as getTools() output, so a tool migrates between
-   * surfaces by moving its definition from one list to the other and nothing
-   * else. Optional; omitting it means the module contributes no utilities.
+   * slot in the tool list. Every tool schema taxes every inference; a
+   * capability used twice a month shouldn't. Utilities belong to the host's
+   * built-in toolset ("settings"): an agent sees them with
+   * `toolsets--look {toolset:"settings"}` and calls them with
+   * `toolsets--act` once it has opened it. Same ToolDefinition shape, same
+   * un-prefixed names, and dispatch arrives at the SAME handleToolCall as
+   * getTools() output. Optional; omitting it means the module contributes no
+   * utilities.
    */
   getUtilities?(): ToolDefinition[];
 
+  /**
+   * Where one of this module's tools (a getTools() name, unprefixed) is
+   * presented: in the agent's tool list (`'header'`, the default), or in the
+   * host's built-in toolset (`'builtin'`), out of the tool list, opened with
+   * `toolsets--open {toolset:"settings"}` and called with `toolsets--act`.
+   * For tools an agent uses rarely: settings, administration, status reads.
+   * Optional; omitting it keeps every tool in the tool list.
+   */
+  toolPlacement?(toolName: string): 'header' | 'builtin' | undefined;
+
   /**
    * Handle a tool call.
    * Tool name is without module prefix.