@animalabs/agent-framework 0.27.0 → 0.29.0

package/dist/src/mcpl/toolsets-module.js

@@ -1,31 +1,61 @@
+/**
+ * The host's own interface to MCPL dynamic tools (RFC-014 §8.2): four tools,
+ * constant and static, aggregated across every server that presents
+ * toolsets.
+ *
+ *   toolsets--open  {server?, toolset?, instance?, options?}
+ *   toolsets--act   {server?, tool, instance?, args?}
+ *   toolsets--look  {server?, toolset?, instance?, tool?}
+ *   toolsets--close {server?, toolset?, instance?}
+ *
+ * Dynamic tools never enter the API tool list: changing it rebuilds the
+ * prompt cache. They're announced in the conversation (in these tools'
+ * results, in the results of calls that changed them, in push events and in
+ * notices) and called through `toolsets--act`, which this module only
+ * resolves (resolveAct): the framework dispatches the call it resolves to
+ * down the same path as a direct call of the server's tool. The module is registered at create(),
+ * for every agent (the host's own toolsets use it too), unless a module given to create() holds
+ * the name; its tools never change after that.
+ *
+ * Its gatherContext publishes the RFC §8.3 reminder, as a stored `afterUser`
+ * injection, when an agent's earlier announcements of an open toolset have
+ * left its context (ToolsetHub.observeCompile).
+ *
+ * Ported from mcpl-cc-bridge's meta-tools.ts, the reference host.
+ */
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 import { unknownToolMessage } from '../modules/unknown-tool.js';
 import { META_TOOL_NAMES, TOOLSETS_MODULE } from './toolset-host.js';
 import { keyOf } from './tool-presence.js';
