@animalabs/agent-framework 0.28.0 → 0.30.0

package/dist/src/mcpl/toolsets-module.d.ts

@@ -1,31 +1,8 @@
-/**
- * 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 when a server is
- * configured with `toolHints: true`; 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 type { EventResponse, Module, ModuleContext, ModuleContextInjection, ProcessState } from '../types/module.js';
 import type { ProcessEvent, ToolCall, ToolDefinition, ToolResult } from '../types/events.js';
 import { type ToolsetController, type ToolsetHub } from './toolset-host.js';
 import { type ChangeSet } from './tool-presence.js';
+import { type HostPresentation } from '../host-presentation.js';
 /** The namespace a reminder's stored injection carries. */
 export declare const TOOLSETS_REMINDER_NAMESPACE = "mcpl-toolsets";
 /** A failure whose outcome is unknown, with how to find it out. */
@@ -50,11 +27,15 @@ export declare function resolveAct(hub: ToolsetHub, input: unknown): ActTarget;
 export declare class ToolsetsModule implements Module {
     private readonly hub;
     private readonly takerFor;
+    /** The host's own toolsets (the built-in "settings" and server tabs), when the framework presents them. */
+    private readonly host;
     readonly name = "toolsets";
     /** `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: ToolsetHub, takerFor: (call: ToolCall) => ((taken: TakenChange) => void) | null);
+    constructor(hub: ToolsetHub, takerFor: (call: ToolCall) => ((taken: TakenChange) => void) | null, 
+    /** The host's own toolsets (the built-in "settings" and server tabs), when the framework presents them. */
+    host?: HostPresentation | null);
     start(_ctx: ModuleContext): Promise<void>;
     stop(): Promise<void>;
     getTools(): ToolDefinition[];
