@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/mcpl/toolset-host.ts

@@ -5,10 +5,14 @@
  * 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.
+ * Hint changes apply as their message is read (RFC §6.1); a static↔dynamic
+ * move takes effect when a tools/list states it (§4.1), and the model's tool
+ * list shows it at its next rebuild; until then the tool is called at either
+ * place (§4.2). The connection's read tap hands
+ * the controller every result of a hinted request (awaited or not, while no
+ * more than 1,000 hinted requests await an answer), each tools/list whole, every push/event and every tools/hints, of the
+ * current transport, synchronously and in arrival order, before anything
+ * routes the message or anything read after it is handled.
  * 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.
@@ -20,12 +24,15 @@
  * which the toolsets module gathers at its next start as a stored
  * `afterUser` injection.
  */
-import type { McplServerConnection, HintRead } from './server-connection.js';
+import { nameToTypeBack, quotedValue } from '../supplied-text.js';
+import { McplRequestError, type McplServerConnection, type HintRead } from './server-connection.js';
 import type { McplServerConfig } from './types.js';
 import { isToolAllowed } from './tool-policy.js';
+import { redactServerText } from './protocol-family.js';
+import { logDetail, logValueRedacted } from './log-value.js';
 import {
-  ToolPresence, emptyChange, isEmptyChange, joinChanges, keyOf,
-  type ChangeSet, type MetaToolNames,
+  ToolPresence, emptyChange, isEmptyChange, keyOf,
+  type ChangeSet, type MetaToolNames, type Presence,
 } from './tool-presence.js';
 import type { HintedTool } from './tool-signature.js';
 
@@ -38,7 +45,7 @@ export const META_TOOL_NAMES: MetaToolNames = {
   close: `${TOOLSETS_MODULE}--close`,
 };
 
-/** How long an open, close or call is waited for. A late result still applies when it's read. */
+/** How long an open or close 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;
@@ -54,16 +61,28 @@ 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;
+  notify(serverId: string, text: string, opts: { invite: boolean }): boolean;
+  /** Whether the server's changes may be put into the conversation unasked
+   *  (its `pushEvents` grant): notices and reminders. */
+  canNotify(serverId: string): boolean;
   /** 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;
+  /** Where the model's published tool list last put a server's tool:
+   *  offered in it (static), listed but not offered (dynamic), or undefined
+   *  where it isn't published. RFC §4.2: until its move applies, a tool
+   *  keeps working where it is. */
+  published?(serverId: string, tool: string): Presence | undefined;
+  /** The host's own toolsets an agent has open (the built-in one, server
+   *  tabs): each one's marker and reminder, for RFC §8.3 reminders beside the
+   *  servers' toolsets. */
+  hostOpen?(agentName: string): Array<{ marker: string; reminder: () => string; dueWhenAbsent?: boolean }>;
 }
 
 /** 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). */