-import { checkArgs, renderToolDefinition } from './tool-signature.js';
+import { checkArgs, jsonText, renderToolDefinition } from './tool-signature.js';
+import { McplRequestError } from './server-connection.js';
+import { BUILTIN_TOOLSET } from '../host-presentation.js';
 /** The namespace a reminder's stored injection carries. */
 export const TOOLSETS_REMINDER_NAMESPACE = 'mcpl-toolsets';
 const META_TOOLS = [
     {
         name: 'open',
-        description: 'Open a toolset of an MCPL server (a game, a building mode, a card table) so its tools can be called with toolsets--act. ' +
-            'Returns what the server shows on opening and the tools available now. server may be left out when one server has the toolset, ' +
-            'and toolset when the server has only one; instance names a separate copy where a toolset allows several (two games at once); ' +
+        description: 'Open a toolset so its tools can be called with toolsets--act: the host\'s own settings and controls (toolset "settings"), ' +
+            'an MCPL server\'s tab (server alone: its tools without putting them in your tool list; a closed tab is connected again; ' +
+            'full: true puts the server back in your tool list), or a toolset an MCPL server declares (a game, a building mode, a card table: ' +
+            'server and toolset). Returns the tools available now. instance names a separate copy where a toolset allows several; ' +
             'options as toolsets--look lists them.',
         inputSchema: {
             type: 'object',
             properties: {
                 server: { type: 'string', description: 'the MCPL server id' },
-                toolset: { type: 'string' },
+                toolset: { type: 'string', description: '"settings" for the host\'s own; a server\'s toolset with server' },
                 instance: { type: 'string', description: 'a name for this copy (toolsets with instances only)' },
                 options: { type: 'object', description: 'toolset options, as toolsets--look shows them' },
+                full: { type: 'boolean', description: 'with server alone: put the server\'s tools back in your tool list' },
             },
         },
     },
     {
         name: 'act',
-        description: 'Call a tool that was announced in the conversation (a tool of an open toolset, or another dynamic tool); they are not in your tool list. ' +
+        description: 'Call a tool of an open toolset (the host\'s "settings", a server\'s tab, or a server\'s own toolset) or another dynamic tool, as announced in the conversation; they are not in your tool list. ' +
             'args are the arguments its signature shows; instance picks the open copy when several are open; server is needed only when two servers have the tool. ' +
-            'Returns the server\'s result, then any change in which tools are available.',
+            'Returns the server\'s result, then any change it made in which tools are available, unless that change already went out as a notice. toolsets--look shows what is available now.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -39,7 +69,7 @@ const META_TOOLS = [
     },
     {
         name: 'look',
-        description: 'Show what is open and what can be opened on MCPL servers, with the tools usable now: announcements earlier in the conversation may be out of date. ' +
+        description: 'Show what is open and what can be opened (the host\'s "settings", each MCPL server\'s tab, servers\' own toolsets), with the tools usable now: announcements earlier in the conversation may be out of date. ' +
             'With tool: that tool\'s full description and input schema. With toolset or instance: just that one.',
         inputSchema: {
             type: 'object',
@@ -53,18 +83,52 @@ const META_TOOLS = [
     },
     {
         name: 'close',
-        description: 'Close an open toolset or instance: its tools and its events stop. Closing a game in progress may count as leaving it.',
+        description: 'Close an open toolset or instance: its tools stop, and for a toolset the server declares, the server is told and stops its events too. Closing a game in progress may count as leaving it. ' +
+            'server alone moves a server out of your tool list into a tab (connected, its events still come), or hides its open tab; with disconnect: true it is disconnected until you open it again.',
         inputSchema: {
             type: 'object',
             properties: {
                 server: { type: 'string', description: 'the MCPL server id (may be left out when one server has the toolset open)' },
-                toolset: { type: 'string', description: 'may be left out when only one thing is open on the server' },
+                toolset: { type: 'string', description: '"settings" for the host\'s own; may be left out when only one thing is open on the server' },
                 instance: { type: 'string' },
+                disconnect: { type: 'boolean', description: 'with server alone: disconnect it as a closed tab until it is opened again' },
             },
         },
     },
 ];
 const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const selector = (v, has) => typeof v === 'string' && v !== v.trim() && v.trim() !== '' && has(v) ? v : str(v);
+const presentersOf = (hub, server) => {
+    const id = str(server);
+    if (!id)
+        return hub.presenting();
+    const c = hub.get(id);
+    return c ? [c] : [];
+};
+const toolNamed = (hub, server, v) => selector(v, (name) => presentersOf(hub, server).some((c) => !!c.presence.tool(name)));
+const toolsetNamed = (hub, server, v) => selector(v, (name) => presentersOf(hub, server).some((c) => c.presence.isDeclared(name) || c.presence.undeclaredGroups.includes(name)));
+const instanceNamed = (presenters, toolset, v) => selector(v, (name) => presenters.some((c) => c.presence.openRecords(toolset).some((o) => o.instance === name)));
+const SELECTORS = ['server', 'toolset', 'instance', 'tool'];
+function checkSelectors(args) {
+    for (const key of SELECTORS) {
+        const v = args[key];
+        if (v === undefined || v === null || str(v) !== undefined)
+            continue;
+        const got = typeof v === 'string' ? 'a blank string' : Array.isArray(v) ? 'a list' : typeof v === 'object' ? 'an object' : `a ${typeof v}`;
+        fail(`${key} must be a name, or left out; got ${got}, so nothing was done`);
+    }
+}
+/** A failure whose outcome is unknown, with how to find it out. */
+export function withLookHint(serverId, text) {
+    const said = text.trimEnd();
+    return `${said}${/[.!?]$/.test(said) ? '' : '.'} ${META_TOOL_NAMES.look} {server:"${serverId}"} asks it what's open, or says it couldn't.`;
+}
+function requestFailure(serverId, did, unconfirmed, error) {
+    const message = suppliedValue(error instanceof Error ? error.message : String(error));
+    if (error instanceof McplRequestError && error.outcome === 'not-sent')
+        return fail(`${serverId} ${did}: ${message}`);
+    return fail(withLookHint(serverId, `${serverId} ${unconfirmed}: ${message}`));
+}
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 class MetaError extends Error {
 }
@@ -106,13 +170,13 @@ function pick(hub, server) {
     if (!id) {
         if (ids.length === 1)
             return hub.get(ids[0]);
-        return fail(`name a server: ${ids.join(', ') || '(no MCPL server presents toolsets now)'}`);
+        return fail(ids.length ? `name a server: ${ids.join(', ')}` : NONE_PRESENTS);
     }
     const c = hub.get(id);
     if (!c)
         return fail(`no server "${id}" presents toolsets; the ones that do: ${ids.join(', ') || 'none'}`);
     if (!c.presence.active)
-        return fail(`${id} sends no tool hints now: its tools are in your tool list`);
+        return fail(`${id} sends no tool hints now: its tools are called directly, by name, not through ${META_TOOL_NAMES.act}`);
     return c;
 }
 /**
@@ -125,59 +189,71 @@ function owner(hub, server, has, what) {
     const owners = hub.presenting().filter(has);
     if (owners.length === 1)
         return owners[0];
-    return fail(owners.length
-        ? `${what} is on several servers (${owners.map((c) => c.serverId).join(', ')}): add server`
-        : `no server that presents toolsets has ${what}`);
+    if (owners.length)
+        return fail(`${what} is on several servers (${owners.map((c) => c.serverId).join(', ')}): add server`);
+    return fail(hub.presenting().length ? `no server that presents toolsets has ${what}: ${META_TOOL_NAMES.look} shows what they have` : NONE_PRESENTS);
+}
+const NONE_PRESENTS = 'no MCPL server presents toolsets now: MCPL tools are called directly, by name';
+function noToolset(c, toolset) {
+    const names = [...Object.keys(c.presence.declared), ...c.presence.undeclaredGroups];
+    return `${c.serverId} has no toolset "${toolset}"; ${names.length ? `it has ${names.map(nameToTypeBack).join(', ')}` : 'it has none'}`;
 }
 /**
  * Resolve a `toolsets--act` call (RFC §8.2) to the dynamic tool it calls,
  * or the reason it can't be sent. The framework then dispatches it exactly as
  * a direct call of that tool, with `_meta["mcpl/instance"]` added (RFC §5.5).
  * Refused here, before anything is sent: a tool no presenting server has, a
- * static tool (it's in the tool list), an instance that isn't named where
+ * tool neither the published list nor the server's latest tools/list puts as dynamic (RFC §4.2), an instance that isn't named where
  * several are open, a group the host has closed (RFC §5.4), and arguments
  * that don't fit the definition in force for that instance (RFC §6.1).
  */
+const hasInstances = (p, ts) => ts !== undefined && p.isDeclared(ts) && !!p.declared[ts].instances;
+/** The key whose definition act checks a call of `tool` against (RFC §6.1): an instance's own, else the toolset's, else the listed one. */
+function actKey(p, tool, instance) {
+    const ts = p.toolsetOf(tool);
+    return ts ? keyOf(ts, hasInstances(p, ts) ? instance : undefined) : keyOf('');
+}
 export function resolveAct(hub, input) {
     try {
         const args = isObj(input) ? input : {};
-        const tool = str(args.tool) ?? fail('name the tool');
+        checkSelectors(args);
+        const tool = toolNamed(hub, args.server, args.tool) ?? fail('name the tool');
         const c = owner(hub, args.server, (x) => !!x.presence.tool(tool), `a tool "${tool}"`);
         const p = c.presence;
         if (!p.tool(tool))
             fail(`${c.serverId} has no tool "${tool}": ${META_TOOL_NAMES.look} {server:"${c.serverId}"} shows what's available`);
-        if (p.presenceOf(tool) === 'static')
-            fail(`${tool} is not a dynamic tool: ${p.toolStatus(tool)}. Call it there.`);
+        if (!p.shownAs(tool, 'dynamic'))
+            fail(`${nameToTypeBack(tool)} is not a dynamic tool: ${p.toolStatus(tool)}. Call it there.`);
         if (args.args !== undefined && !isObj(args.args))
             fail('args must be an object of the tool\'s arguments');
         const callArgs = (args.args ?? {});
-        let instance = str(args.instance);
         const ts = p.toolsetOf(tool);
+        let instance = instanceNamed([c], ts, args.instance);
         const declared = ts !== undefined && p.isDeclared(ts);
-        const withInstances = declared && !!p.declared[ts].instances;
+        const withInstances = hasInstances(p, ts);
         if (withInstances && !instance) {
             // RFC §5.5: the instance rides in _meta; with exactly one open, it's that one.
             const open = p.openRecords(ts);
             if (open.length === 1)
                 instance = open[0].instance;
             else if (!open.length)
-                fail(`${tool} belongs to ${ts}, which isn't open: ${p.openHint(ts)}`);
+                fail(`${nameToTypeBack(tool)} belongs to ${nameToTypeBack(ts)}, which isn't open: ${p.openHint(ts)}`);
             else
-                fail(`several ${ts} instances are open (${open.map((o) => o.instance).join(', ')}): say which with instance`);
+                fail(`several ${nameToTypeBack(ts)} instances are open (${open.map((o) => nameToTypeBack(o.instance)).join(', ')}): say which with instance`);
         }
         if (instance && !withInstances)
-            fail(`${tool} ${ts ? `belongs to ${ts}, which has no instances` : 'belongs to no toolset'}: call it without instance`);
+            fail(`${nameToTypeBack(tool)} ${ts ? `belongs to ${nameToTypeBack(ts)}, which has no instances` : 'belongs to no toolset'}: call it without instance`);
         // RFC §5.4: the host gates calls into an undeclared group it has closed.
         if (ts && !declared && !p.isOpen(ts))
-            fail(`${tool} is in ${ts}, which isn't open: ${p.openHint(ts)}`);
+            fail(`${nameToTypeBack(tool)} is in ${nameToTypeBack(ts)}, which isn't open: ${p.openHint(ts)}`);
         // RFC §6.1: arguments are checked against the definition in force for
         // that instance: its own from hints (the legal moves of one game), else
         // the toolset's, else the listed one.
-        const key = ts ? keyOf(ts, withInstances ? instance : undefined) : keyOf('');
+        const key = actKey(p, tool, instance);
         const problem = checkArgs(p.defOf(key, tool).inputSchema, callArgs);
         if (problem) {
-            fail(`Invalid arguments for ${tool} in ${p.label(key)}: ${problem}. Nothing was sent; ` +
-                `${META_TOOL_NAMES.look} {server:"${c.serverId}", tool:"${tool}"${instance ? `, instance:"${instance}"` : ''}} shows its current definition.`);
+            fail(`Invalid arguments for ${nameToTypeBack(tool)} in ${p.label(key)}: ${problem}. Nothing was sent; ` +
+                `${META_TOOL_NAMES.look} {server:"${c.serverId}", tool:${quotedValue(tool)}${instance ? `, instance:${quotedValue(instance)}` : ''}} shows its current definition.`);
         }
         return { ok: true, serverId: c.serverId, tool, ...(instance ? { instance } : {}), args: callArgs };
     }
@@ -189,9 +265,18 @@ export function resolveAct(hub, input) {
 }
 export class ToolsetsModule {
     hub;
+    takerFor;
+    host;
     name = TOOLSETS_MODULE;
-    constructor(hub) {
+    /** `takerFor`: who shows a call's result to an agent, taking the tool
+     *  change rendered into it; null when the result may reach none, and its
+     *  change is left to a notice (RFC-014 §6.1: told once). */
+    constructor(hub, takerFor, 
+    /** The host's own toolsets (the built-in "settings" and server tabs), when the framework presents them. */
+    host = null) {
         this.hub = hub;
+        this.takerFor = takerFor;
+        this.host = host;
     }
     async start(_ctx) { }
     async stop() { }
@@ -211,11 +296,25 @@ export class ToolsetsModule {
     async handleToolCall(call) {
         const args = isObj(call.input) ? call.input : {};
         try {
+            checkSelectors(args);
+            const hosted = await this.hostCall(call.name, args, call.callerAgentName);
+            if (hosted)
+                return hosted;
+            const take = this.takerFor(call);
+            const lead = call.name === 'look' ? this.hostLookLead(args, call.callerAgentName) : null;
+            if (lead !== null) {
+                if (!this.hub.presenting().length)
+                    return textResult(lead);
+                const theirs = await this.look(args, take);
+                if (theirs.isError || typeof theirs.data !== 'string')
+                    return theirs;
+                return textResult(`${lead}\n\n${theirs.data}`);
+            }
             switch (call.name) {
-                case 'open': return await this.open(args);
+                case 'open': return await this.open(args, take);
                 case 'act': return this.act(args);
-                case 'look': return await this.look(args);
-                case 'close': return await this.close(args);
+                case 'look': return await this.look(args, take);
+                case 'close': return await this.close(args, take);
                 default: return { success: false, isError: true, error: unknownToolMessage(this.name, call.name, META_TOOLS) };
             }
         }
@@ -226,16 +325,87 @@ export class ToolsetsModule {
             return { success: false, isError: true, error: message };
         }
     }
+    /**
+     * The host's own toolsets: `toolset: "settings"` alone, or `server` alone
+     * (a server's tab), for open, close and look; a tool a host toolset has, for
+     * look. Null for everything else, which the servers' toolsets answer.
+     */
+    async hostCall(name, args, agentName) {
+        const host = this.host;
+        if (!host || !agentName || !host.active(agentName))
+            return null;
+        const server = str(args.server);
+        const toolset = str(args.toolset);
+        const instance = str(args.instance);
+        const tool = str(args.tool);
+        const builtin = toolset === BUILTIN_TOOLSET && !server && !instance;
+        const tab = !!server && !toolset && !instance && args.options === undefined;
+        if (args.full !== undefined && typeof args.full !== 'boolean')
+            fail('full must be true or false');
+        if (args.disconnect !== undefined && typeof args.disconnect !== 'boolean')
+            fail('disconnect must be true or false');
+        if (tab && !host.knows(server) && !this.hub.get(server))
+            fail(`no MCPL server "${server}" is configured here`);
+        switch (name) {
+            case 'open':
+                if (builtin)
+                    return textResult(host.openBuiltin(agentName));
+                if (tab)
+                    return textResult(await host.openServer(agentName, server, { full: args.full === true }));
+                if (args.full !== undefined)
+                    fail('full goes with server alone');
+                return null;
+            case 'close':
+                if (builtin)
+                    return textResult(host.closeBuiltin(agentName));
+                if (tab)
+                    return textResult(await host.closeServer(agentName, server, { disconnect: args.disconnect === true }));
+                if (args.disconnect !== undefined)
+                    fail('disconnect goes with server alone');
+                return null;
+            case 'look': {
+                // A host toolset's tool, with or without its server named (as act takes it).
+                if (tool && !toolset && !instance) {
+                    const shown = host.lookTool(agentName, tool, server);
+                    if (shown)
+                        return textResult(shown);
+                    return null;
+                }
+                if (builtin)
+                    return textResult(host.lookToolset(agentName, { builtin: true }));
+                // A server's tab, and every host toolset with no selector, go first in
+                // what the servers' own look says (handleToolCall adds them).
+                if (tab && !tool && !this.hub.get(server)?.presents)
+                    return textResult(host.lookToolset(agentName, { serverId: server }));
+                return null;
+            }
+            default:
+                return null;
+        }
+    }
+    /** What the host's own toolsets add ahead of the servers' look: everything, or one presenting server's tab. */
+    hostLookLead(args, agentName) {
+        const host = this.host;
+        if (!host || !agentName || !host.active(agentName))
+            return null;
+        const server = str(args.server);
+        if (str(args.toolset) || str(args.instance) || str(args.tool))
+            return null;
+        if (!server)
+            return host.catalog(agentName).join('\n');
+        return host.knows(server) ? host.lookToolset(agentName, { serverId: server }) : null;
+    }
     toolsAt(c, key) {
         return [...(c.presence.view().get(key)?.tools.values() ?? [])];
     }
     /** A change set rendered without the key the caller already showed whole. */
-    renderOthers(c, cs, key) {
-        return c.presence.render({ ...cs, changes: cs.changes.filter((ch) => ch.key !== key) });
+    renderOthers(c, cs, key, shown) {
+        return c.presence.render({ ...cs, changes: cs.changes.filter((ch) => ch.key !== key) }, { mark: shown, describeAll: !shown });
     }
     // ── the tools ──
-    async open(args) {
-        let toolset = str(args.toolset);
+    async open(args, take) {
+        const shown = take !== null;
+        let toolset = toolsetNamed(this.hub, args.server, args.toolset);
         const c = toolset && !str(args.server)
             ? owner(this.hub, undefined, (x) => x.presence.isDeclared(toolset) || x.presence.undeclaredGroups.includes(toolset), `a toolset "${toolset}"`)
             : pick(this.hub, args.server);
@@ -243,55 +413,60 @@ export class ToolsetsModule {
         const openable = [...Object.keys(p.declared), ...p.undeclaredGroups];
         if (!toolset) {
             if (openable.length !== 1)
-                fail(`${c.serverId} has ${openable.length ? `several toolsets: name one of ${openable.join(', ')}` : 'no toolsets'}`);
+                fail(`${c.serverId} has ${openable.length ? `several toolsets: name one of ${openable.map(nameToTypeBack).join(', ')}` : 'no toolsets'}`);
             toolset = openable[0];
         }
-        const instance = str(args.instance);
+        const instance = instanceNamed([c], toolset, args.instance);
         if (args.options !== undefined && !isObj(args.options))
             fail('options must be an object');
         const options = args.options;
         if (p.isDeclared(toolset)) {
             if (instance && !p.declared[toolset].instances)
-                fail(`${c.serverId}/${toolset} has no instances: open it without one`);
+                fail(`${c.serverId}/${nameToTypeBack(toolset)} has no instances: open it without one`);
             let opened;
             try {
-                opened = await c.open(toolset, instance, options);
+                opened = await c.open(toolset, instance, options, { shown });
             }
             catch (error) {
-                return fail(`${c.serverId} did not open ${toolset}: ${error instanceof Error ? error.message : String(error)}`);
+                return requestFailure(c.serverId, `did not open ${nameToTypeBack(toolset)}`, `didn't confirm opening ${nameToTypeBack(toolset)}`, error);
             }
             // RFC §5.2: opening what is open adopts it; its content says which options weren't applied.
             const blocks = [
-                { type: 'text', text: `${p.label(opened.key)}${opened.title ? ` ${opened.title}` : ''}${opened.adopted ? ' (already open)' : ''}` },
+                { type: 'text', text: `${p.label(opened.key)}${opened.title ? ` ${suppliedValue(opened.title)}` : ''}${opened.adopted ? ' (already open)' : ''}` },
                 ...asBlocks(opened.content),
             ];
-            const tail = [...p.toolBlock(opened.key, this.toolsAt(c, opened.key), { headed: false })];
+            const tail = [...p.toolBlock(opened.key, this.toolsAt(c, opened.key), { headed: false, describeAll: !shown, seen: shown ? undefined : new Set() })];
             const gone = opened.change.changes.find((ch) => ch.key === opened.key)?.gone ?? [];
             if (gone.length)
-                tail.push(`now unavailable: ${gone.join(', ')}`);
-            const others = this.renderOthers(c, opened.change, opened.key);
+                tail.push(`now unavailable: ${gone.map(suppliedValue).join(', ')}`);
+            const others = this.renderOthers(c, opened.change, opened.key, shown);
             if (others)
                 tail.push(others);
             const close = p.closeHint(opened.key);
             if (close)
                 tail.push(`${close} closes it.`);
             blocks.push({ type: 'text', text: tail.join('\n') });
+            take?.({ toolsets: c, cs: opened.change });
             return blocksResult(blocks);
         }
         if (p.undeclaredGroups.includes(toolset)) {
             // RFC §5.4: a grouping the server offers but doesn't track: the host opens it, the server isn't told.
             if (instance || options)
-                fail(`${c.serverId}/${toolset} takes no instance or options (the server doesn't declare it)`);
+                fail(`${c.serverId}/${nameToTypeBack(toolset)} takes no instance or options (the server doesn't declare it)`);
             const cs = c.setGroupOpen(toolset, true);
             const key = keyOf(toolset);
-            const lines = [`${p.label(key)} open.`, ...p.toolBlock(key, this.toolsAt(c, key), { headed: false })];
-            const others = this.renderOthers(c, cs, key);
+            const lines = [`${p.label(key)} open.`, ...p.toolBlock(key, this.toolsAt(c, key), { headed: false, describeAll: !shown, seen: shown ? undefined : new Set() })];
+            const others = this.renderOthers(c, cs, key, shown);
             if (others)
                 lines.push(others);
             lines.push(`${p.closeHint(key)} closes it.`);
+            if (take)
+                take({ toolsets: c, cs });
+            else
+                c.tell(cs);
             return textResult(lines.join('\n'));
         }
-        return fail(`${c.serverId} has no toolset "${toolset}"${openable.length ? `; it has ${openable.join(', ')}` : ''}`);
+        return fail(noToolset(c, toolset));
     }
     /**
      * act is dispatched by the framework, not here: it resolves the call
@@ -307,42 +482,80 @@ export class ToolsetsModule {
         return { success: false, isError: true, error: `${META_TOOL_NAMES.act} is dispatched by the framework; nothing was sent` };
     }
     /** look restates the present: titles and visibility are re-read from the servers first (toolsets/list). */
-    async look(args) {
+    async look(args, take) {
         const server = str(args.server);
         const targets = server ? [this.hub.get(server)].filter((c) => !!c && c.presents) : this.hub.presenting();
-        const notes = (await Promise.all(targets.map((c) => c.refreshOpen().catch(() => [])))).flat();
-        const result = this.lookNow(args, server, str(args.tool));
-        return notes.length && !result.isError && typeof result.data === 'string' ? textResult(`${result.data}\n${notes.join('\n')}`) : result;
+        const shown = take !== null;
+        const reads = await Promise.all(targets.map(async (c) => ({ c, cs: await c.refreshOpen({ shown }).catch(() => null) })));
+        const read = reads.filter((r) => r.cs !== null);
+        const unread = reads.filter((r) => r.cs === null).map(({ c }) => `${c.serverId} couldn't be asked just now: this is what the host last knew of it.`);
+        const giveBack = () => {
+            if (shown)
+                for (const { c, cs } of read)
+                    c.tell(cs);
+        };
+        let result;
+        try {
+            result = this.lookNow(args, server, toolNamed(this.hub, server, args.tool), shown);
+        }
+        catch (error) {
+            giveBack();
+            if (error instanceof MetaError && unread.length)
+                fail([error.message, ...unread].join('\n'));
+            throw error;
+        }
+        if (result.isError || typeof result.data !== 'string') {
+            giveBack();
+            return result;
+        }
+        const restates = !str(args.tool) && !str(args.toolset) && !str(args.instance);
+        if (!restates)
+            giveBack();
+        const lines = restates
+            ? read.flatMap(({ c, cs }) => {
+                const said = [...cs.suggest.map((s) => c.presence.renderSuggestion(s)), ...c.presence.untoldNotes(cs), ...cs.notes];
+                // The catalog above counted what it showed; the change's own blocks weren't shown, but stay for a notice if its taker can't show the result.
+                take?.({ toolsets: c, cs: { ...cs, blocksShown: false } });
+                return said;
+            })
+            : [];
+        lines.push(...unread);
+        return lines.length ? textResult(`${result.data}\n${lines.join('\n')}`) : result;
     }
-    lookNow(args, server, tool) {
+    lookNow(args, server, tool, mark) {
         if (!server) {
-            if (tool)
-                return this.lookTool(owner(this.hub, undefined, (c) => !!c.presence.tool(tool), `a tool "${tool}"`), tool, str(args.instance));
-            const ts = str(args.toolset);
-            const inst = str(args.instance);
+            if (tool) {
+                const c = owner(this.hub, undefined, (x) => !!x.presence.tool(tool), `a tool "${tool}"`);
+                return this.lookTool(c, tool, instanceNamed([c], c.presence.toolsetOf(tool), args.instance));
+            }
+            const ts = toolsetNamed(this.hub, undefined, args.toolset);
+            const inst = instanceNamed(this.hub.presenting(), ts, args.instance);
             if (ts || inst) {
-                const c = owner(this.hub, undefined, (x) => (ts ? x.presence.isDeclared(ts) || x.presence.undeclaredGroups.includes(ts) : true) && (!inst || x.presence.openRecords().some((o) => o.instance === inst)), ts ? `a toolset "${ts}"${inst ? ` with instance "${inst}"` : ''}` : `an open instance "${inst}"`);
-                return this.lookNow(args, c.serverId, tool);
+                const c = owner(this.hub, undefined, (x) => (ts ? x.presence.isDeclared(ts) || x.presence.undeclaredGroups.includes(ts) : true) && (!inst || x.presence.openRecords(ts).some((o) => o.instance === inst)), ts ? `a toolset "${ts}"${inst ? ` with instance "${inst}"` : ''}` : `an open instance "${inst}"`);
+                return this.lookNow(args, c.serverId, tool, mark);
             }
             const all = this.hub.presenting();
             if (!all.length)
-                return textResult('No MCPL server presents toolsets or dynamic tools now; every tool is in your tool list.');
-            return textResult(all.map((c) => c.presence.catalog()).join('\n\n'));
+                return textResult('No MCPL server presents toolsets or dynamic tools now; MCPL tools are called directly, by name.');
+            return textResult(all.map((c) => c.presence.catalog({ mark })).join('\n\n'));
         }
         const c = pick(this.hub, server);
         if (tool)
-            return this.lookTool(c, tool, str(args.instance));
+            return this.lookTool(c, tool, instanceNamed([c], c.presence.toolsetOf(tool), args.instance));
         const p = c.presence;
-        let toolset = str(args.toolset);
-        const instance = str(args.instance);
-        if (!toolset && instance)
-            toolset = p.openRecords().find((o) => o.instance === instance)?.toolset ?? fail(`no open instance "${instance}" on ${c.serverId}`);
+        let toolset = toolsetNamed(this.hub, server, args.toolset);
+        const instance = instanceNamed([c], toolset, args.instance);
+        if (!toolset && instance) {
+            const open = p.openRecords().filter((o) => o.instance !== undefined);
+            toolset = open.find((o) => o.instance === instance)?.toolset
+                ?? fail(`no open instance "${instance}" on ${c.serverId}; ${open.length ? `open: ${open.map((o) => `${nameToTypeBack(o.toolset)}:${nameToTypeBack(String(o.instance))}`).join(', ')}` : 'no instance is open there'}`);
+        }
         if (!toolset)
-            return textResult(p.catalog());
+            return textResult(p.catalog({ mark }));
         if (p.isOpen(toolset, instance) || (!instance && p.openRecords(toolset).length === 1)) {
             const rec = p.isDeclared(toolset) ? (instance ? p.openRecords(toolset).find((o) => o.instance === instance) : p.openRecords(toolset)[0]) : undefined;
             const key = keyOf(toolset, rec?.instance);
-            const lines = p.toolBlock(key, this.toolsAt(c, key), { describeAll: true, title: rec?.title });
+            const lines = p.toolBlock(key, this.toolsAt(c, key), { describeAll: true, title: rec?.title, seen: mark ? undefined : new Set() });
             const close = p.closeHint(key);
             if (close)
                 lines.push(`${close} closes it.`);
@@ -352,37 +565,39 @@ export class ToolsetsModule {
         if (d) {
             const open = p.openRecords(toolset);
             return textResult([
-                `${c.serverId}/${toolset}${d.title ? ` — ${d.title}` : ''}${d.summary ? `: ${d.summary}` : ''}`,
-                open.length ? `open: ${open.map((o) => o.instance ?? toolset).join(', ')}` : 'not open',
+                `${c.serverId}/${nameToTypeBack(toolset)}${d.title ? ` — ${suppliedValue(d.title)}` : ''}${d.summary ? `: ${suppliedValue(d.summary)}` : ''}`,
+                open.length ? `open: ${open.map((o) => nameToTypeBack(o.instance ?? toolset)).join(', ')}` : 'not open',
                 ...(d.instances ? ['several can be open at once; name each with instance'] : []),
-                ...(d.options ? [`options: ${JSON.stringify(d.options)}`] : []),
+                ...(d.options ? [`options: ${jsonText(d.options)}`] : []),
                 `${p.openHint(toolset)} opens it.`,
             ].join('\n'));
         }
         if (p.undeclaredGroups.includes(toolset)) {
             const names = p.allTools.filter((t) => p.toolsetOf(t.name) === toolset).map((t) => t.name);
-            return textResult(`${c.serverId}/${toolset}: ${names.join(', ')}; not open: ${p.openHint(toolset)} opens it.`);
+            return textResult(`${c.serverId}/${nameToTypeBack(toolset)}: ${names.map(nameToTypeBack).join(', ')}; not open: ${p.openHint(toolset)} opens it.`);
         }
-        return fail(`${c.serverId} has no toolset "${toolset}"`);
+        return fail(noToolset(c, toolset));
     }
     lookTool(c, tool, instance) {
         const p = c.presence;
         if (!p.tool(tool))
-            fail(`${c.serverId} has no tool "${tool}"`);
+            fail(`${c.serverId} has no tool "${tool}": ${META_TOOL_NAMES.look} {server:"${c.serverId}"} shows what's available`);
         const ts = p.toolsetOf(tool);
-        const where = [...p.view().entries()].filter(([, e]) => e.tools.has(tool)).map(([k]) => k);
-        const key = instance && ts ? keyOf(ts, instance) : where[0];
+        // The definition act would check, wherever act would take the tool.
+        const open = !instance && hasInstances(p, ts) ? p.openRecords(ts) : [];
+        const key = !p.shownAs(tool, 'dynamic') ? undefined : actKey(p, tool, instance ?? (open.length === 1 ? open[0].instance : undefined));
         const def = key ? p.defOf(key, tool) : p.tool(tool);
         return textResult(`${renderToolDefinition(def)}\n${p.toolStatus(tool)}`);
     }
-    async close(args) {
-        const named = str(args.toolset);
+    async close(args, take) {
+        const shown = take !== null;
+        const named = toolsetNamed(this.hub, args.server, args.toolset);
         const c = named && !str(args.server)
-            ? owner(this.hub, undefined, (x) => x.presence.isOpen(named, str(args.instance)) || x.presence.openRecords(named).length > 0, `an open toolset "${named}"`)
+            ? owner(this.hub, undefined, (x) => x.presence.isOpen(named, instanceNamed([x], named, args.instance)) || x.presence.openRecords(named).length > 0, `an open toolset "${named}"`)
             : pick(this.hub, args.server);
         const p = c.presence;
         let toolset = named;
-        let instance = str(args.instance);
+        let instance = instanceNamed([c], named, args.instance);
         if (!toolset) {
             const open = [
                 ...p.openRecords().filter((o) => !instance || o.instance === instance),
@@ -390,7 +605,7 @@ export class ToolsetsModule {
             ];
             if (open.length !== 1) {
                 fail(open.length
-                    ? `several are open on ${c.serverId}: name one of ${open.map((o) => `${o.toolset}${o.instance ? `:${o.instance}` : ''}`).join(', ')}`
+                    ? `several are open on ${c.serverId}: name one of ${open.map((o) => `${nameToTypeBack(o.toolset)}${o.instance ? `:${nameToTypeBack(o.instance)}` : ''}`).join(', ')}`
                     : `nothing is open on ${c.serverId}`);
             }
             toolset = open[0].toolset;
@@ -399,33 +614,40 @@ export class ToolsetsModule {
         if (p.isDeclared(toolset)) {
             // As open refuses one: a toolset without instances is closed without one.
             if (instance && !p.declared[toolset].instances)
-                fail(`${c.serverId}/${toolset} has no instances: close it without one`);
+                fail(`${c.serverId}/${nameToTypeBack(toolset)} has no instances: close it without one`);
             if (p.declared[toolset].instances && !instance) {
                 const open = p.openRecords(toolset);
                 if (open.length !== 1)
-                    fail(open.length ? `several ${toolset} instances are open (${open.map((o) => o.instance).join(', ')}): say which` : `${toolset} is not open`);
+                    fail(open.length ? `several ${nameToTypeBack(toolset)} instances are open (${open.map((o) => nameToTypeBack(String(o.instance))).join(', ')}): say which` : `${nameToTypeBack(toolset)} is not open`);
                 instance = open[0].instance;
             }
             let closed;
             try {
-                closed = await c.close(toolset, instance);
+                closed = await c.close(toolset, instance, { shown });
             }
             catch (error) {
-                return fail(`${c.serverId} did not close ${toolset}${instance ? `:${instance}` : ''}: ${error instanceof Error ? error.message : String(error)}`);
+                const what = `${nameToTypeBack(toolset)}${instance ? `:${nameToTypeBack(instance)}` : ''}`;
+                return requestFailure(c.serverId, `did not close ${what}`, `didn't confirm closing ${what}`, error);
             }
             const key = keyOf(toolset, instance);
-            const change = p.render(closed.change) || `${p.label(key)} closed.`;
+            const change = p.render(closed.change, { mark: shown, describeAll: !shown }) || `${p.label(key)} closed.`;
+            take?.({ toolsets: c, cs: closed.change });
             return blocksResult([...asBlocks(closed.content), { type: 'text', text: change }]);
         }
         if (p.undeclaredGroups.includes(toolset)) {
             if (instance)
-                fail(`${c.serverId}/${toolset} takes no instance (the server doesn't declare it)`);
+                fail(`${c.serverId}/${nameToTypeBack(toolset)} takes no instance (the server doesn't declare it)`);
             if (!p.isOpen(toolset))
-                fail(`${c.serverId}/${toolset} is not open`);
+                fail(`${c.serverId}/${nameToTypeBack(toolset)} is not open`);
             const cs = c.setGroupOpen(toolset, false);
-            return textResult(p.render(cs) || `${p.label(keyOf(toolset))} closed.`);
+            const text = p.render(cs, { mark: shown, describeAll: !shown }) || `${p.label(keyOf(toolset))} closed.`;
+            if (take)
+                take({ toolsets: c, cs });
+            else
+                c.tell(cs);
+            return textResult(text);
         }
-        return fail(`${c.serverId} has no toolset "${toolset}"`);
+        return fail(noToolset(c, toolset));
     }
 }
 //# sourceMappingURL=toolsets-module.js.map