@@ -62,6 +43,14 @@ export declare class ToolsetsModule implements Module {
     /** RFC §8.3: the reminder due for this agent, stored where compile() would place it. */
     gatherContext(agentName: string): Promise<ModuleContextInjection[]>;
     handleToolCall(call: ToolCall): Promise<ToolResult>;
+    /**
+     * 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.
+     */
+    private hostCall;
+    /** What the host's own toolsets add ahead of the servers' look: everything, or one presenting server's tab. */
+    private hostLookLead;
     private toolsAt;
     /** A change set rendered without the key the caller already showed whole. */
     private renderOthers;

package/dist/src/mcpl/toolsets-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolsets-module.d.ts","sourceRoot":"","sources":["../../../src/mcpl/toolsets-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,EAAoC,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9G,OAAO,EAAS,KAAK,SAAS,EAAqB,MAAM,oBAAoB,CAAC;AAI9E,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AA+E3D,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnE;AAQD,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,CAAC;AA0EzE,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAmBtJ,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAuCrE;AAED,qBAAa,cAAe,YAAW,MAAM;IAOzC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAP3B,QAAQ,CAAC,IAAI,cAAmB;IAEhC;;gEAE4D;IAC5D,YACmB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,IAAI,EAClF;IAEE,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAE9B,QAAQ,IAAI,cAAc,EAAE,CAE3B;IAEK,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAElF;IAED,wFAAwF;IAClF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAIxE;IAEK,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBxD;IAED,OAAO,CAAC,OAAO;IAIf,6EAA6E;IAC7E,OAAO,CAAC,YAAY;YAMN,IAAI;IAwDlB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAMX,2GAA2G;YAC7F,IAAI;IAoClB,OAAO,CAAC,OAAO;IAsDf,OAAO,CAAC,QAAQ;YAWF,KAAK;CAqDpB"}
+{"version":3,"file":"toolsets-module.d.ts","sourceRoot":"","sources":["../../../src/mcpl/toolsets-module.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,EAAoC,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9G,OAAO,EAAS,KAAK,SAAS,EAAqB,MAAM,oBAAoB,CAAC;AAG9E,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AAkG3D,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnE;AAQD,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,CAAC;AA0EzE,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAmBtJ,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAuCrE;AAED,qBAAa,cAAe,YAAW,MAAM;IAOzC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,QAAQ,CAAC,IAAI,cAAmB;IAEhC;;gEAE4D;IAC5D,YACmB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,IAAI;IACpF,2GAA2G;IAC1F,IAAI,GAAE,gBAAgB,GAAG,IAAW,EACnD;IAEE,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAG;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAE9B,QAAQ,IAAI,cAAc,EAAE,CAE3B;IAEK,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAElF;IAED,wFAAwF;IAClF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAIxE;IAEK,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAkCxD;IAED;;;;OAIG;YACW,QAAQ;IAyCtB,+GAA+G;IAC/G,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,OAAO;IAIf,6EAA6E;IAC7E,OAAO,CAAC,YAAY;YAMN,IAAI;IAwDlB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAMX,2GAA2G;YAC7F,IAAI;IAoClB,OAAO,CAAC,OAAO;IAyDf,OAAO,CAAC,QAAQ;YAWF,KAAK;CAqDpB"}

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

@@ -1,30 +1,59 @@
+/**
+ * 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, 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 it made in which tools are available, unless that change already went out as a notice. toolsets--look shows what is available now.',
         inputSchema: {
@@ -40,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',
@@ -54,18 +83,31 @@ const META_TOOLS = [
     },
     {
         name: 'close',
-        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.',
+        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) {
@@ -82,7 +124,7 @@ export function withLookHint(serverId, text) {
     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 = error instanceof Error ? error.message : String(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}`));
@@ -154,7 +196,7 @@ function owner(hub, server, has, what) {
 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.join(', ')}` : 'it has none'}`;
+    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,
@@ -175,18 +217,18 @@ export function resolveAct(hub, input) {
     try {
         const args = isObj(input) ? input : {};
         checkSelectors(args);
-        const tool = str(args.tool) ?? fail('name the tool');
+        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.shownAs(tool, 'dynamic'))
-            fail(`${tool} is not a dynamic tool: ${p.toolStatus(tool)}. Call it there.`);
+            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 = hasInstances(p, ts);
         if (withInstances && !instance) {
@@ -195,23 +237,23 @@ export function resolveAct(hub, input) {
             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 = 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 };
     }
@@ -224,13 +266,17 @@ export function resolveAct(hub, input) {
 export class ToolsetsModule {
     hub;
     takerFor;
+    host;
     name = TOOLSETS_MODULE;
     /** `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) {
+    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() { }
@@ -251,7 +297,26 @@ export class ToolsetsModule {
         const args = isObj(call.input) ? call.input : {};
         try {
             checkSelectors(args);
+            // An agent shown another's tool list can't switch it: what it opened
+            // or closed would change its owner's list, or nothing it is shown.
+            const caller = call.callerAgentName;
+            const owner = caller && this.host ? this.host.ownerOf(caller) : caller;
+            if ((call.name === 'open' || call.name === 'close') && caller && owner !== caller) {
+                fail(`${caller} is shown ${owner}'s tools and can't ${call.name} a toolset; it reaches the toolsets ${owner} has open. Nothing changed.`);
+            }
+            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, take);
                 case 'act': return this.act(args);
@@ -267,6 +332,76 @@ 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() ?? [])];
     }
@@ -277,7 +412,7 @@ export class ToolsetsModule {
     // ── the tools ──
     async open(args, take) {
         const shown = take !== null;
-        let toolset = str(args.toolset);
+        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);
@@ -285,32 +420,32 @@ 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, { shown });
             }
             catch (error) {
-                return requestFailure(c.serverId, `did not open ${toolset}`, `didn't confirm opening ${toolset}`, 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, 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(', ')}`);
+                tail.push(`now unavailable: ${gone.map(suppliedValue).join(', ')}`);
             const others = this.renderOthers(c, opened.change, opened.key, shown);
             if (others)
                 tail.push(others);
@@ -324,7 +459,7 @@ export class ToolsetsModule {
         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, describeAll: !shown, seen: shown ? undefined : new Set() })];
@@ -368,7 +503,7 @@ export class ToolsetsModule {
         };
         let result;
         try {
-            result = this.lookNow(args, server, str(args.tool), shown);
+            result = this.lookNow(args, server, toolNamed(this.hub, server, args.tool), shown);
         }
         catch (error) {
             giveBack();
@@ -396,12 +531,14 @@ export class ToolsetsModule {
     }
     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}"`);
+                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();
@@ -411,14 +548,14 @@ export class ToolsetsModule {
         }
         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);
+        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) => `${o.toolset}:${o.instance}`).join(', ')}` : 'no instance is open there'}`);
+                ?? 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({ mark }));
@@ -435,8 +572,8 @@ 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: ${jsonText(d.options)}`] : []),
                 `${p.openHint(toolset)} opens it.`,
@@ -444,7 +581,7 @@ export class ToolsetsModule {
         }
         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(noToolset(c, toolset));
     }
@@ -461,13 +598,13 @@ export class ToolsetsModule {
     }
     async close(args, take) {
         const shown = take !== null;
-        const named = str(args.toolset);
+        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),
@@ -475,7 +612,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;
@@ -484,11 +621,11 @@ 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;
@@ -496,7 +633,7 @@ export class ToolsetsModule {
                 closed = await c.close(toolset, instance, { shown });
             }
             catch (error) {
-                const what = `${toolset}${instance ? `:${instance}` : ''}`;
+                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);
@@ -506,9 +643,9 @@ export class ToolsetsModule {
         }
         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);
             const text = p.render(cs, { mark: shown, describeAll: !shown }) || `${p.label(keyOf(toolset))} closed.`;
             if (take)