@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/mcpl/skip-reply-wake.ts

@@ -43,6 +43,41 @@ export function readSkipReplyWake(input: unknown): SkipReplyWake {
   return { kind: 'wake', seconds: Math.floor(Math.min(SKIP_REPLY_WAKE_MAX_SECONDS, seconds)) };
 }
 
+/**
+ * A wake the heartbeat has due before a skip_reply's self-wake: its next tick
+ * or a reminder, one the agent's rules would let wake it as they stand when
+ * the self-wake is armed. `what` names it to the agent ("your heartbeat
+ * (…)"); `inSeconds` is how far off it is then.
+ */
+export interface SkipReplyEarlierWake {
+  inSeconds: number;
+  what: string;
+}
+
+/**
+ * The note a skip_reply's result carries: that the turn ended, and, when the
+ * agent set a wake, when it fires unless something wakes the agent first.
+ * When the heartbeat has a wake due sooner, the note adds it, and what it
+ * would mean: any turn start cancels a pending self-wake
+ * (EventGate.onInferenceStarted), so a timer the agent still wants after the
+ * heartbeat's turn is one it sets again then, for the time that was left.
+ *
+ * It says when the heartbeat is due, not that it will wake the agent: the
+ * rules can change before then, a rate limit can have no token left, a
+ * gate.js or a host's inference policy can hold the wake back, and a batch or
+ * a queued request can wake the agent sooner. Each of those leaves the note
+ * true.
+ */
+export function skipReplyNote(selfWakeSeconds: number | undefined, earlier?: SkipReplyEarlierWake): string {
+  if (selfWakeSeconds === undefined) return 'Turn ended; nothing sent.';
+  const note = `Turn ended; nothing sent. Self-wake in ~${selfWakeSeconds}s unless something wakes you first.`;
+  if (earlier === undefined) return note;
+  const what = earlier.what.charAt(0).toUpperCase() + earlier.what.slice(1);
+  const left = Math.max(1, selfWakeSeconds - earlier.inSeconds);
+  return `${note} ${what} is due sooner, in ~${earlier.inSeconds}s; if it wakes you, the self-wake is cancelled, `
+    + `so set it again for the ~${left}s left if you still want it.`;
+}
+
 /** The refusal the model reads when its host has no EventGate to set a timer. */
 export const SKIP_REPLY_WAKE_NO_GATE_REFUSAL =
   "Your turn didn't end, and no wake was set: this host can't wake you on a timer, so skip_reply can't take wake_in_seconds here. To end the turn and wait for the next message, call skip_reply without it. Anything you meant to come back to, do now.";

package/src/mcpl/tags.ts

