@animalabs/agent-framework 0.28.0 → 0.29.0

package/src/mcpl/toolset-host.ts

@@ -24,6 +24,7 @@
  * which the toolsets module gathers at its next start as a stored
  * `afterUser` injection.
  */
+import { nameToTypeBack, quotedValue } from '../supplied-text.js';
 import { McplRequestError, type McplServerConnection, type HintRead } from './server-connection.js';
 import type { McplServerConfig } from './types.js';
 import { isToolAllowed } from './tool-policy.js';
@@ -73,6 +74,10 @@ export interface ToolsetHostDeps {
    *  where it isn't published. RFC §4.2: until its move applies, a tool
    *  keeps working where it is. */
   published?(serverId: string, tool: string): Presence | undefined;
+  /** The host's own toolsets an agent has open (the built-in one, server
+   *  tabs): each one's marker and reminder, for RFC §8.3 reminders beside the
+   *  servers' toolsets. */
+  hostOpen?(agentName: string): Array<{ marker: string; reminder: () => string; dueWhenAbsent?: boolean }>;
 }
 
 /** One server's RFC-014 state and traffic. Lives as long as the server's
@@ -381,8 +386,8 @@ export class ToolsetController {
    */
   dynamicCallRefusal(tool: string, calledAs: string): string | null {
     if (!this.presence.active || !this.presence.tool(tool) || this.presence.shownAs(tool, 'static')) return null;
-    return `There's no tool "${calledAs}" in your tool list, so nothing ran: ${tool} is a dynamic tool of ${this.serverId}, ` +
-      `called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:"${tool}", args}. ${this.presence.toolStatus(tool)}.`;
+    return `There's no tool "${calledAs}" in your tool list, so nothing ran: ${nameToTypeBack(tool)} is a dynamic tool of ${this.serverId}, ` +
+      `called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:${quotedValue(tool)}, args}. ${this.presence.toolStatus(tool)}.`;
   }
 
   /**
@@ -621,8 +626,8 @@ export class ToolsetController {
     if (!moved.length) return;
     const cs = emptyChange();
     cs.notes.push(...moved.map(({ name, to }) => to === 'dynamic'
-      ? `${name} left your tool list: it's announced when available, and called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:"${name}", args}.`
-      : `${name} is in your tool list now, as ${this.deps.listedName(this.serverId, name)}.`));
+      ? `${nameToTypeBack(name)} left your tool list: it's announced when available, and called with ${META_TOOL_NAMES.act} {server:"${this.serverId}", tool:${quotedValue(name)}, args}.`
+      : `${nameToTypeBack(name)} is in your tool list now, as ${nameToTypeBack(this.deps.listedName(this.serverId, name))}.`));
     this.deliver(cs);
   }
 }
@@ -681,8 +686,9 @@ export class ToolsetHub {
    * reminder due.
    */
   observeCompile(agentName: string, messages: readonly unknown[]): void {
+    const host = this.deps.hostOpen?.(agentName) ?? [];
     const open = this.openMarkers();
-    if (open.length === 0) {
+    if (open.length === 0 && host.length === 0) {
       this.seen.delete(agentName);
       this.due.delete(agentName);
       return;
@@ -696,6 +702,9 @@ export class ToolsetHub {
     }
     for (const marker of [...seen]) if (!open.includes(marker)) seen.delete(marker);
     this.seen.set(agentName, seen);
+    // A host toolset open across a restart was never seen here: it's due
+    // whenever a request doesn't carry its marker.
+    for (const h of host) if (h.dueWhenAbsent && !text.includes(h.marker)) missing = true;
     // Due until a request carries every marker the agent has seen again: a
     // gather that doesn't send (a preview) leaves it due for the next start.
     if (missing) this.due.add(agentName);
@@ -705,7 +714,10 @@ export class ToolsetHub {
   /** The reminder due for `agentName`, or null when none is. */
   reminderFor(agentName: string): string | null {
     if (!this.due.has(agentName)) return null;
-    const parts = this.presenting().filter((c) => this.deps.canNotify(c.serverId)).map((c) => c.presence.reminder()).filter((r): r is string => !!r);
+    const parts = [
+      ...(this.deps.hostOpen?.(agentName) ?? []).map((h) => h.reminder()),
+      ...this.presenting().filter((c) => this.deps.canNotify(c.serverId)).map((c) => c.presence.reminder()).filter((r): r is string => !!r),
+    ];
     if (parts.length === 0) return null;
     return `Open toolsets (a reminder: their earlier announcements have left your context):\n${parts.join('\n')}`;
   }

package/src/mcpl/toolsets-module.ts

@@ -13,8 +13,9 @@
  * 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.
+ * 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
@@ -22,6 +23,7 @@
  *
  * Ported from mcpl-cc-bridge's meta-tools.ts, the reference host.
  */
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 import type { EventResponse, Module, ModuleContext, ModuleContextInjection, ProcessState } from '../types/module.js';
 import type { ProcessEvent, ToolCall, ToolDefinition, ToolResult } from '../types/events.js';
 import { unknownToolMessage } from '../modules/unknown-tool.js';
@@ -29,6 +31,7 @@ import { META_TOOL_NAMES, TOOLSETS_MODULE, type ToolsetController, type ToolsetH
 import { keyOf, type ChangeSet, type ToolPresence } from './tool-presence.js';
 import { checkArgs, jsonText, renderToolDefinition, type HintedTool } from './tool-signature.js';
 import { McplRequestError } from './server-connection.js';
+import { BUILTIN_TOOLSET, type HostPresentation } from '../host-presentation.js';
 
 /** The namespace a reminder's stored injection carries. */
 export const TOOLSETS_REMINDER_NAMESPACE = 'mcpl-toolsets';
@@ -37,24 +40,26 @@ const META_TOOLS: ToolDefinition[] = [
   {
     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); ' +
+      '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. ' +
+      '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: {
@@ -71,7 +76,7 @@ const META_TOOLS: ToolDefinition[] = [
   {
     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. ' +
+      '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',
@@ -85,13 +90,15 @@ const META_TOOLS: ToolDefinition[] = [
   },
   {
     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' },
       },
     },
   },
@@ -99,6 +106,21 @@ const META_TOOLS: ToolDefinition[] = [
 
 const str = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
 
+const selector = (v: unknown, has: (name: string) => boolean): string | undefined =>
+  typeof v === 'string' && v !== v.trim() && v.trim() !== '' && has(v) ? v : str(v);
+const presentersOf = (hub: ToolsetHub, server: unknown): ToolsetController[] => {
+  const id = str(server);
+  if (!id) return hub.presenting();
+  const c = hub.get(id);
+  return c ? [c] : [];
+};
+const toolNamed = (hub: ToolsetHub, server: unknown, v: unknown): string | undefined =>
+  selector(v, (name) => presentersOf(hub, server).some((c) => !!c.presence.tool(name)));
+const toolsetNamed = (hub: ToolsetHub, server: unknown, v: unknown): string | undefined =>
+  selector(v, (name) => presentersOf(hub, server).some((c) => c.presence.isDeclared(name) || c.presence.undeclaredGroups.includes(name)));
+const instanceNamed = (presenters: readonly ToolsetController[], toolset: string | undefined, v: unknown): string | undefined =>
+  selector(v, (name) => presenters.some((c) => c.presence.openRecords(toolset).some((o) => o.instance === name)));
+
 const SELECTORS = ['server', 'toolset', 'instance', 'tool'] as const;
 
 function checkSelectors(args: Record<string, unknown>): void {
@@ -117,7 +139,7 @@ export function withLookHint(serverId: string, text: string): string {
 }
 
 function requestFailure(serverId: string, did: string, unconfirmed: string, error: unknown): never {
-  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}`));
 }
@@ -194,7 +216,7 @@ const NONE_PRESENTS = 'no MCPL server presents toolsets now: MCPL tools are call
 
 function noToolset(c: ToolsetController, toolset: string): string {
   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'}`;
 }
 
 /** What a `toolsets--act` call resolves to: the server's tool, its instance and arguments. */
@@ -221,35 +243,35 @@ export function resolveAct(hub: ToolsetHub, input: unknown): ActTarget {
   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.`);
+    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 ?? {}) as Record<string, unknown>;
-    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) {
       // 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!)}`);
-      else fail(`several ${ts} instances are open (${open.map((o) => o.instance).join(', ')}): say which with instance`);
+      else if (!open.length) fail(`${nameToTypeBack(tool)} belongs to ${nameToTypeBack(ts!)}, which isn't open: ${p.openHint(ts!)}`);
+      else 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`);
+    if (instance && !withInstances) 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)}`);
+    if (ts && !declared && !p.isOpen(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 };
   } catch (error) {
@@ -267,6 +289,8 @@ export class ToolsetsModule implements Module {
   constructor(
     private readonly hub: ToolsetHub,
     private readonly takerFor: (call: ToolCall) => ((taken: TakenChange) => void) | null,
+    /** The host's own toolsets (the built-in "settings" and server tabs), when the framework presents them. */
+    private readonly host: HostPresentation | null = null,
   ) {}
 
   async start(_ctx: ModuleContext): Promise<void> {}
@@ -291,7 +315,16 @@ export class ToolsetsModule implements Module {
     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, take);
         case 'act': return this.act(args);
@@ -307,6 +340,62 @@ export class ToolsetsModule implements Module {
     }
   }
 
+  /**
+   * 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 async hostCall(name: string, args: Record<string, unknown>, agentName: string | undefined): Promise<ToolResult | null> {
+    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. */
+  private hostLookLead(args: Record<string, unknown>, agentName: string | undefined): string | null {
+    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;
+  }
+
   private toolsAt(c: ToolsetController, key: string): HintedTool[] {
     return [...(c.presence.view().get(key)?.tools.values() ?? [])];
   }
@@ -320,36 +409,36 @@ export class ToolsetsModule implements Module {
 
   private async open(args: Record<string, unknown>, take: ((taken: TakenChange) => void) | null): Promise<ToolResult> {
     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);
     const p = c.presence;
     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'}`);
+      if (openable.length !== 1) 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 as Record<string, unknown> | undefined;
 
     if (p.isDeclared(toolset)) {
-      if (instance && !p.declared[toolset]!.instances) fail(`${c.serverId}/${toolset} has no instances: open it without one`);
+      if (instance && !p.declared[toolset]!.instances) fail(`${c.serverId}/${nameToTypeBack(toolset)} has no instances: open it without one`);
       let opened: Awaited<ReturnType<ToolsetController['open']>>;
       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: Block[] = [
-        { 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<string>() })];
       const gone = opened.change.changes.find((ch) => ch.key === opened.key)?.gone ?? [];
-      if (gone.length) tail.push(`now unavailable: ${gone.join(', ')}`);
+      if (gone.length) 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);
@@ -360,7 +449,7 @@ export class ToolsetsModule implements Module {
     }
     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)`);
+      if (instance || options) 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<string>() })];
@@ -400,7 +489,7 @@ export class ToolsetsModule implements Module {
     };
     let result: ToolResult;
     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();
       if (error instanceof MetaError && unread.length) fail([error.message, ...unread].join('\n'));
@@ -426,13 +515,16 @@ export class ToolsetsModule implements Module {
 
   private lookNow(args: Record<string, unknown>, server: string | undefined, tool: string | undefined, mark: boolean): ToolResult {
     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)),
+          (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);
@@ -442,14 +534,14 @@ export class ToolsetsModule implements Module {
       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));
+    if (tool) 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 }));
     if (p.isOpen(toolset, instance) || (!instance && p.openRecords(toolset).length === 1)) {
@@ -464,8 +556,8 @@ export class ToolsetsModule implements Module {
     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.`,
@@ -473,7 +565,7 @@ export class ToolsetsModule implements Module {
     }
     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!));
   }
@@ -491,13 +583,13 @@ export class ToolsetsModule implements Module {
 
   private async close(args: Record<string, unknown>, take: ((taken: TakenChange) => void) | null): Promise<ToolResult> {
     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),
@@ -505,7 +597,7 @@ export class ToolsetsModule implements Module {
       ];
       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;
@@ -513,17 +605,17 @@ export class ToolsetsModule implements Module {
     }
     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`);
+      if (instance && !p.declared[toolset!]!.instances) 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`);
+        if (open.length !== 1) 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: Awaited<ReturnType<ToolsetController['close']>>;
       try {
         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);
@@ -532,8 +624,8 @@ export class ToolsetsModule implements Module {
       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)`);
-      if (!p.isOpen(toolset!)) fail(`${c.serverId}/${toolset} is not open`);
+      if (instance) fail(`${c.serverId}/${nameToTypeBack(toolset!)} takes no instance (the server doesn't declare it)`);
+      if (!p.isOpen(toolset!)) 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) take({ toolsets: c, cs });

package/src/mcpl/transport.ts

@@ -19,9 +19,10 @@
  */
 
 import { spawn, type ChildProcess } from 'node:child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import type { Readable } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
+import { escapeLineSeparators, readLines } from '../line-reader.js';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
@@ -325,16 +326,18 @@ export class StdioTransport extends McplTransport {
     });
   }
 
+  private readonly stopLines: () => void;
+
   private constructor(
     private readonly child: ChildProcess,
-    private readonly rl: ReadlineInterface,
+    stdout: Readable,
     /** The server this child serves, named in its stderr lines and in what
      *  its reaping reports. */
     serverId: string,
   ) {
     super(serverId);
 
-    this.rl.on('line', (line: string) => this.pushLine(line));
+    this.stopLines = readLines(stdout, (line) => this.pushLine(line));
 
     // Stitch stderr chunks into whole lines (a chunk can split a line, and a
     // character's bytes), and keep the stream's last characters for
@@ -383,12 +386,7 @@ export class StdioTransport extends McplTransport {
       });
     };
     this.child.stdin?.on('error', endOnPipeError);