+ *  configuration, across reconnects and the server's restarts (its `ended`
+ *  ids and what the model was shown carry over), in memory only. */
 export class ToolsetController {
   readonly presence: ToolPresence;
   private connection: McplServerConnection | null = null;
@@ -71,16 +90,10 @@ export class ToolsetController {
   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>();
+  /** Results whose change no one has taken yet, in the order they were read, with their method (tellUnlessClaimed). */
+  private readonly unclaimed = new Map<object, string>();
   /** 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;
@@ -95,6 +108,7 @@ export class ToolsetController {
       META_TOOL_NAMES,
       (tool) => isToolAllowed(tool, this.config),
       (tool) => deps.listedName(serverId, tool),
+      (tool) => deps.published?.(serverId, tool),
     );
   }
 
@@ -102,6 +116,14 @@ export class ToolsetController {
     this.deps.log(`${this.serverId}: ${line}`);
   }
 
+  private field(value: unknown): string {
+    return logValueRedacted(value, (text) => redactServerText(text, this.config));
+  }
+
+  private failure(error: unknown): string {
+    return logDetail(redactServerText(error instanceof Error ? error.message : String(error), this.config));
+  }
+
   /** A restart can bring a new configuration under the same id. */
   setConfig(config: McplServerConfig): void {
     this.config = config;
@@ -118,6 +140,10 @@ export class ToolsetController {
     connection.setReadTap((read, epoch) => this.onRead(connection, read, epoch));
   }
 
+  release(): void {
+    if (this.connection) this.detach(this.connection);
+  }
+
   /** The server's connection is gone for good (disconnected, removed). */
   detach(connection: McplServerConnection): void {
     if (this.connection !== connection) return;
@@ -139,7 +165,7 @@ export class ToolsetController {
   /** 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`);
+    if (!c || !c.isConnected) throw new McplRequestError(`${this.serverId} is not connected right now; try again later`, 'not-sent');
     this.sync(c.transportEpoch, c);
     return c;
   }
@@ -153,7 +179,6 @@ export class ToolsetController {
     if (epoch === this.epoch) return;
     this.epoch = epoch;
     this.seenEvents = new Set();
-    this.listPages = null;
     this.presence.beginConnection(connection.toolsetDeclarations, true);
   }
 
@@ -163,7 +188,7 @@ export class ToolsetController {
     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);
+      this.readResult(read.method, read.params, read.result as Record<string, unknown>, read.awaited, read.straddled === true);
       return;
     }
     if (!this.presence.active || !isObj(read.params)) return;
@@ -178,7 +203,7 @@ export class ToolsetController {
     // 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.log(`push ${this.field(p.eventId ?? '')} carries hints and coalesce (RFC-014 §7 forbids it): its hints are ignored; recovering`);
       this.scheduleRecovery();
       return;
     }
@@ -186,32 +211,29 @@ export class ToolsetController {
     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`);
+        this.log(`push ${this.field(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'));
+    const cs = this.applyHints(p.hints, 'push');
+    this.readChanges.set(p, cs);
+    this.tellUnlessClaimed(p, cs, 'push/event');
   }
 
-  private readResult(method: string, params: Record<string, unknown>, res: Record<string, unknown>, awaited: boolean): void {
+  private readResult(method: string, params: Record<string, unknown>, res: Record<string, unknown>, awaited: boolean, straddled: 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);
+        if (!Array.isArray(res.tools)) return;
+        cs = this.readToolList(res.tools as HintedTool[], res);
+        if (straddled && !this.recovering) {
+          this.log('tools/list pages carried different revs, so its earlier pages are older than changes read between them: recovering');
+          this.scheduleRecovery();
+        }
+        this.deliver(cs);
         return;
       }
       case 'toolsets/list':
@@ -259,9 +281,9 @@ export class ToolsetController {
   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 last = this.field(this.presence.rev);
     const r = this.presence.apply(h);
-    const rev = String((h as { rev?: unknown } | null)?.rev);
+    const rev = this.field((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();
@@ -271,6 +293,10 @@ export class ToolsetController {
     } else if (!r.applied) {
       this.log(`a malformed hint change (${source}) was ignored`);
     }
+    if (r.unlisted) {
+      this.log(`hint change rev ${rev} (${source}) names a tool tools/list hasn't listed: recovering from tools/list and toolsets/list`);
+      this.scheduleRecovery();
+    }
     const cs = this.presence.diff(before, this.presence.view());
     cs.suggest.push(...r.suggest);
     return cs;
@@ -281,7 +307,7 @@ export class ToolsetController {
     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.log(`tools/list was written after rev ${this.field(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());
@@ -290,39 +316,78 @@ export class ToolsetController {
   /** 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();
+    if (!Array.isArray(res.open)) {
+      this.log('a toolsets/list result with no open list was ignored');
+      return emptyChange();
+    }
     const before = this.presence.view();
-    const { lost, ended, suggest, skipped } = this.presence.adopt(res);
+    const { lost, ended, suggest, skipped, unlisted } = 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();
     }
+    if (unlisted && !this.recovering) {
+      this.log('toolsets/list names a tool tools/list hasn\'t listed: 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));
+    const told = this.presence.adoptionNotes(lost, ended);
+    cs.notes.push(...told.notes);
+    if (told.ended.length) cs.ended = [...(cs.ended ?? []), ...told.ended];
     return cs;
   }
 
-  /** A change with nothing else to ride on, told as a notice. */
+  /** A change with nothing else to ride on, told as a notice, after every result's change still unclaimed. */
   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') });
+    this.tellUnclaimed();
+    this.notice(cs);
+  }
+
+  /**
+   * Unclaimed carriers' changes, told as notices in the order they were read,
+   * through `upTo` when given. When no notice can be written, a push keeps its
+   * change for the framework's push path, which takes it when the push gets
+   * there; a result's is dropped, whether or not its caller is still to
+   * resume.
+   */
+  private tellUnclaimed(upTo?: object): void {
+    for (const [res, method] of [...this.unclaimed]) {
+      this.unclaimed.delete(res);
+      const cs = this.readChanges.get(res) ?? emptyChange();
+      const sent = this.notice(cs);
+      if (sent !== 'refused' || method !== 'push/event') this.readChanges.delete(res);
+      if (sent === 'told') this.log(`${method}'s tool change wasn't shown with it: told as a notice`);
+      if (res === upTo) return;
+    }
+  }
+
+  /** Whether a notice was written, there was nothing left to tell (`empty`), or one couldn't be written (`refused`). */
+  private notice(cs: ChangeSet): 'told' | 'empty' | 'refused' {
+    if (isEmptyChange(cs)) return 'empty';
+    const text = this.presence.render(cs, { mark: false });
+    if (!text) return 'empty';
+    if (!this.deps.notify(this.serverId, text, { invite: cs.suggest.some((s) => s.action === 'open') })) return 'refused';
+    this.presence.markTold(cs.ended);
+    this.presence.markShown(cs);
+    return 'told';
   }
 
   /**
    * 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.
+   * groups (RFC §5.4, §5.5). Null for any other tool, including one the tool
+   * list last published or the server's latest tools/list puts as static
+   * (shownAs: RFC §4.2, until its move applies).
    */
   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)}.`;
+    if (!this.presence.active || !this.presence.tool(tool) || this.presence.shownAs(tool, 'static')) return null;
+    return `There's no tool "${calledAs}" in your tool list, so nothing ran: ${nameToTypeBack(tool)} is a dynamic tool of ${this.serverId}, ` +
+      `called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:${quotedValue(tool)}, args}. ${this.presence.toolStatus(tool)}.`;
   }
 
   /**
@@ -332,35 +397,56 @@ export class ToolsetController {
    * 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).
+   * agent once), or dropped as tellUnclaimed says when none can be written.
    */
   private tellUnlessClaimed(res: object, cs: ChangeSet, method: string): void {
     if (isEmptyChange(cs)) return;
-    this.unclaimed.add(res);
+    this.unclaimed.set(res, method);
     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);
+      if (this.unclaimed.has(res)) this.tellUnclaimed(res);
     });
   }
 
