@animalabs/agent-framework 0.26.2 → 0.27.0

package/src/mcpl/toolset-host.ts

@@ -0,0 +1,637 @@
+/**
+ * MCPL RFC-014, host side: per server, the controller that feeds the
+ * server's tool presence (tool-presence.ts) from what its connection reads,
+ * sends toolsets/open, close and list, recovers from a lost rev, and renders
+ * what changed; and the hub that holds every server's controller for the
+ * meta-tools (toolsets-module.ts) and for reminders.
+ *
+ * Hint changes apply as their message is read (RFC §6.1): the connection's
+ * read tap hands the controller every result of a hinted request (awaited or
+ * not), every push/event and every tools/hints, of the current transport,
+ * synchronously and in arrival order, before anything routes the message.
+ * What a message's changes did to the model's view is kept by the object
+ * that carried them (`readChanges`), so whoever later handles that object
+ * (the tool result, the push, the meta-tool) renders it next to the content.
+ *
+ * Reminders (RFC §8.3): after each compile built to send, the hub reads
+ * which open toolsets' markers (`[server/toolset:instance]`) the request
+ * carried. A marker an agent has had in view, gone from a later request
+ * (compressed, or out of the window), makes a reminder due for that agent,
+ * which the toolsets module gathers at its next start as a stored
+ * `afterUser` injection.
+ */
+import type { McplServerConnection, HintRead } from './server-connection.js';
+import type { McplServerConfig } from './types.js';
+import { isToolAllowed } from './tool-policy.js';
+import {
+  ToolPresence, emptyChange, isEmptyChange, joinChanges, keyOf,
+  type ChangeSet, type MetaToolNames,
+} from './tool-presence.js';
+import type { HintedTool } from './tool-signature.js';
+
+/** The meta-tools' module, whose tools are `toolsets--open` and so on. */
+export const TOOLSETS_MODULE = 'toolsets';
+export const META_TOOL_NAMES: MetaToolNames = {
+  open: `${TOOLSETS_MODULE}--open`,
+  act: `${TOOLSETS_MODULE}--act`,
+  look: `${TOOLSETS_MODULE}--look`,
+  close: `${TOOLSETS_MODULE}--close`,
+};
+
+/** How long an open, close or call is waited for. A late result still applies when it's read. */
+export const TOOLSET_REQUEST_TIMEOUT_MS = 60_000;
+/** A toolsets/list after a (re)connect or in a recovery. */
+const LIST_TIMEOUT_MS = 15_000;
+/** A toolsets/list that only refreshes titles for look. */
+const REFRESH_TIMEOUT_MS = 5_000;
+/** A burst of anomalies is one recovery. */
+const RECOVERY_DEBOUNCE_MS = 200;
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const metaHints = (res: Record<string, unknown>): unknown => (isObj(res._meta) ? res._meta['mcpl/hints'] : undefined);
+
+export interface ToolsetHostDeps {
+  /** A standalone notice into the conversation: a tools/hints change, a late
+   *  result's, a reconnect's adoption, a recovery's. `invite`: it suggests an
+   *  open. The host applies its usual rules for events. */
+  notify(serverId: string, text: string, opts: { invite: boolean }): void;
+  /** The operator's log. */
+  log(line: string): void;
+  /** How a static tool is named in the tool list (`prefix--tool`). */
+  listedName(serverId: string, tool: string): string;
+}
+
+/** One server's RFC-014 state and traffic. Lives as long as the server's
+ *  configuration, across reconnects and restarts (its `ended` ids and what
+ *  the model was shown carry over). */
+export class ToolsetController {
+  readonly presence: ToolPresence;
+  private connection: McplServerConnection | null = null;
+  /** The transport epoch the presence's revs belong to. */
+  private epoch = -1;
+  /** What applying a message's hints changed, by the object that carried them. */
+  private readonly readChanges = new WeakMap<object, ChangeSet>();
+  /** Results whose change no one has rendered yet (tellUnlessClaimed). */
+  private readonly unclaimed = new Set<object>();
+  /** eventIds of pushes read on this transport (bounded): a repeat's hints are ignored (RFC §6.1). */
+  private seenEvents = new Set<string>();
+  /** A paged tools/list being read. */
+  private listPages: HintedTool[] | null = null;
+  /** Lists this controller asked for itself, whose change it delivers. */
+  private ownLists = 0;
+  /** What lists read while one of its own was out changed, for it to tell. */
+  private ownListChange: ChangeSet | null = null;
+  private recoveryTimer: ReturnType<typeof setTimeout> | null = null;
+  private recovering = false;
+  private recoverAgain = false;
+
+  constructor(
+    readonly serverId: string,
+    private config: McplServerConfig,
+    private readonly deps: ToolsetHostDeps,
+  ) {
+    this.presence = new ToolPresence(
+      serverId,
+      META_TOOL_NAMES,
+      (tool) => isToolAllowed(tool, this.config),
+      (tool) => deps.listedName(serverId, tool),
+    );
+  }
+
+  private log(line: string): void {
+    this.deps.log(`${this.serverId}: ${line}`);
+  }
+
+  /** A restart can bring a new configuration under the same id. */
+  setConfig(config: McplServerConfig): void {
+    this.config = config;
+  }
+
+  /** Tap this connection (a connect or a restart's new one). */
+  attach(connection: McplServerConnection): void {
+    if (this.connection !== connection) {
+      this.connection?.setReadTap(null);
+      // A new connection numbers its transports from 0 again.
+      this.epoch = -1;
+    }
+    this.connection = connection;
+    connection.setReadTap((read, epoch) => this.onRead(connection, read, epoch));
+  }
+
+  /** The server's connection is gone for good (disconnected, removed). */
+  detach(connection: McplServerConnection): void {
+    if (this.connection !== connection) return;
+    connection.setReadTap(null);
+    this.connection = null;
+    this.epoch = -1;
+    if (this.recoveryTimer) clearTimeout(this.recoveryTimer);
+    this.recoveryTimer = null;
+    // Nothing of it presents any more; what the agent was told (ended ids,
+    // definitions shown) is kept for a next connection.
+    this.presence.deactivate();
+  }
+
+  /** Whether the meta-tools speak for this server now. */
+  get presents(): boolean {
+    return this.presence.presents;
+  }
+
+  /** The live connection, for a request. */
+  private live(): McplServerConnection {
+    const c = this.connection;
+    if (!c || !c.isConnected) throw new Error(`${this.serverId} is not connected right now; try again later`);
+    this.sync(c.transportEpoch, c);
+    return c;
+  }
+
+  /**
+   * A new transport: revs start over (RFC §6.1), and its advertisement says
+   * whether hints are in effect. Read from the connection, which holds the
+   * advertisement before its transport can deliver anything.
+   */
+  private sync(epoch: number, connection: McplServerConnection): void {
+    if (epoch === this.epoch) return;
+    this.epoch = epoch;
+    this.seenEvents = new Set();
+    this.listPages = null;
+    this.presence.beginConnection(connection.toolsetDeclarations, true);
+  }
+
+  // ── RFC §6.1: apply on arrival ──
+
+  private onRead(connection: McplServerConnection, read: HintRead, epoch: number): void {
+    if (connection !== this.connection) return;
+    this.sync(epoch, connection);
+    if (read.kind === 'result') {
+      this.readResult(read.method, read.params, read.result as Record<string, unknown>, read.awaited);
+      return;
+    }
+    if (!this.presence.active || !isObj(read.params)) return;
+    const p = read.params;
+    if (read.kind === 'hints') {
+      const cs = this.applyHints(p, 'tools/hints');
+      // Carrier 3: a change with nothing to say, told on its own.
+      this.deliver(cs);
+      return;
+    }
+    if (p.hints === undefined) return;
+    // RFC §7: a push carrying hints is never coalesced; when its changes
+    // would apply is undefined, so they're ignored and the state re-read.
+    if (p.coalesce !== undefined && p.coalesce !== null) {
+      this.log(`push ${String(p.eventId ?? '')} carries hints and coalesce (RFC-014 §7 forbids it): its hints are ignored; recovering`);
+      this.scheduleRecovery();
+      return;
+    }
+    // RFC §6.1: never retried, so a seen eventId is a duplicate whose hints applied once.
+    const eventId = typeof p.eventId === 'string' || typeof p.eventId === 'number' ? String(p.eventId) : '';
+    if (eventId) {
+      if (this.seenEvents.has(eventId)) {
+        this.log(`push ${eventId} was read before: its hints are ignored`);
+        return;
+      }
+      this.seenEvents.add(eventId);
+      if (this.seenEvents.size > 1000) this.seenEvents.delete(this.seenEvents.values().next().value!);
+    }
+    // Applied now, before (and whatever) the host decides about the push.
+    this.readChanges.set(p, this.applyHints(p.hints, 'push'));
+  }
+
+  private readResult(method: string, params: Record<string, unknown>, res: Record<string, unknown>, awaited: boolean): void {
+    let cs: ChangeSet;
+    switch (method) {
+      case 'tools/list': {
+        const page = Array.isArray(res.tools) ? (res.tools as HintedTool[]) : [];
+        // A first page (no cursor) starts the list; a page with no next cursor ends it.
+        if (params.cursor === undefined || this.listPages === null) this.listPages = [];
+        this.listPages.push(...page);
+        if (res.nextCursor !== undefined && res.nextCursor !== null) return;
+        const tools = this.listPages;
+        this.listPages = null;
+        cs = this.readToolList(tools, res);
+        // The framework's own refresh (a list change, a reconnect) told here;
+        // a list this controller asked for is told by whoever asked.
+        if (this.ownLists === 0) this.deliver(cs);
+        else this.ownListChange = joinChanges(this.ownListChange ?? emptyChange(), cs);
+        return;
+      }
+      case 'toolsets/list':
+        cs = this.readToolsetList(res);
+        break;
+      case 'toolsets/open': {
+        if (!this.presence.active) return;
+        cs = this.applyHints(metaHints(res), 'toolsets/open');
+        const before = this.presence.view();
+        const toolset = typeof res.toolset === 'string' ? res.toolset : String(params.toolset ?? '');
+        const instance = typeof res.instance === 'string' && res.instance ? res.instance : typeof params.instance === 'string' ? params.instance : undefined;
+        this.presence.noteOpened(toolset, instance, typeof res.title === 'string' && res.title ? res.title : undefined);
+        cs.changes.push(...this.presence.diff(before, this.presence.view()).changes);
+        break;
+      }
+      case 'toolsets/close': {
+        if (!this.presence.active) return;
+        // RFC §5.2: the hint changes the close caused ride in its result, like an open's.
+        cs = this.applyHints(metaHints(res), 'toolsets/close');
+        const before = this.presence.view();
+        this.presence.noteClosed(String(params.toolset ?? ''), typeof params.instance === 'string' ? params.instance : undefined);
+        cs.changes.push(...this.presence.diff(before, this.presence.view()).changes);
+        break;
+      }
+      default:
+        if (!this.presence.active) return;
+        cs = this.applyHints(metaHints(res), method);
+    }
+    if (awaited) {
+      this.readChanges.set(res, cs);
+      this.tellUnlessClaimed(res, cs, method);
+    } else {
+      // RFC §6.1: a result nobody waits for any more (it timed out) applies
+      // all the same, and its change is told on its own.
+      this.log(`late ${method} result read: its hint changes applied`);
+      this.deliver(cs);
+    }
+  }
+
+  /**
+   * The one apply path (RFC §6.1) for a HintChanges from any carrier, as its
+   * message is read. Revs are consecutive: anything but the last + 1 means a
+   * message was lost or misordered, and the host recovers.
+   */
+  private applyHints(h: unknown, source: string): ChangeSet {
+    if (h === undefined || !this.presence.active) return emptyChange();
+    const before = this.presence.view();
+    const last = this.presence.rev;
+    const r = this.presence.apply(h);
+    const rev = String((h as { rev?: unknown } | null)?.rev);
+    if (r.behind) {
+      this.log(`hint change rev ${rev} (${source}) is not after rev ${last}: ignored; recovering from tools/list and toolsets/list`);
+      this.scheduleRecovery();
+    } else if (r.skipped) {
+      this.log(`hint change rev ${rev} (${source}) after rev ${last}: a rev was lost; applied, and recovering from tools/list and toolsets/list`);
+      this.scheduleRecovery();
+    } else if (!r.applied) {
+      this.log(`a malformed hint change (${source}) was ignored`);
+    }
+    const cs = this.presence.diff(before, this.presence.view());
+    cs.suggest.push(...r.suggest);
+    return cs;
+  }
+
+  /** tools/list, as read: definitions and presence as of its `mcpl/rev`, which takes no rev of its own (RFC §4.1). */
+  private readToolList(tools: HintedTool[], last: Record<string, unknown>): ChangeSet {
+    const before = this.presence.view();
+    this.presence.setTools(tools);
+    if (this.presence.active && this.presence.noteListRev(isObj(last._meta) ? last._meta['mcpl/rev'] : undefined)) {
+      this.log(`tools/list was written after rev ${String(isObj(last._meta) ? last._meta['mcpl/rev'] : '')}, past the last rev read: a message was lost; recovering`);
+      this.scheduleRecovery();
+    }
+    return this.presence.diff(before, this.presence.view());
+  }
+
+  /** toolsets/list, as read: a full statement of dynamic-tool state under its own rev (RFC §5.3, §6.1). */
+  private readToolsetList(res: Record<string, unknown>): ChangeSet {
+    if (!this.presence.active) return emptyChange();
+    const before = this.presence.view();
+    const { lost, ended, suggest, skipped } = this.presence.adopt(res);
+    if (skipped && !this.recovering) {
+      // Per-instance state is restated in full; what else was lost (presence) comes from tools/list.
+      this.log('toolsets/list skipped a rev: re-reading tools/list');
+      this.scheduleRecovery();
+    }
+    const cs = this.presence.diff(before, this.presence.view());
+    cs.suggest.push(...suggest);
+    // A lost toolset gets its note, not also a "closed" line.
+    cs.changes = cs.changes.filter((c) => !lost.some((o) => keyOf(o.toolset, o.instance) === c.key));
+    cs.notes.push(...this.presence.adoptionNotes(lost, ended));
+    return cs;
+  }
+
+  /** A change with nothing else to ride on, told as a notice. */
+  private deliver(cs: ChangeSet): void {
+    if (isEmptyChange(cs)) return;
+    const text = this.presence.render(cs);
+    if (!text) return;
+    this.deps.notify(this.serverId, text, { invite: cs.suggest.some((s) => s.action === 'open') });
+  }
+
+  /**
+   * A dynamic tool called by its namespaced name, as if it were listed (a
+   * model imitating an earlier call, a module): refused, so every call into
+   * a toolset goes through act, which knows its instance and gates closed
+   * groups (RFC §5.4, §5.5). Null for any other tool.
+   */
+  dynamicCallRefusal(tool: string, calledAs: string): string | null {
+    if (!this.presence.active || !this.presence.tool(tool) || this.presence.presenceOf(tool) !== 'dynamic') return null;
+    return `There's no tool "${calledAs}" in your tool list, so nothing ran: ${tool} is a dynamic tool of ${this.serverId}, ` +
+      `called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:"${tool}", args}. ${this.presence.toolStatus(tool)}.`;
+  }
+
+  /**
+   * An awaited result's change is told by whoever renders that result, when
+   * the result goes to the agent: the model's own call of a tool (its tool
+   * result), a meta-tool. One no one renders by the time the awaiting code has
+   * run (the next macrotask), such as the result of a call the framework makes
+   * itself (a reaction, a send, an accounted side effect), is told as a notice
+   * instead, as a standalone tools/hints is (RFC §6.1: every change reaches the
+   * agent once).
+   */
+  private tellUnlessClaimed(res: object, cs: ChangeSet, method: string): void {
+    if (isEmptyChange(cs)) return;
+    this.unclaimed.add(res);
+    setImmediate(() => {
+      if (!this.unclaimed.delete(res)) return;
+      this.log(`${method} result's tool change wasn't shown with it: told as a notice`);
+      this.deliver(cs);
+    });
+  }
+
+  /** What applying `carrier`'s hints changed (a tool result, a push's params),
+   *  rendered, for its handler to show with it; '' for nothing. Taking it
+   *  means it's told there, not as a notice. */
+  changeText(carrier: unknown): string {
+    if (!isObj(carrier)) return '';
+    this.unclaimed.delete(carrier);
+    const cs = this.readChanges.get(carrier);
+    return cs ? this.presence.render(cs) : '';
+  }
+
+  /** The change a carrier's hints made, or an empty one; taken as changeText's is. */
+  changeOf(carrier: unknown): ChangeSet {
+    if (!isObj(carrier)) return emptyChange();
+    this.unclaimed.delete(carrier);
+    return this.readChanges.get(carrier) ?? emptyChange();
+  }
+
+  // ── recovery (RFC §6.1) ──
+
+  private scheduleRecovery(): void {
+    if (!this.presence.active) return;
+    if (this.recovering) {
+      this.recoverAgain = true;
+      return;
+    }
+    if (this.recoveryTimer) return;
+    this.recoveryTimer = setTimeout(() => {
+      this.recoveryTimer = null;
+      void this.recover();
+    }, RECOVERY_DEBOUNCE_MS);
+    this.recoveryTimer.unref?.();
+  }
+
+  /**
+   * Recovering: re-read tools/list (presence, declared definitions), then
+   * toolsets/list (dynamic-tool state in full), so every tool the statement
+   * names is already known; each applies where it's read. What changed is
+   * told. (stdio and WebSocket deliver in order, so no early rev is held.)
+   */
+  private async recover(): Promise<void> {
+    const connection = this.connection;
+    if (!connection || !connection.isConnected) return;
+    this.recovering = true;
+    try {
+      const tools = await this.ownToolList(connection);
+      if (connection !== this.connection) return;
+      const lists = await this.ownToolsetList(connection, LIST_TIMEOUT_MS, 'recovery');
+      if (connection !== this.connection) return;
+      this.deliver(joinChanges(tools, lists));
+    } finally {
+      this.recovering = false;
+      if (this.recoverAgain) {
+        this.recoverAgain = false;
+        this.scheduleRecovery();
+      }
+    }
+  }
+
+  private async ownToolList(connection: McplServerConnection): Promise<ChangeSet> {
+    if (this.ownLists++ === 0) this.ownListChange = null;
+    try {
+      // The tap applied each page as it was read, and kept what the whole
+      // list changed (ownListChange).
+      await connection.sendToolsList();
+    } catch (error) {
+      this.log(`tools/list failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      this.ownLists--;
+    }
+    const collected = this.ownListChange ?? emptyChange();
+    if (this.ownLists === 0) this.ownListChange = null;
+    else this.ownListChange = emptyChange();
+    return collected;
+  }
+
+  private async ownToolsetList(connection: McplServerConnection, timeoutMs: number, why: string): Promise<ChangeSet> {
+    try {
+      const r = await connection.sendToolsetsList(timeoutMs);
+      return this.changeOf(r);
+    } catch (error) {
+      this.log(`toolsets/list (${why}) failed: ${error instanceof Error ? error.message : String(error)}`);
+      return emptyChange();
+    }
+  }
+
+  /**
+   * After every (re)connect, once its policy has settled (RFC §5.3): tools/list
+   * then toolsets/list, the truth. What the server reports open is adopted
+   * (a game kept across the reconnect); what the host believed open and it
+   * doesn't report is closed, never re-opened here, since opening can start a
+   * new game. What ended meanwhile is told, each `ended` id once.
+   */
+  async connected(connection: McplServerConnection): Promise<void> {
+    if (connection !== this.connection || !connection.isConnected) return;
+    this.sync(connection.transportEpoch, connection);
+    if (!this.presence.active) return;
+    const epoch = connection.transportEpoch;
+    const tools = await this.ownToolList(connection);
+    if (connection !== this.connection || connection.transportEpoch !== epoch) return;
+    const lists = await this.ownToolsetList(connection, LIST_TIMEOUT_MS, 'after connecting');
+    if (connection !== this.connection || connection.transportEpoch !== epoch) return;
+    this.deliver(joinChanges(tools, lists));
+  }
+
+  /**
+   * Re-read what the server holds open (titles, visibility) without telling
+   * it: for look, which restates everything anyway. Returns notes for what
+   * the server no longer holds.
+   */
+  async refreshOpen(): Promise<string[]> {
+    if (!this.presence.active) return [];
+    const connection = this.connection;
+    if (!connection || !connection.isConnected) return [];
+    try {
+      const r = await connection.sendToolsetsList(REFRESH_TIMEOUT_MS);
+      return this.changeOf(r).notes;
+    } catch (error) {
+      this.log(`toolsets/list (look) failed: ${error instanceof Error ? error.message : String(error)}`);
+      return [];
+    }
+  }
+
+  // ── the host's acts ──
+
+  /** toolsets/open (RFC §5.2). The server's refusal rejects. */
+  async open(toolset: string, instance: string | undefined, options: Record<string, unknown> | undefined): Promise<{
+    key: string; title?: string; content: unknown[]; change: ChangeSet; adopted: boolean;
+  }> {
+    const connection = this.live();
+    const r = await connection.sendToolsetsOpen({ toolset, ...(instance ? { instance } : {}), ...(options ? { options } : {}) }, TOOLSET_REQUEST_TIMEOUT_MS);
+    const res = isObj(r) ? r : {};
+    const inst = typeof res.instance === 'string' && res.instance ? res.instance : instance;
+    // RFC §5.2: a proposed name is used as given or the open refused.
+    if (instance && inst !== instance) this.log(`proposed instance "${instance}" came back as "${inst}" (RFC-014 §5.2 forbids renaming): using the server's`);
+    const key = keyOf(toolset, this.presence.declared[toolset]?.instances ? inst : undefined);
+    const title = typeof res.title === 'string' && res.title ? res.title : this.presence.openRecords().find((o) => keyOf(o.toolset, o.instance) === key)?.title;
+    return {
+      key,
+      ...(title ? { title } : {}),
+      content: Array.isArray(res.content) ? res.content : [],
+      change: this.changeOf(res),
+      adopted: res.adopted === true,
+    };
+  }
+
+  /** toolsets/close (RFC §5.2). */
+  async close(toolset: string, instance: string | undefined): Promise<{ content: unknown[]; change: ChangeSet }> {
+    const connection = this.live();
+    const r = await connection.sendToolsetsClose({ toolset, ...(instance ? { instance } : {}) }, TOOLSET_REQUEST_TIMEOUT_MS);
+    const res = isObj(r) ? r : {};
+    return { content: Array.isArray(res.content) ? res.content : [], change: this.changeOf(res) };
+  }
+
+  /** Open or close an undeclared group (RFC §5.4): the host's own act; the server isn't told. */
+  setGroupOpen(group: string, open: boolean): ChangeSet {
+    const before = this.presence.view();
+    if (open) this.presence.openGroup(group);
+    else this.presence.closeGroup(group);
+    return this.presence.diff(before, this.presence.view());
+  }
+
+  /**
+   * A manifest re-fetch (RFC §5.1): the `toolsets` domain's declarations, as
+   * the server sent them. A toolset removed ends its instances; a server
+   * that withdraws toolHints is hint-less from then on. What changed is told.
+   */
+  manifestChanged(declarations: Record<string, unknown> | null): void {
+    const before = this.presence.view();
+    const wasActive = this.presence.active;
+    if (!declarations || declarations.toolHints !== true) {
+      if (!wasActive) return;
+      this.presence.deactivate();
+      this.log('the server withdrew toolHints: every tool is static from now on');
+      const cs = this.presence.diff(before, this.presence.view());
+      cs.notes.push(`${this.serverId} no longer presents toolsets: its tools are all in your tool list now.`);
+      this.deliver(cs);
+      return;
+    }
+    if (!wasActive) {
+      // Hints that arrive by a manifest change take effect at the next
+      // connection's handshake: revs belong to a connection's first message.
+      this.log('the server now advertises toolHints: in effect from its next connection');
+      return;
+    }
+    this.presence.setManifest(declarations);
+    this.deliver(this.presence.diff(before, this.presence.view()));
+  }
+
+  /** Apply pending static↔dynamic moves (RFC §4.2) at a tool-list boundary, and say where they went. */
+  applyMoves(): string[] {
+    return this.presence.applyMoves().map(({ name, to }) => to === 'dynamic'
+      ? `${name} left your tool list: it's announced when available now, and called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:"${name}", args}.`
+      : `${name} is in your tool list now, as ${this.deps.listedName(this.serverId, name)}.`);
+  }
+}
+
+/** Every server's controller, for the meta-tools and reminders. */
+export class ToolsetHub {
+  private readonly controllers = new Map<string, ToolsetController>();
+  /** Per agent: the markers it has had in view (seen), and whether a reminder is due. */
+  private readonly seen = new Map<string, Set<string>>();
+  private readonly due = new Set<string>();
+
+  constructor(private readonly deps: ToolsetHostDeps) {}
+
+  /** The controller for a server, made at its first connect. */
+  controllerFor(config: McplServerConfig): ToolsetController {
+    let c = this.controllers.get(config.id);
+    if (!c) {
+      c = new ToolsetController(config.id, config, this.deps);
+      this.controllers.set(config.id, c);
+    } else {
+      c.setConfig(config);
+    }
+    return c;
+  }
+
+  get(serverId: string): ToolsetController | undefined {
+    return this.controllers.get(serverId);
+  }
+
+  /** A server's configuration went (removed): forget its controller. */
+  forget(serverId: string): void {
+    this.controllers.delete(serverId);
+  }
+
+  all(): ToolsetController[] {
+    return [...this.controllers.values()];
+  }
+
+  /** The servers the meta-tools speak for now. */
+  presenting(): ToolsetController[] {
+    return this.all().filter((c) => c.presents);
+  }
+
+  /** Every open key's marker, across servers. */
+  private openMarkers(): string[] {
+    return this.all().flatMap((c) => (c.presence.active ? c.presence.openKeys().map((k) => c.presence.label(k)) : []));
+  }
+
+  /**
+   * A compile built to send for `agentName` (RFC §8.3): which open toolsets'
+   * announcements the request carries. One the agent has had in view and the
+   * request no longer carries (compressed, or out of the window) makes a
+   * reminder due.
+   */
+  observeCompile(agentName: string, messages: readonly unknown[]): void {
+    const open = this.openMarkers();
+    if (open.length === 0) {
+      this.seen.delete(agentName);
+      this.due.delete(agentName);
+      return;
+    }
+    const text = compiledText(messages);
+    const seen = this.seen.get(agentName) ?? new Set<string>();
+    let missing = false;
+    for (const marker of open) {
+      if (text.includes(marker)) seen.add(marker);
+      else if (seen.has(marker)) missing = true;
+    }
+    for (const marker of [...seen]) if (!open.includes(marker)) seen.delete(marker);
+    this.seen.set(agentName, seen);
+    // Due until a request carries every marker the agent has seen again: a
+    // gather that doesn't send (a preview) leaves it due for the next start.
+    if (missing) this.due.add(agentName);
+    else this.due.delete(agentName);
+  }
+
+  /** The reminder due for `agentName`, or null when none is. */
+  reminderFor(agentName: string): string | null {
+    if (!this.due.has(agentName)) return null;
+    const parts = this.presenting().map((c) => c.presence.reminder()).filter((r): r is string => !!r);
+    if (parts.length === 0) return null;
+    return `Open toolsets (a reminder: their earlier announcements have left your context):\n${parts.join('\n')}`;
+  }
+}
+
+/** The text a compiled request carries, for marker search: text blocks and tool results' text, at any depth. */
+function compiledText(messages: readonly unknown[]): string {
+  const out: string[] = [];
+  const walk = (v: unknown, depth: number): void => {
+    if (depth > 6) return;
+    if (typeof v === 'string') { out.push(v); return; }
+    if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+    if (!isObj(v)) return;
+    if (typeof v.text === 'string') out.push(v.text);
+    if (v.content !== undefined) walk(v.content, depth + 1);
+  };
+  for (const m of messages) walk(isObj(m) ? m.content : undefined, 0);
+  return out.join('\n');
+}