-    // On the stream itself, since close() closes readline, which takes its own
-    // listener off the stream. While readline is open, its listener, which
-    // came first, re-emits the error on the interface, where an empty
-    // listener absorbs that copy.
     this.child.stdout?.on('error', endOnPipeError);
-    this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
     // stderr carries diagnostics only: a read error on it is reported, to the
     // listeners or else in the log, and never thrown. It ends nothing once
     // the connection is wired; during a handshake the listener is the
@@ -453,8 +451,7 @@ export class StdioTransport extends McplTransport {
         resolve();
       });
     });
-    const rl = createInterface({ input: child.stdout! });
-    return new StdioTransport(child, rl, config.id);
+    return new StdioTransport(child, child.stdout!, config.id);
   }
 
   writeLine(json: string): void {
@@ -462,7 +459,7 @@ export class StdioTransport extends McplTransport {
     // transport is ending it.
     if (this.pipeError) return;
     // stdin may be gone if the child died between the closed-check and here.
-    this.child.stdin?.write(json + '\n');
+    this.child.stdin?.write(escapeLineSeparators(json) + '\n');
   }
 
   private closing: Promise<void> | null = null;
@@ -492,7 +489,7 @@ export class StdioTransport extends McplTransport {
 
   private async reap(): Promise<void> {
     this.markClosed({ reason: 'closed by host' });
-    this.rl.close();
+    this.stopLines();
     await this.terminate();
   }
 
@@ -696,7 +693,7 @@ export class WebSocketTransport extends McplTransport {
 
   writeLine(json: string): void {
     if (this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(json);
+      this.ws.send(escapeLineSeparators(json));
     }
   }
 
@@ -830,7 +827,7 @@ const SERVER_CONFIG_BOOLEANS: Record<BooleanSetting, string> = {
   inheritEnv: 'true passes the server the host\'s whole environment, and false or leaving it out passes only the allowlisted and LC_* host variables',
   reconnect: 'true retries in the background when the server can\'t be reached or its connection drops, and false or leaving it out doesn\'t',
   allowHostCommands: 'true lets the server run the host\'s admin commands, such as undo, hide, unstick and quiesce, and false or leaving it out refuses them',
-  toolHints: 'true advertises MCPL tool hints (RFC-014), so the server\'s dynamic tools are announced in the conversation and called through toolsets--act, and false or leaving it out lists every tool as before',
+  toolHints: 'true advertises MCPL tool hints (RFC-014) to an MCPL server, so its dynamic tools are announced in the conversation and called through toolsets--act; leaving it out does the same wherever the name toolsets is free; false lists every tool as before and advertises none',
 };
 
 /**
@@ -849,6 +846,13 @@ export function assertServerConfigBooleans(config: McplServerConfig): void {
     if (setting === 'inheritEnv' && dialsNetwork(config)) continue;
     assertBooleanSetting(`MCPL server "${config.id}" ${setting}`, config[setting], whatTrueDoes);
   }
+  // Not a boolean, but read the same way: a value that isn't one of the
+  // three would otherwise be taken for the default.
+  const presentation = (config as { presentation?: unknown }).presentation;
+  if (presentation !== undefined && presentation !== null && presentation !== 'full' && presentation !== 'tab' && presentation !== 'closed-tab') {
+    const kind = typeof presentation === 'string' ? 'another string' : Array.isArray(presentation) ? 'a list' : typeof presentation;
+    throw new Error(`MCPL server "${config.id}" presentation must be "full", "tab" or "closed-tab" (or left out for full), not ${kind}`);
+  }
 }
 
 /**