-  /** 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 {
+  /**
+   * The change a carrier's hints made (a tool result, a push's params), taken
+   * by a caller that shows it to an agent with the carrier: it isn't told as a
+   * notice, and the caller says when it has reached an agent (told). Call it
+   * synchronously as the carrier is read, before the next macrotask, when an
+   * unclaimed carrier's change goes out as a notice instead (tellUnclaimed
+   * says what happens when none can be written). A change already gone that
+   * way is empty here. Unclaimed carriers read before this one
+   * are told first, as notices, so no later change is shown before them.
+   */
+  takeChange(carrier: unknown): ChangeSet {
     if (!isObj(carrier)) return emptyChange();
+    if (this.unclaimed.has(carrier)) {
+      let before: object | undefined;
+      for (const res of this.unclaimed.keys()) {
+        if (res === carrier) break;
+        before = res;
+      }
+      if (before) this.tellUnclaimed(before);
+    }
     this.unclaimed.delete(carrier);
     return this.readChanges.get(carrier) ?? emptyChange();
   }
 
+  /** A change its taker showed to an agent: its ended records count as told, and the definitions it describes as shown, unless the taker showed it without its blocks (`blocksShown: false`). */
+  told(cs: ChangeSet): void {
+    this.presence.markTold(cs.ended);
+    if (cs.blocksShown !== false) this.presence.markShown(cs);
+  }
+
+  /** A change its taker couldn't show, told as a notice instead, or dropped when none can be written. */
+  tell(cs: ChangeSet): void {
+    this.notice(cs);
+  }
+
+  private changeOf(carrier: object): ChangeSet {
+    return this.readChanges.get(carrier) ?? emptyChange();
+  }
+
   // ── recovery (RFC §6.1) ──
 
   private scheduleRecovery(): void {
@@ -380,19 +466,23 @@ export class ToolsetController {
   /**
    * 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.)
+   * names is already known, unless tools/list failed: a tool the last list
+   * lacks then stays unknown until a later change or list starts a recovery.
+   * 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);
+      await this.ownToolList(connection);
+      // RFC §6.1: toolsets/list after tools/list, so every tool it names is known, unless tools/list failed.
       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));
+      this.deliver(lists);
     } finally {
       this.recovering = false;
       if (this.recoverAgain) {
@@ -402,29 +492,21 @@ export class ToolsetController {
     }
   }
 
-  private async ownToolList(connection: McplServerConnection): Promise<ChangeSet> {
-    if (this.ownLists++ === 0) this.ownListChange = null;
+  /** The tap applies the list and tells its change as it's read. */
+  private async ownToolList(connection: McplServerConnection): Promise<void> {
     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--;
+      this.log(`tools/list failed: ${this.failure(error)}`);
     }
-    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);
+      return this.takeChange(r);
     } catch (error) {
-      this.log(`toolsets/list (${why}) failed: ${error instanceof Error ? error.message : String(error)}`);
+      this.log(`toolsets/list (${why}) failed: ${this.failure(error)}`);
       return emptyChange();
     }
   }
