fix(mcpl): the toolsets host follows the server's lists and tells each change once

README.md

@@ -448,36 +448,75 @@ framework registers a `toolsets` module with four constant tools:
 - `toolsets--act {server?, tool, instance?, args?}` calls a dynamic tool down
   the same path as a direct call of it (the agent's `allowedTools`, the
   server's tool policy, the state exchange, the reading of its result, RFC-007
-  observers, who see the server's tool), with only the instance added, in
+  observers and RFC-008 class rules, which see the server's tool and its class),
+  with only the instance added, in
   `_meta["mcpl/instance"]`. It first checks `args` against the definition in
   force for that instance; that check is bounded, and leaves `pattern` and
   anything nested or branching too far to the server, which checks every
   call itself;
 - `toolsets--look {server?, toolset?, instance?, tool?}` restates what is open
-  and what can be opened, or one tool's whole definition;
+  and what can be opened, or one tool's signature, description, class and
+  input schema. It
+  re-reads each server that presents toolsets first, and says so when it
+  couldn't; what that changed
+  is in the answer when look restates everything, and otherwise told as a
+  notice;
 - `toolsets--close {server?, toolset?, instance?}` closes it.
 
-`server` can be left out when only one server has the name. Hint changes apply
+`server` can be left out when only one server has the name. By our reading of
+the code, a server with no toolsets stops presenting them once its latest `tools/list` has no dynamic
+tool, so until the rebuild, act takes its last one only with `server` named.
+Hint changes apply
 as their message is read, in `rev` order, whatever becomes of the message (a
-refused push, a result that came after its timeout). A skipped rev re-reads
-`tools/list` and then `toolsets/list`, which the host also reads after every
-(re)connect, adopting what the server kept open and never re-opening anything.
+refused push, a result that came after its timeout). A move between static and
+dynamic takes effect when the server's `tools/list` states it, and the tool
+list follows at its next rebuild that lists the server, whichever refresh
+brings it (a move is no reason to rebuild the tool list early). Until then the
+tool is called at either place, where the tool list shows it or where the
+server's latest list put it (RFC-014 §4.2 keeps it working where it is until
+the move applies), and
+once that rebuild has published the list, a notice says where it went. A list
+read while a rebuild is under way can undo a move that rebuild then publishes;
+neither is told, and the next rebuild puts the tool back.
+A skipped rev re-reads `tools/list` and then `toolsets/list`, which the host
+also reads after every (re)connect, adopting what the server kept open and
+never re-opening anything.
 What changed is told where it happened: after a call's own result, after the
 push that explains it, or as a notice (`kind: 'mcpl-toolsets'`, which wakes
 nothing) for a standalone `tools/hints`, a late result, an adoption, a
-recovery, or a call whose result doesn't go to the agent (one the framework or
-a module makes itself). Notices need the server's `pushEvents` grant, like any delivery. A
-new tool's first sentence is told the first time its definition appears.
-Suggestions are shown, never acted on. Each `ended` id is told once. When an
+recovery, or a call whose result may not reach the agent (a script's, a
+module's or a host's, or one the framework makes itself); an open, close or
+look made that way also shows its caller the change, unless the change has
+already gone as a notice (below). A dynamic tool's change also goes as a notice
+when it wouldn't fit whole within its result's inline cap, or when its call
+fails after the result was read. A call's change also goes as a notice, ahead of its
+result, when a later change goes to the agent before the call's caller has
+taken it, so changes are told in the order they were read (the agent's window
+can still show a call's result, a push's event, or a change its taker couldn't
+show after a change read later). The model's own call's change counts as told
+once its result is handed back: if the turn is stopped while the call is out
+(or, by our reading of the code, the agent is gone), the result is dropped and the change with it, and
+`toolsets--look` shows the state it left. Notices and reminders
+need the server's `pushEvents` grant, like any delivery; without it, a change
+that would go as a notice is dropped, and `toolsets--look` shows the state. A new tool's first sentence is told with its
+definition until text describing it has reached the model, except that, by our reading of the code, a puppet's
+open, close or look whose result the store refuses has already counted it. Suggestions are shown, never acted on. Each
+`ended` id is told once while the
+host runs (told ids are kept in memory), short of rare interleavings, such as a
+`toolsets--look` overlapping other reads of the same server, that can tell one
+twice. When an
 open toolset's announcements have left an agent's context (compressed or out
 of the window), the module's `gatherContext` restates what is open, as a
 stored `afterUser` injection (namespace `mcpl-toolsets`), at that agent's next
 start.
 
 A dynamic tool called by its prefixed name is refused, pointing at
-`toolsets--act`. Calls to an undeclared toolset's tools are refused while the
-host has that group closed (RFC-014 §5.4). Projection and surface mode are not
-implemented: a `surface` server's static tools are listed like any server's.
+`toolsets--act`, unless the tool list or the server's latest list shows it as
+static (a move waiting for its rebuild). Calls to an undeclared toolset's
+tools are refused while the host has that group closed (RFC-014 §5.4), except
+by a tool's listed name until the rebuild that publishes its move into the
+group. Projection and surface mode are not implemented: a `surface` server's
+static tools are listed like any server's.
 
 #### Per-channel conversation routing (deprecated)
 

