@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/mcpl/tool-presence.ts

@@ -0,0 +1,650 @@
+/**
+ * MCPL RFC-014 (tool presence, toolsets and surfaces): one server's tool
+ * presence as the host keeps it.
+ *
+ * The server's tool list stays its whole truth (RFC §2 principle 1); hints say
+ * which tools are static (the API tool list, as before) and which are dynamic
+ * (announced in the conversation as they come and go, and called through the
+ * host's `act`). Per server this keeps:
+ *
+ *  - the tool definitions (tools/list) and the toolset declarations (manifest);
+ *  - which declared toolsets and instances are open (toolsets/open results,
+ *    toolsets/list, hint `toolsets` entries), and which undeclared groups the
+ *    host opened itself (RFC §5.4: the server is never told);
+ *  - the server's visibility statements per instance, and definition
+ *    overrides, from hint changes applied in `rev` order, each at most once.
+ *    One apply path serves every carrier: a call's, an open's or a close's
+ *    result, a push's `hints`, a standalone `tools/hints`. `tools/list`
+ *    (`mcpl/rev`) and `toolsets/list` are statements later changes build on;
+ *  - which definitions the model has been shown, so a tool's first sentence
+ *    is said once.
+ *
+ * Every mutation is bracketed by view() snapshots, and diff() turns the
+ * difference into what the model reads. Nothing here does I/O: the
+ * controller (toolset-host.ts) feeds it what the connection read.
+ *
+ * Ported from mcpl-cc-bridge's presence.ts, the reference host.
+ */
+import { objectSignature, renderToolLines, toolDigest, type HintedTool } from './tool-signature.js';
+
+export interface ToolsetDecl {
+  title?: string;
+  summary?: string;
+  default?: 'open' | 'closed';
+  instances?: boolean;
+  options?: unknown;
+}
+export interface Suggestion { toolset: string; instance?: string; action: 'open' | 'close'; reason: string }
+export interface OpenRecord { toolset: string; instance?: string; title?: string }
+/** RFC-014 §5.3: an instance that ended other than by a toolsets/close. */
+export interface Ended { id?: string; toolset: string; instance?: string; reason: string }
+export type Presence = 'static' | 'dynamic';
+
+/** The names of the host's meta-tools, as the model calls them. */
+export interface MetaToolNames { open: string; act: string; look: string; close: string }
+
+/** Toolset-less dynamic tools live under this key: always "open", visible per the server. */
+export const NO_TOOLSET = '';
+export const keyOf = (toolset: string, instance?: string): string => `${toolset}\u0000${instance ?? ''}`;
+export const splitKey = (key: string): { toolset: string; instance?: string } => {
+  const [toolset, instance] = key.split('\u0000');
+  return { toolset: toolset ?? '', ...(instance ? { instance } : {}) };
+};
+
+interface Entry { title?: string; tools: Map<string, HintedTool> }
+/** What the model may use right now: per key, the visible tools. Open-but-empty keys are present with no tools. */
+export type View = Map<string, Entry>;
+
+export interface Change {
+  key: string;
+  toolset: string;
+  instance?: string;
+  title?: string;
+  opened: boolean;
+  closed: boolean;
+  retitled: boolean;
+  appeared: HintedTool[];
+  gone: string[];
+  redefined: HintedTool[];
+  /** The visible tools after the change. */
+  now: HintedTool[];
+}
+export interface ChangeSet { changes: Change[]; suggest: Suggestion[]; notes: string[] }
+
+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),
+});
+
+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 : []);
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+
+/**
+ * RFC-014 §6.1: revs on a connection are consecutive (1, 2, 3 …), and changes
+ * apply in rev order, which on stdio and WebSocket is arrival order.
+ *  applied: a rev above the last, applied; `skipped` when it isn't exactly
+ *           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[] }
+
+/** 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> }
+
+/** The fields a hint definition may change (RFC §6.1); `name` and all of `_meta` are ignored. */
+export function overrideOf(d: Record<string, unknown>): DefOverride {
+  return {
+    ...(typeof d.description === 'string' ? { description: d.description } : {}),
+    ...(isObj(d.inputSchema) ? { inputSchema: d.inputSchema } : {}),
+    ...(isObj(d.annotations) ? { annotations: d.annotations } : {}),
+  };
+}
+
+export class ToolPresence {
+  /** Hints are in effect on the current connection: the host advertised toolHints and the server did too. */
+  active = false;
+  declared: Record<string, ToolsetDecl> = {};
+  surface: { title?: string; summary?: string } | null = null;
+  /** The last rev read on this connection (RFC §6.1); 0 at each connect. */
+  rev = 0;
+  private tools = new Map<string, HintedTool>();
+  private open = new Map<string, OpenRecord>();
+  private groups = new Set<string>();
+  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). */
+  private toldEnded = new Set<string>();
+  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>();
+
+  constructor(
+    readonly server: string,
+    /** The meta-tools' names, for the hints rendered text gives. */
+    readonly names: MetaToolNames,
+    /** The host's tool policy (enabledTools/disabledTools): a tool it refuses is as if unlisted. */
+    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,
+  ) {}
+
+  // ── connection lifecycle ──
+
+  /** A new connection: revs start over; hints count only when both sides advertised toolHints. */
+  beginConnection(mcpl: Record<string, unknown> | null | undefined, hostHints: boolean): void {
+    this.rev = 0;
+    // RFC §6.1: hint _meta and tools/hints from a server that did not advertise toolHints are ignored.
+    const active = hostHints && !!mcpl && mcpl.toolHints === true;
+    if (!active) {
+      if (this.active) this.deactivate();
+      return;
+    }
+    this.active = true;
+    this.setManifest(mcpl);
+  }
+
+  /** Toolset declarations and the surface hint, from initialize or a manifest re-fetch. */
+  setManifest(mcpl: Record<string, unknown> | null | undefined): void {
+    const prev = this.declared;
+    const decl: Record<string, ToolsetDecl> = {};
+    if (mcpl && isObj(mcpl.toolsets)) {
+      for (const [name, d] of Object.entries(mcpl.toolsets)) {
+        if (!isObj(d) || !name) continue;
+        decl[name] = {
+          ...(str(d.title) ? { title: str(d.title) } : {}),
+          ...(str(d.summary) ? { summary: str(d.summary) } : {}),
+          default: d.default === 'open' ? 'open' : 'closed',
+          ...(d.instances === true ? { instances: true } : {}),
+          ...(isObj(d.options) ? { options: d.options } : {}),
+        };
+      }
+    }
+    this.declared = decl;
+    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
+    // host's gating.
+    for (const [k, r] of [...this.open]) {
+      if (!decl[r.toolset] || !!decl[r.toolset]!.instances !== !!prev[r.toolset]?.instances) this.dropKey(k);
+    }
+    for (const name of Object.keys(prev)) {
+      if (decl[name]) continue;
+      this.groups.delete(name);
+      for (const k of new Set([...this.visible.keys(), ...this.defs.keys()])) if (splitKey(k).toolset === name) this.dropKey(k);
+    }
+  }
+
+  /** RFC §5.1: a server that withdraws toolHints is hint-less from then on: every tool static, nothing dynamic presented. */
+  deactivate(): void {
+    this.active = false;
+    this.declared = {};
+    this.surface = null;
+    this.open.clear();
+    this.groups.clear();
+    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]));
+    for (const set of this.visible.values()) for (const n of [...set]) if (!this.tools.has(n)) set.delete(n);
+    // 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;
+      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);
+    }
+  }
+
+  // ── reading ──
+
+  /** Whether the meta-tools speak for this server: hints in effect and something dynamic. */
+  get presents(): boolean {
+    if (!this.active) return false;
+    if (Object.keys(this.declared).length) return true;
+    for (const n of this.tools.keys()) if (this.presenceOf(n) === 'dynamic') return true;
+    return false;
+  }
+
+  get allTools(): HintedTool[] {
+    return [...this.tools.values()];
+  }
+
+  tool(name: string): HintedTool | undefined {
+    return this.tools.get(name);
+  }
+
+  toolsetOf(name: string): string | undefined {
+    const m = this.tools.get(name)?._meta;
+    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). */
+  presenceOf(name: string): Presence {
+    if (!this.active) return 'static';
+    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';
+  }
+
+  isDeclared(toolset: string): boolean {
+    return Object.hasOwn(this.declared, toolset);
+  }
+
+  /** Undeclared toolset names the server's tools are tagged with (RFC §5.4). */
+  get undeclaredGroups(): string[] {
+    const out = new Set<string>();
+    for (const n of this.tools.keys()) {
+      const ts = this.toolsetOf(n);
+      if (ts && !this.isDeclared(ts)) out.add(ts);
+    }
+    return [...out];
+  }
+
+  openRecords(toolset?: string): OpenRecord[] {
+    return [...this.open.values()].filter((r) => toolset === undefined || r.toolset === toolset);
+  }
+
+  isOpen(toolset: string, instance?: string): boolean {
+    return this.isDeclared(toolset) ? this.open.has(keyOf(toolset, instance)) : this.groups.has(toolset);
+  }
+
+  get openGroups(): string[] {
+    return [...this.groups];
+  }
+
+  /**
+   * The definition the model sees, and the host checks arguments against, for
+   * `name` in `key`: the instance's own (a hint definition with `instance`),
+   * else the toolset's (one without), else the listed one (RFC §6.1).
+   */
+  defOf(key: string, name: string): HintedTool {
+    const listed = this.tools.get(name)!;
+    const { toolset } = splitKey(key);
+    const o = this.defs.get(key)?.get(name) ?? (toolset ? this.defs.get(keyOf(toolset))?.get(name) : undefined);
+    return o ? { ...listed, ...o } : listed;
+  }
+
+  view(): View {
+    const v: View = new Map();
+    for (const [key, r] of this.open) v.set(key, { title: r.title, tools: new Map() });
+    for (const g of this.groups) if (!this.isDeclared(g)) v.set(keyOf(g), { tools: new Map() });
+    for (const name of this.tools.keys()) {
+      if (this.presenceOf(name) !== 'dynamic') continue;
+      const ts = this.toolsetOf(name);
+      if (ts && this.isDeclared(ts)) {
+        for (const [key, r] of this.open) if (r.toolset === ts && this.visible.get(key)?.has(name)) v.get(key)!.tools.set(name, this.defOf(key, name));
+      } else if (ts) {
+        // Two controllers (RFC §4.1, §5.4): the host has the group open AND the server says visible.
+        const key = keyOf(ts);
+        if (this.groups.has(ts) && this.visible.get(key)?.has(name)) v.get(key)!.tools.set(name, this.defOf(key, name));
+      } else {
+        const key = keyOf(NO_TOOLSET);
+        if (this.visible.get(key)?.has(name)) {
+          if (!v.has(key)) v.set(key, { tools: new Map() });
+          v.get(key)!.tools.set(name, this.defOf(key, name));
+        }
+      }
+    }
+    return v;
+  }
+
+  diff(before: View, after: View): ChangeSet {
+    const out = emptyChange();
+    for (const key of new Set([...before.keys(), ...after.keys()])) {
+      const b = before.get(key);
+      const a = after.get(key);
+      const isGroupKey = splitKey(key).toolset !== NO_TOOLSET;
+      const appeared: HintedTool[] = [];
+      const redefined: HintedTool[] = [];
+      for (const [n, d] of a?.tools ?? []) {
+        const was = b?.tools.get(n);
+        if (!was) appeared.push(d);
+        else if (toolDigest(was) !== toolDigest(d)) redefined.push(d);
+      }
+      const gone = [...(b?.tools.keys() ?? [])].filter((n) => !a?.tools.has(n));
+      const opened = isGroupKey && !b && !!a;
+      const closed = isGroupKey && !!b && !a;
+      const retitled = !!a && !!b && !!a.title && a.title !== b.title;
+      if (!appeared.length && !redefined.length && !gone.length && !opened && !closed && !retitled) continue;
+      out.changes.push({ key, ...splitKey(key), title: a?.title ?? b?.title, opened, closed, retitled, appeared, gone, redefined, now: [...(a?.tools.values() ?? [])] });
+    }
+    return out;
+  }
+
+  // ── the one apply path ──
+
+  /** 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: [] };
+    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) };
+  }
+
+  /**
+   * tools/list's `_meta["mcpl/rev"]` (RFC §4.1): the last rev the server had
+   * sent when it wrote the list, which takes none itself. Read in order it
+   * equals the last rev read; a higher one means a message was lost (true).
+   */
+  noteListRev(rev: unknown): boolean {
+    if (typeof rev !== 'number' || !Number.isFinite(rev)) return false;
+    const lost = rev > this.rev;
+    this.rev = Math.max(this.rev, rev);
+    return lost;
+  }
+
+  private applyBody(h: Record<string, unknown>): Suggestion[] {
+    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;
+      const withInstances = !!this.declared[ts]!.instances;
+      const instance = withInstances ? str(e.instance) : undefined;
+      if (withInstances && !instance) continue; // an instance-less statement about a toolset with instances names nothing
+      const key = keyOf(ts, instance);
+      // "open" opens, confirms, or (with a new title) retitles (RFC §6.1);
+      // it may come from another connection of the same principal (§5.6).
+      if (e.state === 'open') this.open.set(key, { toolset: ts, ...(instance ? { instance } : {}), title: str(e.title) ?? this.open.get(key)?.title });
+      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;
+      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 (isObj(e.definition) && this.presenceOf(name) === 'dynamic') {
+        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 (typeof e.visible === 'boolean') for (const key of this.keysFor(name, str(e.instance))) this.setVisible(key, name, e.visible);
+    }
+    const suggest: Suggestion[] = [];
+    for (const s of arr(h.suggest)) {
+      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;
+  }
+
+  /**
+   * 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 {
+    const ts = this.toolsetOf(name);
+    if (!ts) return keyOf(NO_TOOLSET);
+    return keyOf(ts, this.declared[ts]?.instances ? instance : undefined);
+  }
+
+  /** Where a visibility statement lands. For a toolset with instances, `instance` is required; a statement without one is ignored. */
+  private keysFor(name: string, instance: string | undefined): string[] {
+    const ts = this.toolsetOf(name);
+    if (!ts) return [keyOf(NO_TOOLSET)];
+    const decl = this.declared[ts];
+    if (!decl?.instances) return [keyOf(ts)];
+    return instance ? [keyOf(ts, instance)] : [];
+  }
+
+  private setVisible(key: string, name: string, on: boolean): void {
+    let s = this.visible.get(key);
+    if (!s) this.visible.set(key, (s = new Set()));
+    if (on) s.add(name);
+    else s.delete(name);
+  }
+
+  private dropKey(key: string): void {
+    this.open.delete(key);
+    this.visible.delete(key);
+    this.defs.delete(key);
+  }
+
+  /** The result of a toolsets/open: the instance is open whatever its hints say. */
+  noteOpened(toolset: string, instance: string | undefined, title: string | undefined): void {
+    if (!this.isDeclared(toolset)) return;
+    const withInstances = !!this.declared[toolset]!.instances;
+    if (withInstances && !instance) return;
+    const key = keyOf(toolset, withInstances ? instance : undefined);
+    this.open.set(key, { toolset, ...(withInstances && instance ? { instance } : {}), title: title ?? this.open.get(key)?.title });
+  }
+
+  /** toolsets/close succeeded: closed, whatever the hints said. */
+  noteClosed(toolset: string, instance: string | undefined): void {
+    this.dropKey(keyOf(toolset, this.declared[toolset]?.instances ? instance : undefined));
+  }
+
+  /**
+   * toolsets/list (RFC §5.3): what the principal has open, with the full hint
+   * state of its dynamic tools, the truth for declared toolsets and dynamic
+   * tools outside them. Anything the host believed open and the server doesn't
+   * report is closed, never re-opened here: opening can start a new game.
+   * 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 } {
+    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.
+    for (const k of new Set([...this.open.keys(), ...this.visible.keys(), ...this.defs.keys()])) {
+      if (this.isDeclared(splitKey(k).toolset)) this.dropKey(k);
+      else {
+        this.visible.delete(k);
+        this.defs.delete(k);
+      }
+    }
+    const r = isObj(result) ? result : {};
+    for (const o of arr(r.open)) {
+      if (!isObj(o) || !str(o.toolset)) continue;
+      this.noteOpened(o.toolset as string, str(o.instance), str(o.title));
+    }
+    let suggest: Suggestion[] = [];
+    let skipped = false;
+    const h = isObj(r._meta) ? r._meta['mcpl/hints'] : undefined;
+    if (isObj(h)) {
+      suggest = 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;
+        this.rev = Math.max(this.rev, h.rev);
+      }
+    }
+    const ended: Ended[] = [];
+    for (const e of arr(r.ended)) {
+      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 };
+  }
+
+  /**
+   * 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.
+   */
+  adoptionNotes(lost: OpenRecord[], ended: Ended[]): string[] {
+    const notes: string[] = [];
+    const endedKeys = new Set(ended.map((e) => keyOf(e.toolset, e.instance)));
+    for (const e of ended) {
+      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}` : ''}.`);
+    }
+    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;
+  }
+
+  // ── host-made opens of undeclared groups (RFC §5.4) ──
+
+  openGroup(g: string): void {
+    this.groups.add(g);
+  }
+
+  closeGroup(g: string): void {
+    this.groups.delete(g);
+  }
+
+  // ── 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();
+    return out;
+  }
+
+  // ── rendering ──
+
+  /** 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}` : ''}]`;
+  }
+
+  callHint(key: string): string {
+    const { instance } = splitKey(key);
+    return `${this.names.act} {server:"${this.server}"${instance ? `, instance:"${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}"` : ''}}`;
+  }
+
+  openHint(toolset: string, instance?: string): string {
+    return `${this.names.open} {server:"${this.server}", toolset:"${toolset}"${instance ? `, instance:"${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}` : ''} `;
+    if (!tools.length) return [`${head}no tools available right now.`];
+    return [`${head}tools now — ${this.callHint(key)}:`, ...renderToolLines(tools, 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 {
+    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(', ')}.` : ''}`);
+        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 (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);
+    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 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).`;
+  }
+
+  /** The keys a reminder restates: every open key of this server's view. */
+  openKeys(): string[] {
+    return [...this.view().keys()];
+  }
+
+  /** RFC §8.3 reminder: what is open, its current tools (described), how to call and close it. Null when nothing is open. */
+  reminder(): string | null {
+    const v = this.view();
+    if (!v.size) return null;
+    const lines: string[] = [];
+    for (const [key, e] of v) {
+      lines.push(...this.toolBlock(key, [...e.tools.values()], { describeAll: true, title: e.title }));
+      const close = this.closeHint(key);
+      if (close) lines.push(`  ${close} closes it.`);
+    }
+    return lines.join('\n');
+  }
+
+  /** look naming this server: what is open (with tools) and what can be opened. */
+  catalog(): string {
+    const lines: string[] = [];
+    lines.push(this.surface ? `${this.server} — ${[this.surface.title, this.surface.summary].filter(Boolean).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}`));
+        const close = this.closeHint(key);
+        if (close) lines.push(`    ${close} closes it.`);
+      }
+    } else {
+      lines.push('  nothing open');
+    }
+    const openable: string[] = [];
+    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}` : ''}` +
+          (d.instances ? ' (several can be open at once; name each with instance)' : '') +
+          (d.options ? ` · options ${objectSignature(d.options)}` : ''),
+      );
+    }
+    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(', ')}`);
+    }
+    if (openable.length) lines.push(`can open — ${this.names.open} {server:"${this.server}", toolset, instance?, options?}:`, ...openable);
+    return lines.join('\n');
+  }
+
+  /** 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)}`;
+    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})` : ''}`;
+  }
+
+}