@@ -441,35 +523,41 @@ export class ToolsetController {
     this.sync(connection.transportEpoch, connection);
     if (!this.presence.active) return;
     const epoch = connection.transportEpoch;
-    const tools = await this.ownToolList(connection);
+    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));
+    this.deliver(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.
+   * it, for look. Returns what the re-read changed, taken from the notice it
+   * would otherwise get when `shown` (its result reaches an agent): look then
+   * either shows it (told) or hands it back (tell). Otherwise the change is
+   * left to its notice, and returned to be shown to the caller alone. Null
+   * when nothing was read.
    */
-  async refreshOpen(): Promise<string[]> {
-    if (!this.presence.active) return [];
+  async refreshOpen(opts: { shown: boolean }): Promise<ChangeSet | null> {
+    if (!this.presence.active) return null;
     const connection = this.connection;
-    if (!connection || !connection.isConnected) return [];
+    if (!connection || !connection.isConnected) return null;
     try {
       const r = await connection.sendToolsetsList(REFRESH_TIMEOUT_MS);
-      return this.changeOf(r).notes;
+      if (!isObj(r)) return null;
+      return opts.shown ? this.takeChange(r) : this.changeOf(r);
     } catch (error) {
-      this.log(`toolsets/list (look) failed: ${error instanceof Error ? error.message : String(error)}`);
-      return [];
+      this.log(`toolsets/list (look) failed: ${this.failure(error)}`);
+      return null;
     }
   }
 
   // ── 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<{
+  /** toolsets/open (RFC §5.2). The server's refusal rejects. Its change is
+   *  taken when `shown` (its result reaches an agent), else left to its
+   *  notice and returned for the caller alone; close's is the same. */
+  async open(toolset: string, instance: string | undefined, options: Record<string, unknown> | undefined, opts: { shown: boolean }): Promise<{
     key: string; title?: string; content: unknown[]; change: ChangeSet; adopted: boolean;
   }> {
     const connection = this.live();
@@ -477,24 +565,24 @@ export class ToolsetController {
     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`);
+    if (instance && inst !== instance) this.log(`proposed instance ${this.field(instance)} came back as ${this.field(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),
+      change: opts.shown ? this.takeChange(res) : this.changeOf(res),
       adopted: res.adopted === true,
     };
   }
 
   /** toolsets/close (RFC §5.2). */
-  async close(toolset: string, instance: string | undefined): Promise<{ content: unknown[]; change: ChangeSet }> {
+  async close(toolset: string, instance: string | undefined, opts: { shown: boolean }): 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) };
+    return { content: Array.isArray(res.content) ? res.content : [], change: opts.shown ? this.takeChange(res) : this.changeOf(res) };
   }
 
   /** Open or close an undeclared group (RFC §5.4): the host's own act; the server isn't told. */
@@ -518,7 +606,7 @@ export class ToolsetController {
       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.`);
+      cs.notes.push(`${this.serverId} no longer presents toolsets: its tools are called directly now, by name, not through ${META_TOOL_NAMES.act}.`);
       this.deliver(cs);
       return;
     }
@@ -532,11 +620,15 @@ export class ToolsetController {
     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)}.`);
+  /** At a rebuild of the model's tool list (RFC §4.2), tell where the tools it moved went: `moves`, those still pending, or every one pending. A move a list has undone since the rebuild listed the server isn't told; the next rebuild publishes the undoing. */
+  applyMoves(moves?: Array<{ name: string; to: Presence }>): void {
+    const moved = this.presence.applyMoves(moves);
+    if (!moved.length) return;
+    const cs = emptyChange();
+    cs.notes.push(...moved.map(({ name, to }) => to === 'dynamic'
+      ? `${nameToTypeBack(name)} left your tool list: it's announced when available, and called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:${quotedValue(name)}, args}.`
+      : `${nameToTypeBack(name)} is in your tool list now, as ${nameToTypeBack(this.deps.listedName(this.serverId, name))}.`));
+    this.deliver(cs);
   }
 }
 