@@ -21,8 +21,10 @@ const CORE_IMPLIES: Readonly<Record<string, readonly string[]>> = {
 /**
  * RFC-001 core tags that mark a message as being ABOUT the conversation
  * rather than part of it: reactions (added or removed), edits and deletions
- * of an existing message. These are markers, not turns — they must not clear
- * explicit-send suppression, count as a new conversational round, or
+ * of an existing message, and (revision 3) `chat:system` notices from the
+ * platform or the place: a join, a pin, the weather changing in a world.
+ * These are markers, not turns — they must not clear explicit-send
+ * suppression, count as a new conversational round, or
  * retarget the default publish channel. An edit can also be the first
  * version of a message the agent sees, and then counts as that message:
  * isMarkerTagged reads the host's mark for the case the coalescer knows
@@ -36,6 +38,7 @@ export const NON_CONVERSATIONAL_TAGS: ReadonlySet<string> = new Set([
   'chat:reaction-remove',
   'chat:edited',
   'chat:deleted',
+  'chat:system',
 ]);
 
 /** True when a (possibly untyped) tag list carries a non-conversational marker tag. */
@@ -54,11 +57,19 @@ export function isMarkerTagged(tags: unknown, firstView: boolean): boolean {
   return hasNonConversationalTag(firstView && Array.isArray(tags) ? tags.filter((t) => t !== 'chat:edited') : tags);
 }
 
+/** True when a (possibly untyped) tag list marks a `chat:system` notice: an
+ *  event about the place, not a message anyone sent (RFC-001 rev 3). */
+export function isSystemNotice(tags: unknown): boolean {
+  return Array.isArray(tags) && tags.includes('chat:system');
+}
+
 /**
  * Expand a raw tag list over the normative core closure, then resolve the
  * §16.2 mutual exclusion: `chat:addressed` and `chat:ambient` cannot both
  * stand after expansion, and addressed wins — a message that is both
  * specifically-to-you and background noise is specifically-to-you.
+ * `chat:system` is another facet (kind, not addressing) and stands beside
+ * either: a pin in a DM is addressed by its place and still a notice.
  *
  * Pure; input order is preserved for the tags that survive, with implied
  * tags appended in first-cause order. Unknown and producer-namespaced tags

package/src/mcpl/tool-presence.ts

@@ -25,7 +25,8 @@
  *
  * Ported from mcpl-cc-bridge's presence.ts, the reference host.
  */
-import { objectSignature, renderToolLines, toolDigest, type HintedTool } from './tool-signature.js';
+import { objectSignature, renderToolLines, toolDigest, type HintedTool, type Shown } from './tool-signature.js';
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 
 export interface ToolsetDecl {
   title?: string;
@@ -69,15 +70,20 @@ export interface Change {
   /** The visible tools after the change. */
   now: HintedTool[];
 }
-export interface ChangeSet { changes: Change[]; suggest: Suggestion[]; notes: string[] }
+export interface ChangeSet {
+  changes: Change[];
+  suggest: Suggestion[];
+  notes: string[];
+  /** Ended records' notes, by id: rendered while the id is untold, told once the set reaches an agent (markTold). */
+  ended?: Array<{ id: string; note: string }>;
+  /** false when its taker showed the change without its blocks (a look that restates the present shows the live catalog instead): told() then counts none of its definitions shown, while a notice that tells it still shows them. */
+  blocksShown?: false;
+}
 
 export const emptyChange = (): ChangeSet => ({ changes: [], suggest: [], notes: [] });
-export const isEmptyChange = (c: ChangeSet): boolean => !c.changes.length && !c.suggest.length && !c.notes.length;
-export const joinChanges = (...sets: ChangeSet[]): ChangeSet => ({
-  changes: sets.flatMap((s) => s.changes),
-  suggest: sets.flatMap((s) => s.suggest),
-  notes: sets.flatMap((s) => s.notes),
-});
+export const isEmptyChange = (c: ChangeSet): boolean => !c.changes.length && !c.suggest.length && !c.notes.length && !c.ended?.length;
+/** Whether a change to one key shows that key's tools in a block: what render prints and markShown counts as shown. */
+const showsBlock = (c: Change): boolean => !c.closed && (c.opened || c.appeared.length > 0 || c.redefined.length > 0 || c.gone.length > 0);
 
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const arr = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
@@ -90,7 +96,7 @@ const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v
  *           the last + 1 (a message was lost unread): recover.
  *  behind:  at or below the last, not applied: recover.
  */
-export interface ApplyOutcome { applied: boolean; skipped: boolean; behind: boolean; suggest: Suggestion[] }
+export interface ApplyOutcome { applied: boolean; skipped: boolean; behind: boolean; suggest: Suggestion[]; unlisted: boolean }
 
 /** What a hint `definition` may change (RFC §6.1): everything else stays the listed tool's. */
 interface DefOverride { description?: string; inputSchema?: Record<string, unknown>; annotations?: Record<string, unknown> }
@@ -117,10 +123,10 @@ export class ToolPresence {
   private visible = new Map<string, Set<string>>();
   /** Definition overrides from hints: per key (an instance's own, or a toolset's), per tool. */
   private defs = new Map<string, Map<string, DefOverride>>();
-  /** `ended` ids told to the agent: once per id, across reconnects (RFC §5.3). */
+  /** `ended` ids told to the agent, kept while the server still reports them (RFC §5.3). */
   private toldEnded = new Set<string>();
+  /** Moves a tools/list made that the model's tool list doesn't show yet: told once a rebuild has published them. */
   private pendingMoves = new Map<string, Presence>();
-  private moved = new Map<string, Presence>();
   /** Digests of definitions the model has been shown with their first sentence. */
   readonly shown = new Set<string>();
 
@@ -132,6 +138,8 @@ export class ToolPresence {
     private readonly allowed: (tool: string) => boolean = () => true,
     /** How a static tool is named in the API tool list, for `look`. */
     private readonly listedName: (tool: string) => string = (tool) => tool,
+    /** Where the model's published tool list last put a tool, if it's there (shownAs). */
+    private readonly published: (tool: string) => Presence | undefined = () => undefined,
   ) {}
 
   // ── connection lifecycle ──
@@ -166,6 +174,7 @@ export class ToolPresence {
       }
     }
     this.declared = decl;
+    for (const name of Object.keys(decl)) this.groups.delete(name);
     this.surface = mcpl && isObj(mcpl.surface) ? { title: str(mcpl.surface.title), summary: str(mcpl.surface.summary) } : null;
     // RFC §5.1: removing a toolset, or turning its instances on or off, ends
     // its open instances; one that becomes undeclared starts closed under the
@@ -190,21 +199,35 @@ export class ToolPresence {
     this.visible.clear();
     this.defs.clear();
     this.pendingMoves.clear();
-    this.moved.clear();
   }
 
   /** tools/list: every definition, visible or not (RFC §4.1). A tool the host's policy refuses is left out. */
   setTools(list: HintedTool[]): void {
-    this.tools = new Map(list
-      .filter((t) => isObj(t) && typeof t.name === 'string' && this.allowed(t.name))
-      .map((t) => [t.name, t]));
+    const seen = new Map([...this.tools.keys()].map((name) => [name, this.presenceOf(name)]));
+    const named = list.filter((t) => isObj(t) && typeof t.name === 'string');
+    this.tools = new Map();
+    for (const t of named) if (this.allowed(t.name) && !this.tools.has(t.name)) this.tools.set(t.name, t);
     for (const set of this.visible.values()) for (const n of [...set]) if (!this.tools.has(n)) set.delete(n);
+    // RFC §4.1: the list states each tool's presence, and presence follows
+    // it. A changed presence is a move the model's tool list shows at its
+    // next rebuild (§4.2; applyMoves); one the list reverses before then
+    // never reached that list.
+    for (const name of [...this.pendingMoves.keys()]) if (!this.tools.has(name)) this.pendingMoves.delete(name);
+    for (const name of this.active ? this.tools.keys() : []) {
+      const was = seen.get(name);
+      const listed = this.listedPresence(name);
+      if (this.pendingMoves.has(name)) {
+        if (this.pendingMoves.get(name) !== listed) this.pendingMoves.delete(name);
+      } else if (was !== undefined && was !== listed) {
+        this.pendingMoves.set(name, listed);
+      }
+    }
     // The list's `mcpl/visible` is the server's word only where nothing else
     // speaks: toolset-less dynamic tools and undeclared groups. For a declared
     // toolset it's an aggregate ("visible in some open instance"); per-instance
     // state comes from toolsets/list and hint changes (RFC §4.1, §5.3).
     for (const t of this.tools.values()) {
-      if (this.presenceOf(t.name) !== 'dynamic') continue;
+      if (this.listedPresence(t.name) !== 'dynamic') continue;
       const ts = this.toolsetOf(t.name);
       if (ts && this.isDeclared(ts)) continue;
       this.setVisible(keyOf(ts ?? NO_TOOLSET), t.name, t._meta?.['mcpl/visible'] !== false);
@@ -234,12 +257,23 @@ export class ToolPresence {
     return m && typeof m['mcpl/toolset'] === 'string' && m['mcpl/toolset'] ? (m['mcpl/toolset'] as string) : undefined;
   }
 
-  /** static unless hinted dynamic; a toolset wins over any "static" (RFC §4.1); a move applies only at a boundary (applyMoves). */
+  /** As the list states it: a toolset's tool is dynamic whatever a hint says (RFC §4.1). */
   presenceOf(name: string): Presence {
     if (!this.active) return 'static';
+    return this.listedPresence(name);
+  }
+
+  /** RFC §4.2: "Until it applies the move, the tool keeps working where it
+   *  is." Whether a tool is at `place` in the tool list last published, or
+   *  in the server's latest tools/list (its presence). Until a rebuild
+   *  applies a move the two differ, and a call is taken at either. */
+  shownAs(name: string, place: Presence): boolean {
+    if (!this.active) return place === 'static';
+    return this.published(name) === place || this.listedPresence(name) === place;
+  }
+
+  private listedPresence(name: string): Presence {
     if (this.toolsetOf(name)) return 'dynamic';
-    const moved = this.moved.get(name);
-    if (moved) return moved;
     return this.tools.get(name)?._meta?.['mcpl/presence'] === 'dynamic' ? 'dynamic' : 'static';
   }
 
@@ -332,12 +366,12 @@ export class ToolPresence {
 
   /** Apply a HintChanges (RFC §6.1) from any of its carriers, as it is read (see ApplyOutcome). */
   apply(h: unknown): ApplyOutcome {
-    const none: ApplyOutcome = { applied: false, skipped: false, behind: false, suggest: [] };
+    const none: ApplyOutcome = { applied: false, skipped: false, behind: false, suggest: [], unlisted: false };
     if (!isObj(h) || typeof h.rev !== 'number' || !Number.isFinite(h.rev)) return none;
     if (h.rev <= this.rev) return { ...none, behind: true };
     const skipped = h.rev !== this.rev + 1;
     this.rev = h.rev;
-    return { ...none, applied: true, skipped, suggest: this.applyBody(h) };
+    return { ...none, applied: true, skipped, ...this.applyBody(h) };
   }
 
   /**
@@ -352,7 +386,8 @@ export class ToolPresence {
     return lost;
   }
 
-  private applyBody(h: Record<string, unknown>): Suggestion[] {
+  private applyBody(h: Record<string, unknown>): { suggest: Suggestion[]; unlisted: boolean } {
+    let unlisted = false;
     for (const e of arr(h.toolsets)) {
       if (!isObj(e) || !str(e.toolset) || !this.isDeclared(e.toolset as string)) continue; // undeclared toolsets are host-local
       const ts = e.toolset as string;
@@ -366,20 +401,20 @@ export class ToolPresence {
       else if (e.state === 'closed') this.dropKey(key);
     }
     for (const e of arr(h.tools)) {
-      if (!isObj(e) || !str(e.name) || !this.tools.has(e.name as string)) continue;
+      if (!isObj(e) || !str(e.name)) continue;
       const name = e.name as string;
-      // A toolset's tool is dynamic whatever a hint says (RFC §4.1).
-      if ((e.presence === 'static' || e.presence === 'dynamic') && !this.toolsetOf(name)) {
-        // RFC §4.2: a move applies at a boundary the host chooses; until then the tool stays where it is.
-        if (e.presence !== this.presenceOf(name)) this.pendingMoves.set(name, e.presence);
-        else this.pendingMoves.delete(name);
+      if (!this.tools.has(name)) {
+        if (this.allowed(name)) unlisted = true;
+        continue;
       }
-      if (isObj(e.definition) && this.presenceOf(name) === 'dynamic') {
+      // A hint's presence stages nothing: a hinted move takes effect when
+      // the server's tools/list states it (RFC §4.1), as the rebuild's own
+      // list does. A definition it gives is the tool's current one, kept
+      // whatever its presence now, for when it's shown dynamic (§6.1).
+      if (isObj(e.definition)) {
         const key = this.defKeyFor(name, str(e.instance));
-        if (key !== null) {
-          if (!this.defs.has(key)) this.defs.set(key, new Map());
-          this.defs.get(key)!.set(name, overrideOf(e.definition));
-        }
+        if (!this.defs.has(key)) this.defs.set(key, new Map());
+        this.defs.get(key)!.set(name, overrideOf(e.definition));
       }
       if (typeof e.visible === 'boolean') for (const key of this.keysFor(name, str(e.instance))) this.setVisible(key, name, e.visible);
     }
@@ -388,14 +423,14 @@ export class ToolPresence {
       if (!isObj(s) || !str(s.toolset) || (s.action !== 'open' && s.action !== 'close')) continue;
       suggest.push({ toolset: s.toolset as string, ...(str(s.instance) ? { instance: str(s.instance) } : {}), action: s.action, reason: str(s.reason) ?? '' });
     }
-    return suggest;
+    return { suggest, unlisted };
   }
 
   /**
    * Where a definition lands (RFC §6.1): with `instance`, that instance's own;
    * without, the toolset's (for a toolset without instances, its only one's).
    */
-  private defKeyFor(name: string, instance: string | undefined): string | null {
+  private defKeyFor(name: string, instance: string | undefined): string {
     const ts = this.toolsetOf(name);
     if (!ts) return keyOf(NO_TOOLSET);
     return keyOf(ts, this.declared[ts]?.instances ? instance : undefined);
@@ -445,7 +480,7 @@ export class ToolPresence {
    * Returns what was lost, what the server says ended while no connection was
    * told, its suggestions, and whether its rev skipped one.
    */
-  adopt(result: unknown): { lost: OpenRecord[]; ended: Ended[]; suggest: Suggestion[]; skipped: boolean } {
+  adopt(result: unknown): { lost: OpenRecord[]; ended: Ended[]; suggest: Suggestion[]; skipped: boolean; unlisted: boolean } {
     const had = [...this.open.values()];
     // A full statement: a dynamic tool not stated visible is invisible.
     // Undeclared groups stay as the host has them open or closed.
@@ -463,9 +498,10 @@ export class ToolPresence {
     }
     let suggest: Suggestion[] = [];
     let skipped = false;
+    let unlisted = false;
     const h = isObj(r._meta) ? r._meta['mcpl/hints'] : undefined;
     if (isObj(h)) {
-      suggest = this.applyBody(h);
+      ({ suggest, unlisted } = this.applyBody(h));
       // Its own rev, at its place in order (RFC §6.1).
       if (typeof h.rev === 'number' && Number.isFinite(h.rev)) {
         skipped = h.rev !== this.rev + 1;
@@ -477,29 +513,51 @@ export class ToolPresence {
       if (!isObj(e) || !str(e.toolset)) continue;
       ended.push({ ...(str(e.id) ? { id: str(e.id) } : {}), toolset: e.toolset as string, ...(str(e.instance) ? { instance: str(e.instance) } : {}), reason: str(e.reason) ?? '' });
     }
-    return { lost: had.filter((o) => !this.open.has(keyOf(o.toolset, o.instance))), ended, suggest, skipped };
+    // RFC §5.3: a record is reported on every toolsets/list until it expires, and its id is never
+    // reused, so an id the server no longer reports needn't be remembered.
+    const reported = new Set(ended.flatMap((e) => (e.id ? [e.id] : [])));
+    for (const id of [...this.toldEnded]) if (!reported.has(id)) this.toldEnded.delete(id);
+    return { lost: had.filter((o) => !this.open.has(keyOf(o.toolset, o.instance))), ended, suggest, skipped, unlisted };
   }
 
   /**
    * What the agent should hear about an adoption: what ended while it was
-   * away, each `ended` id once however often the server repeats it (RFC
-   * §5.3), and what is closed now.
+   * away, each `ended` id until it has been told (RFC §5.3; markTold), and
+   * what is closed now. An ended record with an id is in `ended`, rendered
+   * while its id is untold.
    */
-  adoptionNotes(lost: OpenRecord[], ended: Ended[]): string[] {
+  adoptionNotes(lost: OpenRecord[], ended: Ended[]): { notes: string[]; ended: Array<{ id: string; note: string }> } {
     const notes: string[] = [];
-    const endedKeys = new Set(ended.map((e) => keyOf(e.toolset, e.instance)));
+    const told: Array<{ id: string; note: string }> = [];
+    const endedKeys = new Set<string>();
     for (const e of ended) {
+      if (!e.id || !this.toldEnded.has(e.id)) endedKeys.add(keyOf(e.toolset, e.instance));
+      const note = `${this.label(keyOf(e.toolset, e.instance))} ended${e.reason ? `: ${suppliedValue(e.reason)}` : ''}.`;
       if (e.id) {
-        if (this.toldEnded.has(e.id)) continue;
-        this.toldEnded.add(e.id);
-      }
-      notes.push(`${this.label(keyOf(e.toolset, e.instance))} ended${e.reason ? `: ${e.reason}` : ''}.`);
+        if (!this.toldEnded.has(e.id)) told.push({ id: e.id, note });
+      } else notes.push(note);
     }
     for (const o of lost) {
       if (endedKeys.has(keyOf(o.toolset, o.instance))) continue;
       notes.push(`${this.label(keyOf(o.toolset, o.instance))} is closed: ${this.server} no longer has it open. ${this.openHint(o.toolset)} starts a new one.`);
     }
-    return notes;
+    return { notes, ended: told };
+  }
+
+  /** The agent has been told these ended records (a notice written, a result it reads); the next statement forgets any it no longer reports. */
+  markTold(ended: ChangeSet['ended']): void {
+    for (const { id } of ended ?? []) this.toldEnded.add(id);
+  }
+
+  /** The definitions a change set's tool blocks describe have reached the model. */
+  markShown(cs: ChangeSet): void {
+    for (const c of cs.changes) if (showsBlock(c)) for (const t of c.now) this.shown.add(toolDigest(t));
+  }
+
+  /** A set's ended notes whose ids are still untold, each once. */
+  untoldNotes(cs: ChangeSet): string[] {
+    const seen = new Set<string>();
+    return (cs.ended ?? []).filter(({ id }) => !this.toldEnded.has(id) && !seen.has(id) && !!seen.add(id)).map(({ note }) => note);
   }
 
   // ── host-made opens of undeclared groups (RFC §5.4) ──
@@ -514,15 +572,15 @@ export class ToolPresence {
 
   // ── boundaries ──
 
-  /** Apply pending static↔dynamic moves (RFC §4.2) at a boundary the host chooses. Returns what moved. */
-  applyMoves(): Array<{ name: string; to: Presence }> {
-    const out: Array<{ name: string; to: Presence }> = [];
-    for (const [name, to] of this.pendingMoves) {
-      if (!this.tools.has(name)) continue;
-      this.moved.set(name, to);
-      out.push({ name, to });
-    }
-    this.pendingMoves.clear();
+  /** The static↔dynamic moves the lists made since the last rebuild, still to be shown. */
+  moves(): Array<{ name: string; to: Presence }> {
+    return [...this.pendingMoves].map(([name, to]) => ({ name, to }));
+  }
+
+  /** At a rebuild of the model's tool list (RFC §4.2): those of `moves` still pending, now shown. */
+  applyMoves(moves = this.moves()): Array<{ name: string; to: Presence }> {
+    const out = moves.filter(({ name, to }) => this.pendingMoves.get(name) === to);
+    for (const { name } of out) this.pendingMoves.delete(name);
     return out;
   }
 
@@ -531,60 +589,67 @@ export class ToolPresence {
   /** The marker a key's announcements begin with, `[server/toolset:instance]`, which a reminder looks for. */
   label(key: string): string {
     const { toolset, instance } = splitKey(key);
-    return `[${this.server}${toolset ? `/${toolset}` : ''}${instance ? `:${instance}` : ''}]`;
+    return `[${this.server}${toolset ? `/${nameToTypeBack(toolset)}` : ''}${instance ? `:${nameToTypeBack(instance)}` : ''}]`;
   }
 
   callHint(key: string): string {
     const { instance } = splitKey(key);
-    return `${this.names.act} {server:"${this.server}"${instance ? `, instance:"${instance}"` : ''}, tool, args}`;
+    return `${this.names.act} {server:"${this.server}"${instance ? `, instance:${quotedValue(instance)}` : ''}, tool, args}`;
   }
 
   closeHint(key: string): string | null {
     const { toolset, instance } = splitKey(key);
     if (!toolset) return null;
-    return `${this.names.close} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    return `${this.names.close} {server:"${this.server}", toolset:${quotedValue(toolset)}${instance ? `, instance:${quotedValue(instance)}` : ''}}`;
   }
 
   openHint(toolset: string, instance?: string): string {
-    return `${this.names.open} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${instance}"` : ''}}`;
+    return `${this.names.open} {server:"${this.server}", toolset:${quotedValue(toolset)}${instance ? `, instance:${quotedValue(instance)}` : ''}}`;
   }
 
   /** The tool block for one key: its label, how to call, and the visible tools (new or changed ones described). */
-  toolBlock(key: string, tools: HintedTool[], opts: { describeAll?: boolean; headed?: boolean; title?: string } = {}): string[] {
-    const head = opts.headed === false ? '' : `${this.label(key)}${opts.title ? ` ${opts.title}` : ''} `;
+  toolBlock(key: string, tools: HintedTool[], opts: { describeAll?: boolean; headed?: boolean; title?: string; seen?: Shown } = {}): string[] {
+    const head = opts.headed === false ? '' : `${this.label(key)}${opts.title ? ` ${suppliedValue(opts.title)}` : ''} `;
     if (!tools.length) return [`${head}no tools available right now.`];
-    return [`${head}tools now — ${this.callHint(key)}:`, ...renderToolLines(tools, this.shown, { describeAll: opts.describeAll })];
+    return [`${head}tools now — ${this.callHint(key)}:`, ...renderToolLines(tools, opts.seen ?? this.shown, { describeAll: opts.describeAll })];
   }
 
-  /** What the model reads for a change set. `bare`: a key whose header the caller already printed. */
-  render(cs: ChangeSet, opts: { bare?: string } = {}): string {
+  /**
+   * What the model reads for a change set. `bare`: a key whose header the
+   * caller already printed. `mark: false` renders without counting the
+   * definitions it describes as shown, for text that may not reach the model
+   * (markShown counts them once it has). `describeAll`: every tool with its
+   * first sentence, as for a result that may reach no agent.
+   */
+  render(cs: ChangeSet, opts: { bare?: string; mark?: boolean; describeAll?: boolean } = {}): string {
+    const local = new Set<string>();
+    const seen: Shown = opts.mark === false ? { has: (d) => this.shown.has(d) || local.has(d), add: (d) => { local.add(d); } } : this.shown;
     const lines: string[] = [];
     for (const c of cs.changes) {
       const bare = opts.bare === c.key;
       if (c.closed) {
-        lines.push(`${this.label(c.key)} closed.${c.gone.length ? ` Now unavailable: ${c.gone.join(', ')}.` : ''}`);
+        lines.push(`${this.label(c.key)} closed.${c.gone.length ? ` Now unavailable: ${c.gone.map(suppliedValue).join(', ')}.` : ''}`);
         continue;
       }
       const title = (c.opened || c.retitled) && !bare ? c.title : undefined;
-      const setChanged = c.opened || c.appeared.length > 0 || c.redefined.length > 0 || c.gone.length > 0;
-      if (setChanged) lines.push(...this.toolBlock(c.key, c.now, { headed: !bare, title }));
-      else if (title) lines.push(`${this.label(c.key)} ${title}`);
-      if (c.gone.length) lines.push(`now unavailable: ${c.gone.join(', ')}`);
+      if (showsBlock(c)) lines.push(...this.toolBlock(c.key, c.now, { headed: !bare, title, seen, describeAll: opts.describeAll }));
+      else if (title) lines.push(`${this.label(c.key)} ${suppliedValue(title)}`);
+      if (c.gone.length) lines.push(`now unavailable: ${c.gone.map(suppliedValue).join(', ')}`);
       if (c.opened && !bare) {
         const close = this.closeHint(c.key);
         if (close) lines.push(`${close} closes it.`);
       }
     }
     for (const s of cs.suggest) lines.push(this.renderSuggestion(s));
-    lines.push(...cs.notes);
+    lines.push(...this.untoldNotes(cs), ...cs.notes);
     return lines.join('\n');
   }
 
   /** RFC §6.2: a suggestion is shown, never acted on. */
   renderSuggestion(s: Suggestion): string {
-    const what = `${s.toolset}${s.instance ? `:${s.instance}` : ''}`;
+    const what = suppliedValue(`${s.toolset}${s.instance ? `:${s.instance}` : ''}`);
     const how = s.action === 'open' ? this.openHint(s.toolset, s.instance) : this.closeHint(keyOf(s.toolset, s.instance));
-    return `${this.server} suggests ${s.action === 'open' ? 'opening' : 'closing'} ${what}${s.reason ? `: ${s.reason}` : ''} — ${how} if you want to (nothing was done).`;
+    return `${this.server} suggests ${s.action === 'open' ? 'opening' : 'closing'} ${what}${s.reason ? `: ${suppliedValue(s.reason)}` : ''} — ${how} if you want to (nothing was done).`;
   }
 
   /** The keys a reminder restates: every open key of this server's view. */
@@ -605,14 +670,16 @@ export class ToolPresence {
     return lines.join('\n');
   }
 
-  /** look naming this server: what is open (with tools) and what can be opened. */
-  catalog(): string {
+  /** look naming this server: what is open (with tools) and what can be
+   *  opened. `mark: false`, as for render, for a look whose result may
+   *  reach no agent. */
+  catalog(opts: { mark?: boolean } = {}): string {
     const lines: string[] = [];
-    lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).join(': ')}` : this.server);
+    lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).map(suppliedValue).join(': ')}` : this.server);
     const v = this.view();
     if (v.size) {
       for (const [key, e] of v) {
-        lines.push(...this.toolBlock(key, [...e.tools.values()], { describeAll: true, title: e.title }).map((l) => `  ${l}`));
+        lines.push(...this.toolBlock(key, [...e.tools.values()], { describeAll: true, title: e.title, seen: opts.mark === false ? new Set<string>() : undefined }).map((l) => `  ${l}`));
         const close = this.closeHint(key);
         if (close) lines.push(`    ${close} closes it.`);
       }
@@ -623,7 +690,7 @@ export class ToolPresence {
     for (const [name, d] of Object.entries(this.declared)) {
       if (!d.instances && this.isOpen(name)) continue;
       openable.push(
-        `  ${name}${d.title ? ` — ${d.title}` : ''}${d.summary ? `: ${d.summary}` : ''}` +
+        `  ${nameToTypeBack(name)}${d.title ? ` — ${suppliedValue(d.title)}` : ''}${d.summary ? `: ${suppliedValue(d.summary)}` : ''}` +
           (d.instances ? ' (several can be open at once; name each with instance)' : '') +
           (d.options ? ` · options ${objectSignature(d.options)}` : ''),
       );
@@ -631,7 +698,7 @@ export class ToolPresence {
     for (const g of this.undeclaredGroups) {
       if (this.groups.has(g)) continue;
       const names = this.allTools.filter((t) => this.toolsetOf(t.name) === g).map((t) => t.name);
-      openable.push(`  ${g}: ${names.join(', ')}`);
+      openable.push(`  ${nameToTypeBack(g)}: ${names.map(nameToTypeBack).join(', ')}`);
     }
     if (openable.length) lines.push(`can open — ${this.names.open} {server:"${this.server}", toolset, instance?, options?}:`, ...openable);
     return lines.join('\n');
@@ -639,12 +706,12 @@ export class ToolPresence {
 
   /** Where a tool can be called from now, for `look` naming it. */
   toolStatus(tool: string): string {
-    if (this.presenceOf(tool) === 'static') return `static — in your tool list as ${this.listedName(tool)}`;
+    if (this.presenceOf(tool) === 'static') return `static — called by name, as ${nameToTypeBack(this.listedName(tool))}`;
     const where = [...this.view().entries()].filter(([, e]) => e.tools.has(tool)).map(([k]) => k);
     const ts = this.toolsetOf(tool);
     return where.length
-      ? `available now in ${where.map((k) => this.label(k)).join(', ')} — ${this.names.act} {server:"${this.server}", tool:"${tool}"${where.length > 1 ? ', instance' : ''}, args}`
-      : `not available right now${ts ? ` (toolset ${ts})` : ''}`;
+      ? `available now in ${where.map((k) => this.label(k)).join(', ')} — ${this.names.act} {server:"${this.server}", tool:${quotedValue(tool)}${where.length > 1 ? ', instance' : ''}, args}`
+      : `not available right now${ts ? ` (toolset ${nameToTypeBack(ts)})` : ''}`;
   }
 
 }