changelog.d/mcpl-toolsets-hint-state.breaking.md

@@ -0,0 +1 @@
+- **Hosts that set `toolHints: true` on an MCPL server without granting it `pushEvents`:** the reminder that restates a server's open toolsets at an agent's next start, once their announcement has left the context, now comes only for a server granted `pushEvents`, like every other notice of its changes. Grant `pushEvents` to that server to keep the reminders.

changelog.d/mcpl-toolsets-hint-state.changed.md

@@ -0,0 +1,4 @@
+- MCPL RFC-014 tool presence (`toolHints: true`):
+  - A move between static and dynamic takes effect when the server's `tools/list` states it, not when a hint announces it, and once the next rebuild of the model's tool list that lists the server has published it, a notice says where the tool went, unless a list read during that rebuild undid the move. A move is no reason to rebuild the tool list early, whether a hint announced it or the host's own re-read found it.
+  - Each `ended` id is told once while the host runs: told ids are kept in memory, an id counts as told only once a notice or a result carrying it reached the agent, and it is forgotten once the server stops reporting it. Rare interleavings, such as a `toolsets--look` overlapping another read of the same server, can tell one twice.
+  - `toolsets--look` naming a tool shows its signature, description, class and input schema, as before; the README no longer calls that its whole definition. What look's own re-read of the server changed is in its answer when it restates everything, and otherwise told as a notice.

changelog.d/mcpl-toolsets-hint-state.fixed.md

@@ -0,0 +1,6 @@
+- MCPL RFC-014 tool presence (`toolHints: true`), fixes to how hint changes are applied and told:
+  - A `tools/list` is applied whole as its last page is read, so a hint read just after it isn't undone, and a malformed or timed-out list changes nothing. A paged list whose pages straddle a change, or a hint or `toolsets/list` entry naming a tool `tools/list` hasn't listed, is recovered from.
+  - Changes are told in the order they were read, each once: a result's change nobody shows with it is told as a notice before any later change, and a new tool's first sentence counts as shown only once text describing it reached the model. A change a caller took and then couldn't show is told when the caller finds that out, after anything told meanwhile. By our reading of the code, a puppet's open, close or look whose result the store refuses has already counted the definitions it rendered.
+  - A change that would go as a notice to a server without the `pushEvents` grant is dropped, and `toolsets--look` shows the state.
+  - A tool the operator's tool policy refuses never starts a recovery, and a tool listed twice is known by its first listing.
+  - A malformed definition no longer makes rendering throw: a description that isn't a string is left out, and a schema or a toolset's `options` nested very deep is cut short, rather than failing a notice or `toolsets--look`.

changelog.d/mcpl-toolsets-wiring.changed.md

@@ -0,0 +1 @@
+- MCPL RFC-014 tool presence (`toolHints: true`): until a move between static and dynamic reaches the model's tool list, the tool is called at either place: by its prefixed name where the tool list or the server's latest `tools/list` shows it static, and through `toolsets--act` where either shows it dynamic (RFC-014 §4.2). A dynamic tool called by its prefixed name is therefore no longer always refused. `toolsets--look` naming a tool shows the definition `toolsets--act` would check it against wherever `toolsets--act` would take it.

changelog.d/mcpl-toolsets-wiring.fixed.md

@@ -0,0 +1,7 @@
+- MCPL RFC-014 tool presence (`toolHints: true`), fixes to how the toolsets host is wired into the framework:
+  - A result's tool change goes with it only where the result reaches an agent: the model's own call, and the operator's puppet, whose call and result are stored in the agent's window. The model's own call counts as reaching it once its result is handed back. If the turn is stopped while the call is out (or, by our reading of the code, the agent is gone), the result is dropped, and the change with it, counted as told and not told again, as in 0.27.0; `toolsets--look` shows the state it left. A script's, a module's or a host's own call leaves it to a notice. A dynamic tool's change that wouldn't fit whole within its result's inline cap, or whose call fails after its result was read, goes as a notice too. A result that is structured content alone shows that content, as its JSON, before the change that goes with it.
+  - An open or close whose outcome is unknown is reported as unconfirmed rather than as not done, and names `toolsets--look`, which says when it couldn't ask the server. A selector that is present but isn't a name is refused (null reads as left out), and a refusal for a name the server doesn't have says what it has.
+  - Removing a server, or restarting it under another id or with `toolHints` off, leaves no toolset state behind. A stop or a disconnect while a `toolHints` server is still connecting ends the connect.
+  - The capability mask no longer reports `toolHints`, `toolsets` and `surface` as masked: `toolHints: false` turns hints off. Operator tool-name patterns naming a dynamic tool count as matched.
+  - Server-chosen values in the toolset host's log lines, and in the trace of a `toolsets--act` that can't be resolved, are redacted with the servers' configuration. A request kept for a late answer no longer holds a call's arguments.
+  - A programmatic `toolsets--act` that's refused is traced as `tool:failed`, as the model's own refused act already was. A tool change that can't be told for want of an agent is logged, as one without the `pushEvents` grant already was.