@@ -565,8 +657,11 @@ export class ToolsetHub {
     return this.controllers.get(serverId);
   }
 
-  /** A server's configuration went (removed): forget its controller. */
+  /** A server's configuration went (removed): its controller lets go of the
+   *  connection it holds, and is forgotten, so a server added later under
+   *  the same id starts from nothing. */
   forget(serverId: string): void {
+    this.controllers.get(serverId)?.release();
     this.controllers.delete(serverId);
   }
 
@@ -591,8 +686,9 @@ export class ToolsetHub {
    * reminder due.
    */
   observeCompile(agentName: string, messages: readonly unknown[]): void {
+    const host = this.deps.hostOpen?.(agentName) ?? [];
     const open = this.openMarkers();
-    if (open.length === 0) {
+    if (open.length === 0 && host.length === 0) {
       this.seen.delete(agentName);
       this.due.delete(agentName);
       return;
@@ -606,6 +702,9 @@ export class ToolsetHub {
     }
     for (const marker of [...seen]) if (!open.includes(marker)) seen.delete(marker);
     this.seen.set(agentName, seen);
+    // A host toolset open across a restart was never seen here: it's due
+    // whenever a request doesn't carry its marker.
+    for (const h of host) if (h.dueWhenAbsent && !text.includes(h.marker)) missing = true;
     // 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);
@@ -615,7 +714,10 @@ export class ToolsetHub {
   /** 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);
+    const parts = [
+      ...(this.deps.hostOpen?.(agentName) ?? []).map((h) => h.reminder()),
+      ...this.presenting().filter((c) => this.deps.canNotify(c.serverId)).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')}`;
   }